Tabs#

콘텐츠를 탭으로 구분하여 표시하는 컴포넌트입니다.

Live Preview#

TabPane(
  index: 0,
  labels: ['Account', 'Password'],
  children: [
    text('Account settings'),
    text('Password settings'),
  ],
)

TabPane(
  index: 0,
  labels: ['Account', 'Password'],
  children: [
    text('Account settings'),
    text('Password settings'),
  ],
)

사용 시기 (When to Use)#

이 컴포넌트를 사용하세요:

• 관련된 콘텐츠를 여러 패널로 나누어 전환할 때
• 같은 맥락의 다른 뷰를 제공할 때 (개요/상세/리뷰 등)
• 페이지 이동 없이 콘텐츠를 전환할 때

대신 다른 컴포넌트를 사용하세요:

• Accordion: 모든 섹션을 한 페이지에서 펼치고 접을 때
• Navigation: 앱의 주요 페이지 간 이동일 때
• Select: 옵션 선택이 목적이고 관련 콘텐츠 패널이 없을 때

기본 사용법 (Basic Usage)#

Tabs(
  onChanged: handleTabChange,
  tabs: [
    Tab(label: '개요'),
    Tab(label: '리뷰'),
    Tab(label: '관련 상품'),
  ],
  children: [
    OverviewPanel(),
    ReviewPanel(),
    RelatedProductsPanel(),
  ],
)

// 컨트롤러 사용
final tabController = TabController(length: 3);

Tabs(
  controller: tabController,
  tabs: [
    Tab(label: '탭 1'),
    Tab(label: '탭 2'),
    Tab(label: '탭 3'),
  ],
  children: [Tab1Content(), Tab2Content(), Tab3Content()],
)

Tabs(
  onChanged: handleTabChange,
  tabs: [
    Tab(label: '개요'),
    Tab(label: '리뷰'),
    Tab(label: '관련 상품'),
  ],
  children: [
    OverviewPanel(),
    ReviewPanel(),
    RelatedProductsPanel(),
  ],
)

Props / Parameters#

스타일 시스템 (Style System)#

Tabs 의 모든 chrome / dimensional / nested-slot 오버라이드는 CoreTabsStyle<Clr> 단일 슬롯으로 흐릅니다 (Epic #1302 원칙 6/7/8). 시맨틱 enum (variant) 과 behaviour (tabs / index / onChanged / swipeable) 는 위젯/컴포넌트 파라미터로 직접 전달합니다.

시맨틱 vs 스타일#

• 시맨틱 enum / behaviour: 위젯/컴포넌트 파라미터로 직접 (tabs, index, onChanged, variant, swipeable, padding)
• chrome / dimensional / 슬롯 스타일: CoreTabsStyle 한 곳으로 (activeIndicatorColor / activeIndicatorThickness / activeIndicatorRadius / tabBarBackgroundColor / tabBarPaddingH / tabBarPaddingV / tabGap / tabButtonStyle / contentTextStyle)

Resolve chain#

design system default for tabs
  → CoreTabsTheme.style                        // 프로젝트 공통
  → parent component slot override
  → widget.tabsStyle                           // 인스턴스별

각 nested 슬롯 스타일 (tabButtonStyle / contentTextStyle) 은 자기 컴포넌트의 자체 resolve chain 으로 다시 한 번 머지됩니다.

슬롯 매핑 (CoreTabsStyle 9 필드)#

Migration#

기존 TabsTheme 의 평면 chrome (backgroundColor / borderRadius / containerPadding / tabPadding / activeColor / inactiveColor) 은 호환을 위해 유지되지만, 새 코드는 tabsStyle 슬롯을 사용하세요:

사용 예 (Flutter)#

Tabs(
  index: currentTabIndex,
  onChanged: (index) => setState(() => currentTabIndex = index),
  labels: ['Account', 'Password'],
  tabsStyle: CoreTabsStyle(
    activeIndicatorColor: Colors.blue,
    activeIndicatorRadius: 8,
    tabBarBackgroundColor: Color(0xFFF7F7F7),
    tabBarPaddingH: 12,
    tabBarPaddingV: 6,
    tabGap: 4,
  ),
)

사용 예 (Web)#

TabList(
  index: currentTabIndex,
  onChanged: handleChange,
  labels: ['Account', 'Password'],
  tabsStyle: CoreTabsStyle<CoreColor>(
    activeIndicatorThickness: 2,
    tabBarPaddingH: 16,
    tabBarPaddingV: 8,
  ),
)

변형 (Variants)#

라인 탭#

TabPane(
  index: 0,
  labels: ['Account', 'Password'],
  children: [
    text('Account settings'),
    text('Password settings'),
  ],
)

TabPane(
  index: 0,
  labels: ['Account', 'Password'],
  children: [
    text('Account settings'),
    text('Password settings'),
  ],
)

박스 탭#

TabPane(
  index: 0,
  labels: ['Account', 'Password'],
  children: [
    text('Account settings'),
    text('Password settings'),
  ],
)

TabPane(
  index: 0,
  labels: ['Account', 'Password'],
  children: [
    text('Account settings'),
    text('Password settings'),
  ],
)

필 탭#

TabPane(
  index: 0,
  labels: ['Account', 'Password'],
  children: [
    text('Account settings'),
    text('Password settings'),
  ],
)

TabPane(
  index: 0,
  labels: ['Account', 'Password'],
  children: [
    text('Account settings'),
    text('Password settings'),
  ],
)

아이콘 포함#

Tab(
  label: '설정',
  icon: Icon(Icons.settings),
)

비활성화 탭#

Tab(label: '준비 중', enabled: false)

동작 스펙 (Behavior)#

탭 전환#

• 탭 클릭 시 해당 콘텐츠 패널이 즉시 표시
• 이전 패널은 숨겨지고 선택된 패널만 렌더링
• onChanged 콜백으로 탭 전환 이벤트 감지

TabPane — 고급 탭#

드래그 앤 드롭으로 탭 순서를 변경할 수 있는 고급 탭 컨테이너입니다.

TabPane<MyData>(
  data: tabItems,
  selectedIndex: currentIndex,
  onFocusChanged: handleTabChange,
  onSorted: handleReorder,
  builder: (data) => TabChild(
    tab: Text(data.label),
    child: data.content,
  ),
)

• 탭이 많아지면 자동으로 스크롤 가능 (fade edge 표시)
• leading, trailing 위젯으로 탭 바에 추가 컨트롤 배치

테마 설정#

TabsTheme(
  backgroundColor: Colors.grey[100],
  activeColor: Colors.blue,
  inactiveColor: Colors.grey,
  expand: true,  // 탭이 전체 너비를 채움
)

사용 가이드라인 (Usage Guidelines)#

✅ Do#

Tabs(
  tabs: [
    Tab(label: '개요'),
    Tab(label: '리뷰'),
    Tab(label: '사양'),
  ],
  children: [overviewPanel, reviewPanel, specPanel],
)

❌ Don't#

Tabs(
  tabs: [
    Tab(label: '제품의 전반적인 개요 및 소개'),
    Tab(label: '사용자 리뷰 및 평가'),
  ],
  children: [overviewPanel, reviewPanel],
)

✅ Do#

Tabs(
  tabs: [
    Tab(label: '기본 정보'),
    Tab(label: '보안 설정'),
    Tab(label: '알림 설정'),
  ],
  children: [profileForm, securityForm, notificationForm],
)

❌ Don't#

Tabs(
  tabs: [
    Tab(label: '프로필'),
    Tab(label: '결제 내역'),
    Tab(label: '고객센터'),
  ],
  children: [profile, payments, support],
)

✅ Do#

Tab(
  label: '분석 (프리미엄)',
  enabled: false,
  icon: Icon(Icons.lock),
)

❌ Don't#

Tab(label: '분석', enabled: false)

접근성 (Accessibility)#

키보드 인터랙션#

스크린 리더#

• Flutter: 탭 역할과 현재 선택 상태가 자동 전달. "탭 2/5, 선택됨" 형태로 읽힘
• Web: role="tab", role="tabpanel", aria-selected, data-state 적용

ARIA 속성#

<div role="tablist">
  <button role="tab" aria-selected="true" data-state="active">탭 1</button>
  <button role="tab" aria-selected="false" data-state="inactive">탭 2</button>
</div>
<div role="tabpanel" data-state="active">콘텐츠 1</div>

크로스 플랫폼 차이점 (Platform Differences)#

v3.0부터 기본 API (enabled, onChanged 등)가 통일되었습니다. 아래는 플랫폼 고유 차이점만 나열합니다.

관련 컴포넌트 (Related Components)#

• Accordion: 접고 펼 수 있는 콘텐츠 섹션. 모든 섹션을 동시에 볼 수 있어야 할 때 적합
• Navigation: 앱의 주요 섹션 간 이동. 탭과 달리 URL이 변경됨

조합 예제#

// 제품 상세 페이지 패턴
Card(
  header: CardHeader(title: product.name),
  body: CardBody(
    child: Tabs(
      tabs: [
        Tab(label: '설명', icon: Icon(Icons.description)),
        Tab(label: '사양', icon: Icon(Icons.list)),
        Tab(label: '리뷰', icon: Icon(Icons.star)),
      ],
      children: [
        DescriptionPanel(product: product),
        SpecificationsPanel(product: product),
        ReviewsPanel(productId: product.id),
      ],
    ),
  ),
)