Menubar#

데스크탑 애플리케이션 스타일의 상단 가로 메뉴 바 컴포넌트입니다. 중첩 메뉴와 키보드 탐색을 지원합니다.

Live Preview#

Menubar([
  MenuItem([text('File')]),
  MenuItem([text('Edit')]),
  MenuItem([text('View')]),
])

Card(
  child: Row(
    children: [
      TextButton(onPressed: () {}, child: Text('File')),
      TextButton(onPressed: () {}, child: Text('Edit')),
      TextButton(onPressed: () {}, child: Text('View')),
    ],
  ),
)

사용 시기 (When to Use)#

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

• IDE, 문서 편집기, 데스크탑 앱처럼 파일/편집/보기 스타일의 메뉴 바가 필요할 때
• 많은 기능을 계층적 메뉴 구조로 정리해야 할 때
• 키보드 단축키와 함께 메뉴 항목을 표시할 때

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

• Navigation: 페이지 간 이동을 위한 네비게이션 메뉴에
• DropdownMenu: 단일 버튼의 드롭다운 액션 목록에
• Tabs: 동일 화면 내 콘텐츠 섹션 전환에

기본 사용법 (Basic Usage)#

// 기본 메뉴 바
Menubar(
  onSelect: handleMenubarSelect,
  items: [
    MenubarItem(
      label: '파일',
      menu: [
        MenubarMenu(value: 'new', label: '새 파일'),
        MenubarMenu(value: 'open', label: '열기'),
        MenubarSeparator(),
        MenubarMenu(value: 'save', label: '저장'),
        MenubarMenu(value: 'saveAs', label: '다른 이름으로 저장'),
        MenubarSeparator(),
        MenubarMenu(value: 'exit', label: '종료'),
      ],
    ),
    MenubarItem(
      label: '편집',
      menu: [
        MenubarMenu(value: 'undo', label: '실행 취소'),
        MenubarMenu(value: 'redo', label: '다시 실행'),
        MenubarSeparator(),
        MenubarMenu(value: 'cut', label: '잘라내기'),
        MenubarMenu(value: 'copy', label: '복사'),
        MenubarMenu(value: 'paste', label: '붙여넣기'),
      ],
    ),
    MenubarItem(
      label: '보기',
      menu: [
        MenubarMenu(value: 'zoomIn', label: '확대'),
        MenubarMenu(value: 'zoomOut', label: '축소'),
        MenubarMenu(value: 'resetZoom', label: '기본 배율'),
      ],
    ),
  ],
)

Menubar(
  onSelect: handleMenubarSelect,
  items: [
    MenubarItem(
      label: '파일',
      menu: [
        MenubarMenu(value: 'new', label: '새 파일'),
        MenubarMenu(value: 'open', label: '열기'),
        MenubarSeparator(),
        MenubarMenu(value: 'save', label: '저장'),
      ],
    ),
    MenubarItem(
      label: '편집',
      menu: [
        MenubarMenu(value: 'undo', label: '실행 취소'),
        MenubarMenu(value: 'redo', label: '다시 실행'),
      ],
    ),
  ],
)

Props / Parameters#

Menubar#

스타일 시스템 (Style System)#

DropdownMenu / Menu / Menubar / ContextMenu 의 모든 chrome / dimensional / nested-slot 오버라이드는 공통 CoreDropdownMenuStyle<Clr, Shadow> 단일 슬롯으로 흐릅니다 (Epic #1302 원칙 6/7/8). 4 종류 위젯이지만 chrome 은 모두 동일 Style 클래스로 받습니다.

시맨틱 vs 스타일#

• 시맨틱 / behaviour: 위젯 파라미터로 직접 (border, popoverOffset …)
• chrome / dimensional / 슬롯 스타일: CoreDropdownMenuStyle 한 곳으로 (popoverStyle / triggerStyle / itemStyle / headerTextStyle + flat separatorColor / separatorThickness / separatorIndent)
• 변형 교체: asChild — 트리거를 직접 위젯으로 주입

Resolve chain#

design system default for menubar
  → CoreDropdownMenuTheme.style                  // 프로젝트 공통
  → parent component slot override
  → widget.dropdownMenuStyle                     // 인스턴스별

Menubar 의 dropdownMenuStyle 은 Data.maybeOf<MenubarState> 를 통해 자식 submenu 팝업으로도 자동 전파됩니다.

슬롯 매핑 (CoreDropdownMenuStyle 7 필드)#

Migration — 옛 평면 필드 → 새 위치 매핑#

사용 예 (Flutter)#

Menubar(
  dropdownMenuStyle: CoreDropdownMenuStyle(
    popoverStyle: CorePopoverStyle(
      panelBorderRadius: 8,
      panelBackgroundColor: Color(0xFFFFFFFF),
    ),
  ),
  children: [
    // MenuButton(...)
  ],
)

사용 예 (Web)#

Menubar(
  [
    MenubarItem(label: 'File', children: [
      MenubarAction(label: 'New', onSelect: () {}),
    ]),
  ],
  dropdownMenuStyle: CoreDropdownMenuStyle<String, String>(
    popoverStyle: CorePopoverStyle<String, String>(
      panelBorderRadius: 8,
    ),
  ),
)

MenubarItem#

MenubarMenu#

MenubarSeparator#

메뉴 아이템 사이의 구분선입니다. 별도의 속성이 없습니다.

변형 (Variants)#

단축키 포함#

키보드 단축키를 함께 표시합니다.

Menubar(
  onSelect: handleMenubarSelect,
  items: [
    MenubarItem(
      label: '파일',
      menu: [
        MenubarMenu(value: 'new', label: '새 파일', shortcut: '⌘N'),
        MenubarMenu(value: 'open', label: '열기', shortcut: '⌘O'),
        MenubarMenu(value: 'save', label: '저장', shortcut: '⌘S'),
      ],
    ),
  ],
)

동작 스펙 (Behavior)#

인터랙션#

• 클릭: 메뉴 바 항목 클릭 시 드롭다운 열기
• 호버 이동: 한 메뉴가 열린 상태에서 다른 메뉴 바 항목 호버 시 자동 전환
• 항목 선택: 드롭다운 항목 클릭 시 onSelect(value) 호출 후 닫힘
• 외부 클릭: 메뉴 외부 클릭 시 닫힘

상태 전환#

• closed → open: 메뉴 바 항목 클릭
• open → open (다른 메뉴): 다른 메뉴 바 항목 호버
• open → closed: 항목 선택, 외부 클릭, Escape

애니메이션#

• 드롭다운 열림: 페이드 인 150ms
• 드롭다운 닫힘: 페이드 아웃 100ms

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

✅ Do#

MenubarItem(
  label: '파일',
  menu: [
    MenubarMenu(value: 'new', label: '새 파일', shortcut: '⌘N'),
    MenubarMenu(value: 'open', label: '열기', shortcut: '⌘O'),
    MenubarSeparator(), // 파일 작업과 저장 그룹 분리
    MenubarMenu(value: 'save', label: '저장', shortcut: '⌘S'),
    MenubarMenu(value: 'saveAs', label: '다른 이름으로 저장', shortcut: '⌘⇧S'),
    MenubarSeparator(), // 저장과 종료 분리
    MenubarMenu(value: 'exit', label: '종료', shortcut: '⌘Q'),
  ],
)

❌ Don't#

// ❌ 너무 많은 항목
MenubarItem(
  label: '도구',
  menu: List.generate(15, (i) => MenubarMenu(
    value: 'tool_$i',
    label: '도구 ${i + 1}',
  )),
)

✅ Do#

MenubarMenu(value: 'save', label: '저장', shortcut: '⌘S')
MenubarMenu(value: 'undo', label: '실행 취소', shortcut: '⌘Z')
MenubarMenu(value: 'copy', label: '복사', shortcut: '⌘C')

❌ Don't#

// ❌ 모바일에 데스크탑 스타일 Menubar 강요
CouiMenubar(
  items: [
    MenubarItem(label: '홈', menu: []),
    MenubarItem(label: '검색', menu: []),
    MenubarItem(label: '프로필', menu: []),
  ],
  onSelect: handleMenubarSelect,
)

✅ Do#

CouiMenubar(
  items: [
    MenubarItem(label: '파일', children: fileMenuItems),
    MenubarItem(label: '편집', children: editMenuItems),
    MenubarItem(label: '보기', children: viewMenuItems),
    MenubarItem(label: '도움말', children: helpMenuItems),
  ],
)

❌ Don't#

// ❌ 15개의 최상위 메뉴바 항목
CouiMenubar(
  items: fifteenTopLevelItems,  // 너무 많아 화면을 넘침
)

접근성 (Accessibility)#

키보드 인터랙션#

스크린 리더#

• Flutter: role="menubar" + role="menu" + role="menuitem" 자동 적용
• Web: role="menubar" 메뉴바에, role="menu" 드롭다운에, role="menuitem" 항목에 자동 적용

터치 타겟#

• 메뉴 바 항목 최소 높이: 44dp
• 드롭다운 항목 최소 높이: 44dp

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

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

관련 컴포넌트 (Related Components)#

• Menu: 사이드바 형태의 일반 메뉴
• ContextMenu: 우클릭으로 표시되는 상황별 메뉴
• Navigation: 페이지 이동을 위한 네비게이션 메뉴

조합 예제#

// 데스크탑 앱 레이아웃
Scaffold(
  body: Column(
    children: [
      // 메뉴 바
      CouiMenubar(
        onSelect: handleMenuSelect,
        items: [
          MenubarItem(
            label: '파일',
            menu: [
              MenubarMenu(value: 'new', label: '새 파일', shortcut: '⌘N'),
              MenubarMenu(value: 'open', label: '열기', shortcut: '⌘O'),
              const MenubarSeparator(),
              MenubarMenu(value: 'save', label: '저장', shortcut: '⌘S'),
            ],
          ),
          MenubarItem(
            label: '편집',
            menu: [
              MenubarMenu(value: 'undo', label: '실행 취소', shortcut: '⌘Z'),
              MenubarMenu(value: 'redo', label: '다시 실행', shortcut: '⌘⇧Z'),
            ],
          ),
        ],
      ),
      // 메인 콘텐츠 영역
      Expanded(child: mainContent),
    ],
  ),
)