Dropdown#
导航
@rockshin/tao-ui从触发器打开一组相关操作或选项。
#何时使用
多个次要操作需要紧凑收纳在一个触发器后时使用 Dropdown。
推荐
- 菜单项按任务关系分组。
- 危险操作使用 danger 语义。
- 键盘可达并保持清晰焦点。
避免
- 不要隐藏唯一的主要操作。
#代码演示
#基础用法
TSX
import { Button, Dropdown } from '@rockshin/tao-ui';
function DropdownExample() {
return (
<Dropdown
menu={{
items: [
{ key: 'edit', label: 'Edit' },
{ key: 'duplicate', label: 'Duplicate' },
{ type: 'divider' },
{ key: 'archive', label: 'Archive' },
],
}}
>
<Button variant="secondary">Actions</Button>
</Dropdown>
);
}
export default DropdownExample;#分组与子菜单
TSX
import { Button, Dropdown } from '@rockshin/tao-ui';
function DropdownGroups() {
return (
<Dropdown
menu={{
items: [
{
type: 'group',
label: 'Create',
children: [
{ key: 'file', label: 'New file', extra: '⌘N' },
{ key: 'folder', label: 'New folder' },
],
},
{ type: 'divider' },
{
key: 'share',
label: 'Share',
children: [
{ key: 'link', label: 'Copy link' },
{ key: 'invite', label: 'Invite people' },
],
},
{ key: 'delete', label: 'Delete', danger: true },
],
}}
>
<Button variant="secondary">Project actions</Button>
</Dropdown>
);
}
export default DropdownGroups;#触发方式、箭头与组合按钮
TSX
import { useState } from 'react';
import { Button, Dropdown, Stack } from '@rockshin/tao-ui';
const items = [
{ key: 'edit', label: 'Edit' },
{ key: 'duplicate', label: 'Duplicate' },
];
function DropdownTriggers() {
const [feedback, setFeedback] = useState('');
return (
<>
<Stack direction="horizontal" gap="md">
<Dropdown trigger={['hover']} menu={{ items }}>
<Button variant="secondary">Hover</Button>
</Dropdown>
<Dropdown trigger={['click']} arrow menu={{ items }}>
<Button variant="secondary">Click with arrow</Button>
</Dropdown>
<Dropdown.Button menu={{ items }} onClick={() => setFeedback('save')}>
Save
</Dropdown.Button>
</Stack>
<output
aria-live="polite"
style={{
display: 'block',
marginTop: 12,
whiteSpace: 'pre-wrap',
overflowWrap: 'anywhere',
}}
>
{feedback}
</output>
</>
);
}
export default DropdownTriggers;#图标、快捷键与禁用项
菜单项支持图标和辅助内容;这里的快捷键文字仅作提示,不注册全局键盘快捷键。
TSX
import { Button, Dropdown } from '@rockshin/tao-ui';
function FileIcon() {
return (
<svg
aria-hidden="true"
focusable="false"
width="16"
height="16"
viewBox="0 0 24 24"
fill="none"
stroke="currentColor"
strokeWidth="2"
strokeLinecap="round"
strokeLinejoin="round"
>
<path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z" />
<path d="M14 2v6h6" />
</svg>
);
}
function CopyIcon() {
return (
<svg
aria-hidden="true"
focusable="false"
width="16"
height="16"
viewBox="0 0 24 24"
fill="none"
stroke="currentColor"
strokeWidth="2"
strokeLinecap="round"
strokeLinejoin="round"
>
<rect x="9" y="9" width="13" height="13" rx="2" />
<path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" />
</svg>
);
}
function ClipboardIcon() {
return (
<svg
aria-hidden="true"
focusable="false"
width="16"
height="16"
viewBox="0 0 24 24"
fill="none"
stroke="currentColor"
strokeWidth="2"
strokeLinecap="round"
strokeLinejoin="round"
>
<rect x="8" y="2" width="8" height="4" rx="1" />
<path d="M16 4h2a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2h2" />
</svg>
);
}
export default function DropdownWithIconsAndShortcuts() {
return (
<Dropdown
menu={{
items: [
{ key: 'new', label: 'New file', icon: <FileIcon />, extra: '⌘N' },
{ key: 'copy', label: 'Copy', icon: <CopyIcon />, extra: '⌘C' },
{
key: 'paste',
label: 'Paste',
icon: <ClipboardIcon />,
extra: '⌘V',
disabled: true,
},
],
}}
>
<Button variant="secondary">Actions</Button>
</Dropdown>
);
}#分组与分隔线
按任务关系分组,用分隔线区分不同类别的操作。
TSX
import { Button, Dropdown } from '@rockshin/tao-ui';
export default function DropdownDividerAndGroup() {
return (
<Dropdown
menu={{
items: [
{
type: 'group',
label: 'Account',
children: [
{ key: 'profile', label: 'Profile' },
{ key: 'billing', label: 'Billing' },
],
},
{ type: 'divider' },
{
type: 'group',
label: 'Workspace',
children: [
{ key: 'members', label: 'Members' },
{ key: 'settings', label: 'Settings' },
],
},
{ type: 'divider' },
{ key: 'logout', label: 'Log out', danger: true },
],
}}
>
<Button variant="secondary">Account</Button>
</Dropdown>
);
}#嵌套子菜单
嵌套 children 创建子菜单;可以用键盘方向键继续导航。
TSX
import { Button, Dropdown, type MenuItem } from '@rockshin/tao-ui';
export default function DropdownSubmenu() {
return (
<Dropdown
menu={{
items: [
{ key: 'back', label: 'Back' },
{ key: 'forward', label: 'Forward', disabled: true },
{ type: 'divider' },
{
key: 'share',
label: 'Share',
children: [
{ key: 'mail', label: 'Email' },
{ key: 'message', label: 'Message' },
{
key: 'more',
label: 'More',
children: [
{ key: 'twitter', label: 'Twitter' },
{ key: 'facebook', label: 'Facebook' },
],
},
],
},
{ key: 'delete', label: 'Delete', danger: true, extra: '⌫' },
],
}}
>
<Button variant="secondary">Right menu</Button>
</Dropdown>
);
}#受控菜单选择
选中状态由调用方维护,适合显示模式或筛选选项。
TSX
import { Button, Dropdown, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';
export default function DropdownSelectable() {
const [single, setSingle] = useState<string[]>(['md']);
const [multi, setMulti] = useState<string[]>(['bold']);
return (
<Stack direction="horizontal" gap="lg">
<Dropdown
menu={{
selectable: true,
selectedKeys: single,
onSelect: ({ selectedKeys }) => setSingle(selectedKeys),
items: [
{ key: 'sm', label: 'Small' },
{ key: 'md', label: 'Medium' },
{ key: 'lg', label: 'Large' },
],
}}
>
<Button variant="secondary">Size: {single[0]}</Button>
</Dropdown>
<Dropdown
menu={{
selectable: true,
multiple: true,
selectedKeys: multi,
onSelect: ({ selectedKeys }) => setMulti(selectedKeys),
items: [
{ key: 'bold', label: 'Bold' },
{ key: 'italic', label: 'Italic' },
{ key: 'underline', label: 'Underline' },
],
}}
>
<Button variant="secondary">Format ({multi.length})</Button>
</Dropdown>
</Stack>
);
}#菜单位置
配置 placement,弹层在视口边缘仍会自动避让。
TSX
import { Button, Dropdown, type MenuItem } from '@rockshin/tao-ui';
const basicItems: MenuItem[] = [
{ key: 'profile', label: 'Profile' },
{ key: 'billing', label: 'Billing' },
{ key: 'settings', label: 'Settings' },
];
export default function DropdownPlacement() {
return (
<div
style={{
display: 'grid',
gridTemplateColumns: 'repeat(3, auto)',
gap: 12,
width: 'fit-content',
}}
>
{(
[
'topLeft',
'top',
'topRight',
'bottomLeft',
'bottom',
'bottomRight',
] as const
).map((p) => (
<Dropdown key={p} placement={p} menu={{ items: basicItems }}>
<Button variant="secondary">{p}</Button>
</Dropdown>
))}
</div>
);
}#触发方式
分别试用点击和悬停触发;触屏场景应保留点击入口。
TSX
import { Button, Dropdown, type MenuItem, Stack } from '@rockshin/tao-ui';
const basicItems: MenuItem[] = [
{ key: 'profile', label: 'Profile' },
{ key: 'billing', label: 'Billing' },
{ key: 'settings', label: 'Settings' },
];
export default function DropdownTrigger() {
return (
<Stack direction="horizontal" gap="lg">
<Dropdown trigger={['hover']} menu={{ items: basicItems }}>
<Button variant="secondary">Hover me</Button>
</Dropdown>
<Dropdown trigger={['click']} arrow menu={{ items: basicItems }}>
<Button variant="secondary">Click (with arrow)</Button>
</Dropdown>
</Stack>
);
}#API
#Dropdown
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| children | Trigger element (a single React element). | ReactNode (必填) | - |
| trigger | How the menu opens. Defaults to ['click']. | DropdownTrigger[] | undefined | - |
| placement | Defaults to 'bottomLeft'. Ignored for contextMenu. | DropdownPlacement | undefined | - |
| disabled | 是否禁用 | boolean | undefined | - |
| arrow | Show a pointing arrow on the menu. Defaults to false. | boolean | undefined | - |
| className | Merged onto the floating content. | string | undefined | - |
| style | 节点样式 | CSSProperties | undefined | - |
#Dropdown.Button
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| children | Main button content. | ReactNode | - |
| onClick | Main button click handler. | (() => void) | undefined | - |
| icon | Icon for the trigger button. Defaults to an ellipsis. | ReactNode | - |
| trigger | How the menu opens. Defaults to ['click']. | DropdownTrigger[] | undefined | - |
| placement | Defaults to 'bottomLeft'. Ignored for contextMenu. | DropdownPlacement | undefined | - |
| disabled | 是否禁用 | boolean | undefined | - |
| arrow | Show a pointing arrow on the menu. Defaults to false. | boolean | undefined | - |
| className | Merged onto the floating content. | string | undefined | - |
| style | 节点样式 | CSSProperties | undefined | - |