#Dropdown 下拉菜单
在菜单中收纳更多操作。
#基础用法
通过 items 提供菜单操作,并使用按钮作为触发器。
basic.tsx
import { Button, Dropdown, Flex, Text } from '@ifhover/leaf-ui';
import { Archive, ChevronDown, Copy, Pencil } from 'lucide-react';
import { useState } from 'react';
export function DropdownBasic() {
const [action, setAction] = useState('');
return (
<Flex direction="column" gap="md" align="start">
<Dropdown
items={[
{ key: 'edit', label: '编辑', icon: <Pencil size={14} /> },
{ key: 'copy', label: '复制', icon: <Copy size={14} /> },
{ key: 'archive', label: '归档', icon: <Archive size={14} /> },
]}
onSelect={setAction}
>
<Button variant="outline" endIcon={<ChevronDown size={16} />}>
更多操作
</Button>
</Dropdown>
{action && <Text role="status">已选择: {action}</Text>}
</Flex>
);
}
#示例
#右侧内容
通过条目的 extra 放置快捷键、标签等补充信息。它属于整行点击区域,不要在其中嵌套按钮或链接。
extra.tsx
import type { DropdownItem } from '@ifhover/leaf-ui';
import { Button, Dropdown, Flex, Tag, Text } from '@ifhover/leaf-ui';
import { ChevronDown, Copy, Download, Pencil } from 'lucide-react';
import { useState } from 'react';
const items: DropdownItem[] = [
{ key: 'edit', label: '编辑', icon: <Pencil />, extra: <Text tone="muted">Ctrl E</Text> },
{ key: 'copy', label: '复制链接', icon: <Copy />, extra: <Tag size="sm">新</Tag> },
{
key: 'export',
label: '导出',
icon: <Download />,
extra: <Text tone="muted">CSV</Text>,
children: [
{ key: 'all', label: '全部数据' },
{ key: 'selected', label: '当前选择' },
],
},
];
export function DropdownExtra() {
const [action, setAction] = useState('');
return (
<Flex direction="column" gap="md" align="start">
<Dropdown items={items} onSelect={setAction}>
<Button variant="outline" endIcon={<ChevronDown size={16} />}>
更多操作
</Button>
</Dropdown>
{action && <Text role="status">已选择: {action}</Text>}
</Flex>
);
}
#菜单尺寸
通过 Dropdown 的 size 设置菜单尺寸,子菜单继承该尺寸。触发按钮使用自己的 size。
小
默认
大
sizes.tsx
import { Button, Dropdown, Flex, Grid, Text } from '@ifhover/leaf-ui';
import { ChevronDown, Copy, Pencil } from 'lucide-react';
const sizes = [
{ size: 'sm', label: '小' },
{ size: 'md', label: '默认' },
{ size: 'lg', label: '大' },
] as const;
export function DropdownSizes() {
return (
<Flex direction="column" gap="md">
{sizes.map(({ size, label }) => (
<Grid
key={size}
role="group"
aria-label={label}
columns={{ xs: 1, sm: 2 }}
gap="8px"
align="center"
>
<Text tone="muted">{label}</Text>
<Dropdown
size={size}
items={[
{ key: 'edit', label: '编辑', icon: <Pencil /> },
{ key: 'copy', label: '复制链接', icon: <Copy />, extra: 'Ctrl C' },
]}
>
<Button variant="outline" endIcon={<ChevronDown size={16} />}>
更多操作
</Button>
</Dropdown>
</Grid>
))}
</Flex>
);
}
#子菜单与分组
children 定义子菜单,type: 'group' 与 label 定义分组标题。只有选择菜单项才触发 onSelect,展开子菜单不会触发。
hierarchy.tsx
import { Button, Dropdown, Flex, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';
export function DropdownHierarchy() {
const [action, setAction] = useState('');
return (
<Flex direction="column" gap="md" align="start">
<Dropdown
onSelect={setAction}
items={[
{
key: 'project',
type: 'group',
label: '项目',
children: [
{ key: 'open', label: '打开' },
{
key: 'export',
label: '导出',
children: [
{ key: 'csv', label: 'CSV' },
{ key: 'json', label: 'JSON' },
],
},
],
},
{ key: 'divider', type: 'divider' },
{ key: 'archive', label: '归档', disabled: true },
{ key: 'delete', label: '删除', danger: true },
]}
>
<Button variant="outline">项目操作</Button>
</Dropdown>
{action && <Text role="status">已选择: {action}</Text>}
</Flex>
);
}
#单选菜单
使用 type: 'radio',相同 group 标识同一互斥组。示例通过 checked 和 onCheckedChange 管理当前视图。
当前视图: 列表
radio.tsx
import { Button, Dropdown, Flex, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';
export function DropdownRadio() {
const [view, setView] = useState('list');
return (
<Flex direction="column" gap="md" align="start">
<Dropdown
items={[
{
key: 'list',
label: '列表',
type: 'radio',
group: 'view',
checked: view === 'list',
onCheckedChange: () => setView('list'),
},
{
key: 'grid',
label: '网格',
type: 'radio',
group: 'view',
checked: view === 'grid',
onCheckedChange: () => setView('grid'),
},
]}
>
<Button variant="outline">切换视图</Button>
</Dropdown>
<Text role="status" tone="muted">
当前视图: {view === 'list' ? '列表' : '网格'}
</Text>
</Flex>
);
}
#复选菜单
单选和复选菜单默认在选择后保持打开。通过 closeOnSelect 可覆盖此行为。
详情已显示
checkbox.tsx
import { Button, Dropdown, Flex, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';
export function DropdownCheckbox() {
const [details, setDetails] = useState(true);
return (
<Flex direction="column" gap="md" align="start">
<Dropdown
items={[
{
key: 'details',
label: '显示详情',
type: 'checkbox',
checked: details,
onCheckedChange: setDetails,
},
]}
>
<Button variant="outline">显示选项</Button>
</Dropdown>
<Text role="status" tone="muted">
{details ? '详情已显示' : '详情已隐藏'}
</Text>
</Flex>
);
}
#悬停触发
设置 trigger="hover" 后,指针移入时打开。仍可聚焦按钮并按方向键打开菜单。
hover.tsx
import { Button, Dropdown, Flex, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';
export function DropdownHover() {
const [action, setAction] = useState('');
return (
<Flex direction="column" gap="md" align="start">
<Dropdown
trigger="hover"
items={[
{ key: 'edit', label: '编辑' },
{ key: 'copy', label: '复制' },
]}
onSelect={setAction}
>
<Button variant="outline">悬停展开</Button>
</Dropdown>
{action && <Text role="status">已选择: {action}</Text>}
</Flex>
);
}
#右键菜单
设置 trigger="contextMenu" 后,在右键点击处打开。键盘用户可聚焦按钮并按 ↓ 或 ↑ 打开菜单。
context-menu.tsx
import { Button, Dropdown, Flex, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';
export function DropdownContextMenu() {
const [action, setAction] = useState('');
return (
<Flex direction="column" gap="md" align="start">
<Dropdown
trigger="contextMenu"
items={[
{ key: 'edit', label: '编辑' },
{ key: 'copy', label: '复制' },
]}
onSelect={setAction}
>
<Button variant="outline">在此右键点击</Button>
</Dropdown>
{action && <Text role="status">已选择: {action}</Text>}
</Flex>
);
}
#API
#Dropdown API
触发器应是支持 ref 与事件的单个按钮。Escape 关闭菜单并返回触发按钮。共享浮层参数见 PopupOptions。
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
items | readonly DropdownItem[] | 必填 | 菜单项列表 |
children | ReactElement< ButtonHTMLAttributes<HTMLButtonElement> & { ref?: Ref<HTMLButtonElement> } > | 必填 | 单个按钮,支持 Leaf Button 或 button |
trigger | 'click' | 'hover' | 'contextMenu' | readonly ('click' | 'hover' | 'contextMenu')[] | 'click' | 触发方式;下拉菜单支持点击、悬停和右键。 |
disabled | boolean | false | 禁用交互。 |
size | 'sm' | 'md' | 'lg' | 'md' | 展示尺寸。 |
open | boolean | — | 受控的展开状态。 |
defaultOpen | boolean | false | 非受控模式的初始展开状态。 |
onOpenChange | (open: boolean) => void | — | 展开状态变更 |
onSelect | (key: string) => void | — | 激活叶菜单项时返回 key,包括单选和复选项;展开子菜单不触发。 |
placement | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | 'bottom-start' | 菜单位置;popupPlacement 优先。 |
popupWidth | number | string | — | 浮层宽度;未设置时最小 160px,并根据内容增宽。 |
popupMaxWidth | number | string | 420 | 浮层最大宽度,仍受视口限制。 |
itemRender | (item: DropdownItem) => ReactNode | — | 自定义菜单项的标签内容,不替换整行。 |
mouseEnterDelay | number | 100 | 悬停触发后等待多少毫秒再打开。 |
mouseLeaveDelay | number | 150 | 鼠标离开后等待多少毫秒再关闭。 |
popupPlacement | 'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'right' | 'right-start' | 'right-end' | — | 浮层相对触发控件的位置。 |
popupClassName | string | — | 浮层的自定义类名。 |
popupStyle | CSSProperties | — | 浮层的自定义样式。 |
popupRender | (content: React.ReactNode) => React.ReactNode | — | 包装或补充面板内容,保留传入的内容以维持交互。 |
getPopupContainer | () => Element | DocumentFragment | — | 返回浮层的挂载容器,也可返回 ShadowRoot。 |
#DropdownItem
下拉菜单中的操作、分组或子菜单数据。
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
key | string | 必填 | 唯一标识 |
label | ReactNode | — | 菜单项文字或分组标题。 |
icon | ReactNode | — | 菜单项文字前的图标。 |
extra | ReactNode | — | 条目右侧的附加内容;适合放快捷键、状态标签等非交互信息。 |
type | 'item' | 'divider' | 'group' | 'checkbox' | 'radio' | 'item' | 普通项、分隔线、分组、复选项或单选项。 |
children | readonly DropdownItem[] | — | 菜单项列表。 |
disabled | boolean | false | 禁用交互。 |
danger | boolean | false | 危险操作的颜色,不会禁用菜单项。 |
checked | boolean | — | 受控的勾选状态;省略时由菜单内部保存。 |
group | string | — | 单选项所属的互斥组标识。 |
closeOnSelect | boolean | — | 选择后是否关闭;默认普通项关闭,单选和复选项保持打开。 |
onCheckedChange | (checked: boolean) => void | — | 点击勾选项时返回下一勾选状态。 |
href | string | — | 链接目标。 |
target | string | — | 链接的 target 属性,例如 _blank;省略时在当前标签页打开。 |
onClick | (event: MouseEvent<HTMLElement>) => void | — | 点击此项时触发 |