DropdownMenu
从临时操作或导航菜单中选择。中文惯用名：下拉菜单。设计文档原名：Dropdown。
稳定本期新增已接入
元信息
| 字段 | 值 |
|---|---|
| 规范 ID | component.dropdown-menu |
| 名称 | DropdownMenu |
| 二级分类 | 导航（navigation） |
| 用途 | 从临时操作或导航菜单中选择 |
| 描述 | 中文惯用名：下拉菜单。设计文档原名：Dropdown。 |
预览
静态结构：Base UI Menu.Root（data-slot="dropdown-menu"）——children 为触发元素，经 span（data-slot="dropdown-menu-trigger-wrap"）接入 Trigger（以 span 包装避免按钮嵌套按钮）；弹出内容 data-slot="dropdown-menu-content"，菜单项 data-slot="dropdown-menu-item"（danger 项写 data-variant="destructive"，文字与聚焦底色转 destructive；disabled 项 data-disabled 置灰不可点）；项内 icon 渲染于文字前（Icon size="sm"）；点击项触发 onSelect 并传出该项 value。本预览为受控接收用法：选中值经 events.onSelect 写回 state。
DSL 结构
{
"type": "DropdownMenu",
"props": {
"items": [
{
"label": "重命名",
"value": "rename",
"icon": "pencil"
},
{
"label": "分享",
"value": "share",
"icon": "share"
},
{
"label": "删除",
"value": "delete",
"icon": "trash",
"danger": true
}
]
},
"events": {
"onSelect": {
"action": "setState",
"params": {
"selected": "${event}"
}
}
},
"children": [
{
"type": "Button",
"props": {
"text": "打开菜单",
"variant": "default"
}
}
]
}何时用
何时使用
- 从临时操作集合中选择：列表行的「重命名 / 分享 / 删除」、页面右上角的更多操作。
- 操作入口需要收纳：主操作留按钮，次要操作收进下拉，保持界面清爽。
- 需要区分危险操作：danger 项以 destructive 语义呈现，与普通项拉开距离。
何时不用
- 站点级 / 模块级导航：使用 NavigationMenu、Menu。
- 需要承载复杂内容或交互（表单、多行说明、勾选组）：使用 Popover。
- 只有一个操作：直接放 Button，不必包一层下拉。
变体
| 变体 | 视觉形态 | 适用场景 |
|---|---|---|
| 默认项 | 浮层内一行一项，hover / 聚焦高亮 | 重命名、复制链接等常规操作 |
| 危险项 | destructive 文字色（聚焦时浅红底） | 删除、移除成员等破坏性操作 |
| 带图标项 | 图标 + 文案 | 操作类型需要快速识别 |
| 禁用项 | 置灰不可点（data-disabled） | 无权限或前置条件不满足的操作 |
API 属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
items | DropdownMenuItemData[] | [] | 菜单项（可含表达式解析后的数组）：{ label, value, disabled?, danger?, icon? } |
onSelect | (value: string) => void | — | 选中事件，传出选中项 value（Renderer 绑定 events.onSelect） |
children | DslNode[] | — | 触发元素（DSL 子树，经 Renderer children 机制渲染，常为 Button） |
className / style | string / CSSProperties | — | 通用：挂在弹出内容根节点（不是触发元素）的 class 合并 / 内联样式 |
使用规范
- 触发元素用 Button（default / text 变体），不放裸文本；触发文案表明「更多操作」而非具体某项。
- 危险项固定放最后并保持 destructive 语义；删除类操作仍需二次确认（Popconfirm / Dialog）。
- 项文案用动词短语（「重命名」），不用「操作一 / 操作二」这类占位。
- 菜单项数量控制在 6 项以内，超出说明该拆分为独立页面或面板。
- 选中结果只经 onSelect 传出 value，组件不感知业务含义；由消费方按 value 分发动作。
正例
- ✓ 列表行操作：Button「更多」+ DropdownMenu（重命名 / 分享 / 删除），value 驱动动作分发。
- ✓ 卡片右上角：图标按钮触发下拉，删除项 danger 且走二次确认。
反例
- ✕ 用 DropdownMenu 做站点顶部导航（应使用 NavigationMenu）。
- ✕ 把表单或说明性多行内容放进下拉项（应使用 Popover）。
Design Token 映射
不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。