下拉菜单 · DropdownMenu

下拉菜单用于操作场景。下面的官方示例展示原生用法与状态，属性名保持上游 API。

安装与前置条件

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见开始使用。

示例与使用方式

• 下拉菜单 · 综合展示 / 分组 1：首先体验这个示例，再查看代码理解组件的组合方式。
• 下拉菜单 · 综合展示 2：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 下拉菜单 · 综合展示 3：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 下拉菜单 · 交互示例 4：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 下拉菜单 · 交互示例 5：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 下拉菜单 · 分组 6：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 下拉菜单 · 基础用法 7：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 下拉菜单 · 交互示例 8：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 下拉菜单 · 禁用状态 9：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 下拉菜单 · 交互示例 10：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 下拉菜单 · 交互示例 11：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

API 与上游详细参考

优先使用 0.7.1 官方中文说明；上游尚未提供中文的条目保留英文。属性名、类型及默认值保持原生 API，不把示例状态名称当成组件属性。

Dropdown Menu

A dropdown menu that displays a list of actionable items in a popup triggered by a button. Use to present action options as a next step in a process, or to offer contextual actions without cluttering the interface.

使用建议

• Keep menu items concise and action-oriented so users can scan options quickly.
• Use sections and dividers to group related actions when the menu has many items.
• For a short, flat action set, use presentation="bottom-sheet" when product policy calls for a modal touch surface.
• Use presentation="adaptive" when the same short action set should remain anchored on pointer layouts and become a BottomSheet on compact coarse-pointer layouts.
• For a hierarchy that cannot fit as adjacent flyouts on a compact touch surface, a product may explicitly use a drill-in interaction with a Back action.
• Choose presentation explicitly in product code. A compact, coarse-pointer, hover-free media query is one useful policy, but DropdownMenu does not impose a universal device breakpoint.
• When the content is no longer a short list of immediate actions, reevaluate the interaction and choose a component that matches the actual task; content traits alone do not determine the component.
• 避免：Use a DropdownMenu for navigation; use a navigation component instead.
• 避免：Place more than 10–12 items in a single menu without grouping them into sections.

主题 API

{
  "targets": [
    {
      "className": "astryx-dropdown-menu",
      "visualProps": [
        "presentation"
      ]
    },
    {
      "className": "astryx-dropdown-menu-item",
      "visualProps": [
        "size",
        "variant"
      ]
    },
    {
      "className": "astryx-dropdown-menu-radio",
      "visualProps": [
        "size"
      ],
      "states": [
        "checked",
        "disabled"
      ]
    },
    {
      "className": "astryx-dropdown-menu-section-heading"
    },
    {
      "className": "astryx-dropdown-menu-divider"
    },
    {
      "className": "astryx-dropdown-menu-indicator-icon"
    }
  ],
  "vars": [
    {
      "name": "--_dropdown-menu-radius",
      "description": "Border radius of the menu popup",
      "default": "var(--radius-element)",
      "private": true
    },
    {
      "name": "--_dropdown-menu-padding",
      "description": "Inner padding of the menu popup",
      "default": "var(--spacing-1)",
      "private": true
    }
  ],
  "derived": [
    {
      "property": "borderRadius",
      "vars": [
        "--_dropdown-menu-radius"
      ]
    },
    {
      "property": "padding",
      "vars": [
        "--_dropdown-menu-padding"
      ]
    }
  ]
}

DropdownMenuItem

组件结构

• Trigger button: Button that opens and closes the selected menu presentation.
• Trigger indicator icon: Optional trailing chevron shown by a labeled trigger when hasChevron is enabled.
• Pointer menu surface: Anchored top-level or nested menu panel used by the pointer presentation.
• Pointer action row: Action, selectable option, or submenu trigger row in an anchored menu.
• Icon-rendered item icon: Optional semantic or component icon rendered through Icon at the start of an action row.
• Caller-rendered item start content: Optional arbitrary React content rendered directly at the start of an action row.
• Checkbox indicator: Decorative shared checkbox indicator for a checkbox action row.
• Radio indicator: Decorative shared radio indicator with an additional menu-owned target.
• Pointer section heading: Heading that labels a group of rows in an anchored menu: a data-driven section or a compound DropdownMenuGroup.
• Pointer divider: Divider between groups in an anchored menu.
• Pointer submenu indicator icon: Trailing chevron that identifies an action row as a nested flyout trigger.
• Touch sheet frame: BottomSheet panel, content area, handle, and optional scrim that host touch actions.
• Touch menu surface: Menu-owned content panel rendered inside the touch sheet frame.
• Touch heading: Current action-sheet title, updated when a nested action view is opened.
• Touch action list: Spacious List that groups actions in the touch presentation.
• Touch action row: ListItem button used for an action or drill-in entry in the touch presentation.
• Touch divider: Divider between action groups in the touch presentation.

Dropdown Menu Checkbox Item

An independently checkable option inside DropdownMenu. The row owns menuitemcheckbox semantics while the shared Indicator supplies decorative checkbox paint.

主题 API

{
  "targets": [
    {
      "className": "astryx-dropdown-menu-item",
      "visualProps": [
        "size"
      ]
    }
  ]
}

组件结构

• Checkable row: The menuitemcheckbox root that owns the accessible name, checked state, focus, and activation.
• Label/content: Caller content laid out by Item: the required label plus optional description, icon, and end content.
• Checkbox marker: Decorative shared Indicator chrome that visualizes checked and disabled state without adding a second control.

Dropdown Menu Divider

A horizontal rule separating groups of rows in a compound menu. Renders role="separator", so it is never a stop in the arrow-key order. The data-driven equivalent is the {type: "divider"} entry in items; both modes render this component, so they look and theme identically.

主题 API

{
  "targets": [
    {
      "className": "astryx-dropdown-menu-divider"
    }
  ]
}

Dropdown Menu Group

A titled group of rows in a compound menu. Renders role="group" named by its heading; the heading is plain text, not a menuitem, so arrow keys and typeahead skip it. The data-driven equivalent is the {type: "section", title, items} entry in items; the heading shares its typography and theme target.

主题 API

{
  "targets": [
    {
      "className": "astryx-dropdown-menu-section-heading"
    }
  ]
}

Dropdown Menu Item

用于自定义项渲染的辅助组件，提供一致的样式。宿主属性和 DOM 事件处理器（aria-、data-、id、拖放）会落在行根元素上，即带 role="menuitem" 的元素。

Dropdown Menu Radio Group

单选的单选菜单项组（menuitemradio 的 role="group"）。持有所选值，并以菜单的项间距布局其子项。

Dropdown Menu Radio Item

DropdownMenuRadioGroup 中的单个选项（role="menuitemradio"）。必须在 DropdownMenuRadioGroup 内使用。

Dropdown Menu Submenu

A single menu row that reveals a nested flyout of its own items. The row adopts DropdownMenuItem semantics (label / icon / description / isDisabled); its children become the flyout content. Opens inline-end with viewport auto-flip; Right/Enter/Space opens and focuses the first item, Left/Escape closes and returns focus to the trigger (Right/Left swap in RTL). On a phone (a coarse pointer, decided when the menu opened) the row drills in instead: its rows replace the menu's rows in the same box, led by a Back row named "Back to <parent>", and Back, Escape or ArrowLeft return to the row. Host attributes and DOM event handlers (aria-, data-, id) reach the trigger row, the element carrying role="menuitem" and aria-haspopup="menu"; a caller's handlers run after the row's own, except for the keys that open the flyout (the open arrow, Enter, Space) and a click on a disabled row. For data-driven menus, give a menu item a nested items array instead of using this component directly.

完整示例的额外依赖

部分示例使用独立图标包。示例清单中的每条安装命令包含该示例实际需要的依赖；若要运行本页全部示例，还需安装：

npm install @heroicons/react@2.2.0