Dropdown

用于显示操作和选项的下拉菜单组件。

导入

import { Dropdown } from 'asterui'

示例

基础下拉菜单

使用组合模式的简单下拉菜单。

import { Dropdown, Button } from 'asterui'

function App() {
  return (
      <Dropdown>
        <Dropdown.Trigger>
          <Button color="primary">Actions</Button>
        </Dropdown.Trigger>
        <Dropdown.Menu>
          <Dropdown.Item>Edit</Dropdown.Item>
          <Dropdown.Item>Duplicate</Dropdown.Item>
          <Dropdown.Item>Delete</Dropdown.Item>
        </Dropdown.Menu>
      </Dropdown>
    )
}

export default App

数据驱动（menu 属性）

通过 menu 属性而非组合组件定义菜单项。

import { Dropdown, Button } from 'asterui'
import { PencilIcon, DocumentDuplicateIcon, TrashIcon } from '@aster-ui/icons'

function App() {
  const menuItems = [
    { key: 'edit', label: 'Edit', icon: <PencilIcon size="sm" /> },
    { key: 'duplicate', label: 'Duplicate', icon: <DocumentDuplicateIcon size="sm" /> },
    { type: 'divider' as const },
    { key: 'delete', label: 'Delete', danger: true, icon: <TrashIcon size="sm" /> },
  ]
  
  return (
      <Dropdown menu={{ items: menuItems }}>
        <Dropdown.Trigger>
          <Button color="primary">Data-Driven</Button>
        </Dropdown.Trigger>
      </Dropdown>
    )
}

export default App

弹出位置

下拉菜单可以定位在不同方向。

import { Dropdown, Button, Space } from 'asterui'

function App() {
  return (
      <Space direction="horizontal" size="sm" wrap>
        <Dropdown placement="top">
          <Dropdown.Trigger>
            <Button>Top</Button>
          </Dropdown.Trigger>
          <Dropdown.Menu>
            <Dropdown.Item>Option 1</Dropdown.Item>
            <Dropdown.Item>Option 2</Dropdown.Item>
            <Dropdown.Item>Option 3</Dropdown.Item>
          </Dropdown.Menu>
        </Dropdown>
  
        <Dropdown placement="bottom">
          <Dropdown.Trigger>
            <Button>Bottom</Button>
          </Dropdown.Trigger>
          <Dropdown.Menu>
            <Dropdown.Item>Option 1</Dropdown.Item>
            <Dropdown.Item>Option 2</Dropdown.Item>
            <Dropdown.Item>Option 3</Dropdown.Item>
          </Dropdown.Menu>
        </Dropdown>
  
        <Dropdown placement="left">
          <Dropdown.Trigger>
            <Button>Left</Button>
          </Dropdown.Trigger>
          <Dropdown.Menu>
            <Dropdown.Item>Option 1</Dropdown.Item>
            <Dropdown.Item>Option 2</Dropdown.Item>
            <Dropdown.Item>Option 3</Dropdown.Item>
          </Dropdown.Menu>
        </Dropdown>
  
        <Dropdown placement="right">
          <Dropdown.Trigger>
            <Button>Right</Button>
          </Dropdown.Trigger>
          <Dropdown.Menu>
            <Dropdown.Item>Option 1</Dropdown.Item>
            <Dropdown.Item>Option 2</Dropdown.Item>
            <Dropdown.Item>Option 3</Dropdown.Item>
          </Dropdown.Menu>
        </Dropdown>
      </Space>
    )
}

export default App

触发模式

控制下拉菜单的打开方式：点击、悬停或两者。

import { Dropdown, Button, Space } from 'asterui'

function App() {
  return (
      <Space direction="horizontal" size="sm" wrap>
        <Dropdown trigger={['click']}>
          <Dropdown.Trigger>
            <Button>Click</Button>
          </Dropdown.Trigger>
          <Dropdown.Menu>
            <Dropdown.Item>Option 1</Dropdown.Item>
            <Dropdown.Item>Option 2</Dropdown.Item>
          </Dropdown.Menu>
        </Dropdown>
  
        <Dropdown trigger={['hover']}>
          <Dropdown.Trigger>
            <Button>Hover</Button>
          </Dropdown.Trigger>
          <Dropdown.Menu>
            <Dropdown.Item>Option 1</Dropdown.Item>
            <Dropdown.Item>Option 2</Dropdown.Item>
          </Dropdown.Menu>
        </Dropdown>
      </Space>
    )
}

export default App

带图标

带图标的菜单项，提供更好的视觉上下文。

import { Dropdown, Button } from 'asterui'
import { PencilIcon, DocumentDuplicateIcon, TrashIcon } from '@aster-ui/icons'

function App() {
  return (
      <Dropdown>
        <Dropdown.Trigger>
          <Button color="primary">Options</Button>
        </Dropdown.Trigger>
        <Dropdown.Menu>
          <Dropdown.Item icon={<PencilIcon size="sm" />}>Edit</Dropdown.Item>
          <Dropdown.Item icon={<DocumentDuplicateIcon size="sm" />}>Duplicate</Dropdown.Item>
          <Dropdown.Item icon={<TrashIcon size="sm" />}>Delete</Dropdown.Item>
        </Dropdown.Menu>
      </Dropdown>
    )
}

export default App

带分隔符

用分隔符分隔菜单部分。

import { Dropdown, Button } from 'asterui'

function App() {
  return (
      <Dropdown>
        <Dropdown.Trigger>
          <Button>Account</Button>
        </Dropdown.Trigger>
        <Dropdown.Menu>
          <Dropdown.Item>Profile</Dropdown.Item>
          <Dropdown.Item>Settings</Dropdown.Item>
          <Dropdown.Divider />
          <Dropdown.Item>Help</Dropdown.Item>
          <Dropdown.Item danger>Sign out</Dropdown.Item>
        </Dropdown.Menu>
      </Dropdown>
    )
}

export default App

项目状态

项目可以是激活、禁用或样式为危险。

import { Dropdown, Button } from 'asterui'

function App() {
  return (
      <Dropdown>
        <Dropdown.Trigger>
          <Button>States</Button>
        </Dropdown.Trigger>
        <Dropdown.Menu>
          <Dropdown.Item active>Active Item</Dropdown.Item>
          <Dropdown.Item>Normal Item</Dropdown.Item>
          <Dropdown.Item disabled>Disabled Item</Dropdown.Item>
          <Dropdown.Divider />
          <Dropdown.Item danger>Delete Account</Dropdown.Item>
        </Dropdown.Menu>
      </Dropdown>
    )
}

export default App

对齐

将下拉菜单对齐到开始、中心或结尾。

import { Dropdown, Button, Space } from 'asterui'

function App() {
  return (
      <Space direction="horizontal" size="sm" wrap>
        <Dropdown placement="bottomLeft">
          <Dropdown.Trigger>
            <Button>Bottom Left</Button>
          </Dropdown.Trigger>
          <Dropdown.Menu>
            <Dropdown.Item>Option 1</Dropdown.Item>
            <Dropdown.Item>Option 2</Dropdown.Item>
          </Dropdown.Menu>
        </Dropdown>
  
        <Dropdown placement="bottom">
          <Dropdown.Trigger>
            <Button>Bottom Center</Button>
          </Dropdown.Trigger>
          <Dropdown.Menu>
            <Dropdown.Item>Option 1</Dropdown.Item>
            <Dropdown.Item>Option 2</Dropdown.Item>
          </Dropdown.Menu>
        </Dropdown>
  
        <Dropdown placement="bottomRight">
          <Dropdown.Trigger>
            <Button>Bottom Right</Button>
          </Dropdown.Trigger>
          <Dropdown.Menu>
            <Dropdown.Item>Option 1</Dropdown.Item>
            <Dropdown.Item>Option 2</Dropdown.Item>
          </Dropdown.Menu>
        </Dropdown>
      </Space>
    )
}

export default App

右键菜单

使用 contextMenu 触发器在右键点击时打开下拉菜单。

import { Dropdown, Typography } from 'asterui'
import { PencilIcon, DocumentDuplicateIcon, TrashIcon } from '@aster-ui/icons'

function App() {
  return (
      <Dropdown trigger={['contextMenu']}>
        <Dropdown.Trigger>
          <div className="p-8 border-2 border-dashed border-base-300 rounded-lg text-center cursor-context-menu">
            <Typography.Text type="secondary">Right-click here</Typography.Text>
          </div>
        </Dropdown.Trigger>
        <Dropdown.Menu>
          <Dropdown.Item icon={<PencilIcon size="sm" />}>Edit</Dropdown.Item>
          <Dropdown.Item icon={<DocumentDuplicateIcon size="sm" />}>Copy</Dropdown.Item>
          <Dropdown.Divider />
          <Dropdown.Item icon={<TrashIcon size="sm" />} danger>Delete</Dropdown.Item>
        </Dropdown.Menu>
      </Dropdown>
    )
}

export default App

带子菜单

用于分层选项的嵌套子菜单。

import { Dropdown, Button } from 'asterui'
import { PencilIcon, FolderIcon, Cog6ToothIcon } from '@aster-ui/icons'

function App() {
  return (
      <Dropdown>
        <Dropdown.Trigger>
          <Button>With Submenu</Button>
        </Dropdown.Trigger>
        <Dropdown.Menu>
          <Dropdown.Item icon={<PencilIcon size="sm" />}>Edit</Dropdown.Item>
          <Dropdown.SubMenu title="More Options" icon={<FolderIcon size="sm" />}>
            <Dropdown.Item>Option A</Dropdown.Item>
            <Dropdown.Item>Option B</Dropdown.Item>
            <Dropdown.Item>Option C</Dropdown.Item>
          </Dropdown.SubMenu>
          <Dropdown.SubMenu title="Settings" icon={<Cog6ToothIcon size="sm" />}>
            <Dropdown.Item>Preferences</Dropdown.Item>
            <Dropdown.Item>Account</Dropdown.Item>
          </Dropdown.SubMenu>
          <Dropdown.Divider />
          <Dropdown.Item danger>Delete</Dropdown.Item>
        </Dropdown.Menu>
      </Dropdown>
    )
}

export default App

紧凑按钮下拉菜单

使用 Join 组合按钮和下拉菜单以实现紧凑的分体按钮外观。按钮会自动被视为触发器，无需 Dropdown.Trigger 包装器。悬停时自动打开。

import { Dropdown, Button, Join } from 'asterui'
import { UserIcon } from '@aster-ui/icons'

function App() {
  const menuItems = [
    { key: 'profile', label: 'Profile' },
    { key: 'settings', label: 'Settings' },
    { type: 'divider' as const },
    { key: 'logout', label: 'Sign out', danger: true },
  ]
  
  return (
      <Join>
        <Button color="primary">Actions</Button>
        <Dropdown menu={{ items: menuItems }} placement="bottomRight">
          <Button color="primary" icon={<UserIcon />} />
        </Dropdown>
      </Join>
    )
}

export default App

紧凑图标下拉菜单

使用简化 API 将仅图标的下拉按钮与另一个按钮组合在一起（无需 Dropdown.Trigger 包装器）。悬停时打开以便快速访问。

import { Dropdown, Button, Join } from 'asterui'
import { EllipsisVerticalIcon } from '@aster-ui/icons'

function App() {
  return (
      <Join>
        <Button>Save</Button>
        <Dropdown placement="bottomRight">
          <Button icon={<EllipsisVerticalIcon />} />
          <Dropdown.Menu>
            <Dropdown.Item>Save and Close</Dropdown.Item>
            <Dropdown.Item>Save as Draft</Dropdown.Item>
            <Dropdown.Divider />
            <Dropdown.Item>Discard</Dropdown.Item>
          </Dropdown.Menu>
        </Dropdown>
      </Join>
    )
}

export default App

API

`Dropdown`

属性	描述	类型	默认值
`children`	触发元素和下拉内容（组合模式）	`React.ReactNode`	-
`menu`	菜单配置（数据驱动模式）	`{ items: DropdownMenuItemType[], onClick?: (info: { key: string; keyPath: string[] }) => void }`	-
`trigger`	下拉菜单的触发模式	`('click' \| 'hover' \| 'contextMenu')[]`	`['hover']`
`placement`	下拉菜单弹出位置	`'top' \| 'topLeft' \| 'topRight' \| 'bottom' \| 'bottomLeft' \| 'bottomRight' \| 'left' \| 'right'`	`'bottomLeft'`
`open`	受控的打开状态	`boolean`	-
`onOpenChange`	打开状态改变时的回调	`(open: boolean, info?: { source }) => void`	-
`disabled`	禁用下拉菜单	`boolean`	`false`
`arrow`	显示指向触发器的箭头	`boolean \| { pointAtCenter?: boolean }`	`false`
`autoAdjustOverflow`	下拉菜单被遮挡时自动调整位置	`boolean`	`true`
`mouseEnterDelay`	悬停显示前的延迟（秒）	`number`	`0.15`
`mouseLeaveDelay`	鼠标离开隐藏前的延迟（秒）	`number`	`0.1`
`destroyOnHidden`	隐藏时销毁下拉菜单	`boolean`	`false`
`popupRender`	自定义弹出内容	`(menu: ReactNode) => ReactNode`	-
`data-testid`	子元素的测试 ID 前缀	`string`	-
`className`	额外的 CSS 类名	`string`	-

`Dropdown.Item`

属性	描述	类型	默认值
`key`	项目的唯一键（React key 属性）	`string`	-
`children`	项目内容	`React.ReactNode`	-
`label`	项目标签（children 的替代方案）	`React.ReactNode`	-
`icon`	在标签前显示的图标	`React.ReactNode`	-
`onClick`	点击处理器	`() => void`	-
`active`	激活/选中状态	`boolean`	`false`
`disabled`	禁用项目	`boolean`	`false`
`danger`	危险/破坏性样式	`boolean`	`false`
`className`	额外的 CSS 类名	`string`	-

`Dropdown.SubMenu`

属性	描述	类型	默认值
`key`	子菜单的唯一键（React key 属性）	`string`	-
`children`	子菜单项	`React.ReactNode`	-
`title`	子菜单标题/标签	`React.ReactNode`	-
`icon`	在标题前显示的图标	`React.ReactNode`	-
`disabled`	禁用子菜单	`boolean`	`false`

无障碍

支持 Enter、Space 和 Escape 键的键盘导航
方向键浏览菜单项
为屏幕阅读器提供正确的 ARIA 属性
打开和关闭菜单时的焦点管理
点击外部关闭行为