JenniferSoft Design Docs

Appearance

Tabs ​

탭(Tabs) 컴포넌트는 사용자가 키보드나 마우스를 사용하여 여러 개의 콘텐츠 패널 중 하나를 선택하고 전환할 수 있도록 하는 요소입니다. 각 탭은 특정 패널을 대표하며, 클릭 또는 선택 시 해당 패널의 내용이 표시됩니다.

기본 사용법 ​

vue
<template>
    <tabs
        :active-tab="activeTab"
        :tabs="tabs"
        @select:tab="handleSelectTab"
        @focus:tab="handleFocusTab"
    />
    <div>{{ activeTab }}</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { Tabs } from '@jennifersoft/vue-components-v2';

const tabs = [
    { tabKey: 'tab1', label: 'Tab 1', tooltip: { text: '툴팁 내용' } },
    {
        tabKey: 'tab2',
        label: 'Tab 2 Tab 2 Tab 2',
        tooltip: { text: '툴팁 내용' },
    },
    {
        tabKey: 'tab3',
        label: 'Tab 3',
        icon: ICON_TYPE.pod,
        tooltip: { text: '툴팁 내용' },
    },
    {
        tabKey: 'tab4',
        label: 'Tab 4',
        badgeContent: 10,
        tooltip: { text: '툴팁 내용' },
    },
    {
        tabKey: 'tab5',
        label: 'Tab 5',
        badgeContent: 10,
        icon: ICON_TYPE.pod,
        tooltip: { text: '툴팁 내용' },
    },
    {
        tabKey: 'tab6',
        label: 'Tab 6',
        disabled: true,
        badgeContent: 10,
        icon: ICON_TYPE.pod,
    },
];
const activeTab = ref('tab1');

const handleSelectTab = (key) => {
    activeTab.value = key;
};
const handleFocusTab = (key) => {
    console.log('Tab focused:', key);
};
</script>

Props ​

Tabs 컴포넌트 ​

Prop 이름타입필수 여부기본값설명
activeTabstring | number | symbolYes-현재 선택된 탭의 키
tabsTabItem[]Yes-탭 아이템 배열
tabIdentifierstringNo'tabs'탭의 고유 키를 생성할 때 사용되는 접두사 식별자

tabIdentifier 는 tabs props가 변경되었지만 tab key가 그대로 유지되는 경우 indicator가 제대로 작동하지 않거나 Tab 컴포넌트 자체가 제대로 업데이트 되지 않는 현상을 방지하기 위한 추가 식별자입니다. Tabs 컴포넌트에서는 기본값이 'tabs' 입니다.

TabItem 인터페이스 ​

속성타입필수 여부설명
tabKeystring | number | symbolYes탭을 식별하는 고유 키
labelstringYes탭에 표시될 텍스트
disabledbooleanNo탭 비활성화 여부
tooltipTooltipPropsNo탭에 표시될 툴팁
iconIconTypesNo탭에 표시될 아이콘
badgeContentnumberNo배지에 표시될 숫자
contextKeyanyNo탭의 컨텍스트 키

Example ​

tab1

Events ​

이벤트 이름파라미터설명
select:tabtabKey: string | number | symbol탭이 선택되었을 때 발생
focus:tabtabKey: string | number | symbol탭이 포커스되었을 때 발생

접근성 ​

  • 키보드 탐색이 지원됩니다
  • 비활성화된 탭은 disabled 속성이 적용됩니다

Tab Contraction ​

Tabs는 고수준 편의 래퍼(Tabs 컴포넌트) 외에도, 더 유연한 조합형 API를 제공합니다. 이 계약을 TabContraction이라고 하며, 아래 세 부분으로 구성됩니다.

  • [TabList]
  • [Tab]
  • [contextKey]

TabList ​

  • 개요
    • Tab 항목을 감싸는 리스트 컨테이너입니다.
    • 키보드 내비게이션, 인디케이터(Primary) 등을 관리합니다.

Props ​

Prop 이름타입필수 여부기본값설명
selectedKeystring | number | symbolYes-현재 선택된 탭의 키
contextKeystring | InjectionKey<TabContraction['context']>No'tabContext'탭 그룹 컨텍스트 키
type'primary' | 'secondary'No'primary'탭 리스트 스타일

Events ​

이벤트 이름파라미터설명
select:tabtabKey: string | number | symbol탭이 선택되었을 때 발생
focus:tabtabKey: string | number | symbol탭이 포커스되었을 때

Tab ​

Props ​

Prop 이름타입필수 여부기본값설명
contextKeystring | InjectionKey<TabContraction['context']>No-탭 컨텍스트 키
tabKeystring | number | symbolYes-탭 고유 키
labelstringYes-탭 라벨
disabledbooleanNofalse비활성화 여부
tooltipTooltipPropsNo-툴팁
iconIconTypesNo-아이콘
badgeContentnumberNo-배지 숫자

contextKey ​

  • 동일 화면에 서로 다른 탭 그룹이 공존할 때 상호 간섭을 막기 위해 사용합니다.
  • const contextKey = Symbol('tabContext') 형태로 정의 후 TabList와 각 Tab에 동일하게 전달하세요.

Context API ​

이름타입설명
selectedKeyRef<string | number | symbol>현재 선택된 탭 키
focusedKeyRef<string | number | symbol | null>현재 포커스된 탭 키
tabElemMapMap<string | number | symbol, HTMLElement>탭 키와 엘리먼트 매핑
tabOrder(string | number | symbol)[]탭 렌더링 및 탐색 순서
selectTab(key: string | number | symbol) => void지정 키를 선택
focusTab(key: string | number | symbol) => void지정 키로 포커스 이동
register(key: string | number | symbol, el: HTMLElement) => void탭 요소 등록

Tabs 래퍼와의 관계 ​

  • Tabs 컴포넌트는 위의 TabList + Tab을 조합하여 사용하기 쉬운 고수준 래퍼입니다.
  • tabIdentifier는 tabs 배열이 갱신될 때 인디케이터/렌더링 동기화를 돕는 보조 식별자입니다.

예시: 조합형 사용(Primary) ​

vue
<template>
  <tab-list
    :selected-key="active"
    :context-key="contextKey"
    @select:tab="onSelect"
    @focus:tab="onFocus"
  >
    <tab :context-key="contextKey" tab-key="tab1" label="Tab 1" />
    <tab :context-key="contextKey" tab-key="tab2" label="Tab 2" />
    <tab :context-key="contextKey" tab-key="tab3" label="Tab 3" />
  </tab-list>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { TabList, Tab } from '@jennifersoft/vue-components-v2';

const contextKey = Symbol('tabContext');
const active = ref('tab1');

const onSelect = (key: string | number | symbol) => {
  active.value = key as any;
};
const onFocus = (key: string | number | symbol) => {
  console.log('focus', key);
};
</script>