For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/llms-full.txt, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/components/dropdown.md.

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

触发器应是支持 ref 与事件的单个按钮。Escape 关闭菜单并返回触发按钮。共享浮层参数见 PopupOptions。

属性类型默认值说明
itemsreadonly DropdownItem[]必填菜单项列表
childrenReactElement< ButtonHTMLAttributes<HTMLButtonElement> & { ref?: Ref<HTMLButtonElement> } >必填单个按钮,支持 Leaf Button 或 button
trigger'click' | 'hover' | 'contextMenu' | readonly ('click' | 'hover' | 'contextMenu')[]'click'触发方式;下拉菜单支持点击、悬停和右键。
disabledbooleanfalse禁用交互。
size'sm' | 'md' | 'lg''md'展示尺寸。
openboolean—受控的展开状态。
defaultOpenbooleanfalse非受控模式的初始展开状态。
onOpenChange(open: boolean) => void—展开状态变更
onSelect(key: string) => void—激活叶菜单项时返回 key,包括单选和复选项;展开子菜单不触发。
placement'top-start' | 'top-end' | 'bottom-start' | 'bottom-end''bottom-start'菜单位置;popupPlacement 优先。
popupWidthnumber | string—浮层宽度;未设置时最小 160px,并根据内容增宽。
popupMaxWidthnumber | string420浮层最大宽度,仍受视口限制。
itemRender(item: DropdownItem) => ReactNode—自定义菜单项的标签内容,不替换整行。
mouseEnterDelaynumber100悬停触发后等待多少毫秒再打开。
mouseLeaveDelaynumber150鼠标离开后等待多少毫秒再关闭。
popupPlacement'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'right' | 'right-start' | 'right-end'—浮层相对触发控件的位置。
popupClassNamestring—浮层的自定义类名。
popupStyleCSSProperties—浮层的自定义样式。
popupRender(content: React.ReactNode) => React.ReactNode—包装或补充面板内容,保留传入的内容以维持交互。
getPopupContainer() => Element | DocumentFragment—返回浮层的挂载容器,也可返回 ShadowRoot。

下拉菜单中的操作、分组或子菜单数据。

属性类型默认值说明
keystring必填唯一标识
labelReactNode—菜单项文字或分组标题。
iconReactNode—菜单项文字前的图标。
extraReactNode—条目右侧的附加内容;适合放快捷键、状态标签等非交互信息。
type'item' | 'divider' | 'group' | 'checkbox' | 'radio''item'普通项、分隔线、分组、复选项或单选项。
childrenreadonly DropdownItem[]—菜单项列表。
disabledbooleanfalse禁用交互。
dangerbooleanfalse危险操作的颜色,不会禁用菜单项。
checkedboolean—受控的勾选状态;省略时由菜单内部保存。
groupstring—单选项所属的互斥组标识。
closeOnSelectboolean—选择后是否关闭;默认普通项关闭,单选和复选项保持打开。
onCheckedChange(checked: boolean) => void—点击勾选项时返回下一勾选状态。
hrefstring—链接目标。
targetstring—链接的 target 属性,例如 _blank;省略时在当前标签页打开。
onClick(event: MouseEvent<HTMLElement>) => void—点击此项时触发