开发预览更新于 2026-05-10

Dropdown 下拉菜单

下拉菜单 —— Popover + 列表 + 键盘导航。支持分组标题、分隔线、危险操作语义。

基础用法

items 数组式配置，按顺序渲染菜单项；divider: true 渲染分隔线，header: true 渲染分组标题。键盘 ↑↓ 切换、Enter / 空格选中、Esc 关闭、Home / End 跳到首/末项。

<script setup lang="ts">
import { CfButton, CfDropdown } from '@chufix-design/vue';
import type { DropdownItem } from '@chufix-design/vue';

const items: DropdownItem[] = [
{ key: 'profile', label: '个人资料' },
{ key: 'settings', label: '设置' },
{ divider: true, label: '' },
{ header: true, label: '操作' },
{ key: 'rename', label: '重命名' },
{ key: 'archive', label: '归档', disabled: true },
{ key: 'delete', label: '删除', tone: 'danger' },
];

function onSelect(item: DropdownItem) {
console.log('selected:', item.key);
}
</script>

<template>
<CfDropdown :items="items" placement="bottom" @select="onSelect">
  <CfButton variant="secondary">操作菜单 ▾</CfButton>
</CfDropdown>
</template>

import { CfButton, CfDropdown } from '@chufix-design/react';
import type { DropdownItem } from '@chufix-design/react';

const items: DropdownItem[] = [
{ key: 'profile', label: '个人资料' },
{ key: 'settings', label: '设置' },
{ divider: true, label: '' },
{ header: true, label: '操作' },
{ key: 'rename', label: '重命名' },
{ key: 'archive', label: '归档', disabled: true },
{ key: 'delete', label: '删除', tone: 'danger' },
];

export default function Demo() {
return (
  <CfDropdown
    items={items}
    placement="bottom"
    onSelect={(item) => console.log('selected:', item.key)}
  >
    <CfButton variant="secondary">操作菜单 ▾</CfButton>
  </CfDropdown>
);
}

API · Props

属性	类型	默认值	说明
`items`	`DropdownItem[]`	`[]`	菜单项配置数组
`placement`	`'top' \| 'bottom' \| 'left' \| 'right'`	`'bottom'`	首选位置
`offset`	`number`	`6`	与触发元素的间距（px）
`closeOnSelect`	`boolean`	`true`	选中后关闭
`disabled`	`boolean`	`false`	禁用触发
`width`	`number \| string`	`—`	固定宽度，省略则自适应
`open`	`boolean`	`—`	受控时使用

API · DropdownItem

属性	类型	说明
`key`	`string`	唯一标识（建议提供，便于 `select` 事件分流）
`label`	`string`	显示文本
`icon`	`string`	可选前置图标（emoji 或符号）
`disabled`	`boolean`	禁用项
`divider`	`boolean`	渲染为分隔线
`header`	`boolean`	渲染为分组标题（不可点）
`tone`	`'default' \| 'danger'`	语义色，`danger` 用于不可逆操作

API · Events

事件	参数	说明
`select` (Vue) / `onSelect` (React)	`(item, index)`	选中某一项时触发
`update:open` (Vue) / `onOpenChange` (React)	`(open: boolean)`	展开状态变化