UI
本页目录

组件 · 导航

DropdownMenu 下拉菜单

组合式下拉菜单。@selrux/ui@0.4.1 起 DropdownMenuTrigger 的 render 可换成任意可挂 ref 的元素或组件（Button、a、Avatar、span 等），等价于常见 asChild 用法；非按钮宿主自动补 role="button" 与 tabIndex，可用 nativeButton 固定首屏语义。

入口 @selrux/ui/dropdown-menu · 源码 src/components/dropdown-menu/index.ts · 16 个组件 · 发布状态 preview

使用建议

  • 避免：把 Trigger 写成无障碍缺失的纯装饰节点
  • 避免：杜撰 asChild 布尔 prop（本库用 render）
  • 限制：公开 API 以 @selrux/ui/dropdown-menu 的 d.ts 与源码为准；任意元素触发依赖 0.4.1+ 的 render / nativeButton

引入

tsx
import {
  DropdownMenu,
  DropdownMenuArrow,
  DropdownMenuCheckboxItem,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuItem,
  // …共 18 个导出
} from '@selrux/ui/dropdown-menu';

演练场

调节下方可实现的字面量属性，实时预览真实组件。函数、Portal、样式逃生口等见代码演示与 API 表。

默认关闭；点击触发器打开。

代码演示

基础用法

触发器打开菜单，textValue 用于键盘输入定位。

勾选与单选

CheckboxItem 多选开关，RadioGroup + RadioItem 互斥选择。

受控勾选与单选

CheckboxItem 的 checked / onCheckedChange、RadioGroup 的 value / onValueChange 受控；closeOnAction 决定选择后是否关闭；onAction 统一接收激活。

archived = false，sort = updated，最近激活：-

子菜单与项状态

DropdownMenuSub 嵌套子菜单（SubTrigger / SubContent）；Item 的 disabled、inset、closeOnAction={false} 与 onAction；CheckboxItem 的 disabled / inset。

最近操作：-

位置与尺寸

DropdownMenuContent 的 side / align / sideOffset / collisionPadding；根的 size；loop={false} 关闭首尾循环。

受控打开与关闭策略

open / onOpenChange 受控；closeOnEscape、closeOnOutsidePress 控制关闭方式；disabled 禁止打开；defaultOpen 为非受控初始值。

open = false

自定义触发器

render 可换成任意元素——Button、链接、Avatar、图标、纯文字或表格行内操作。非按钮元素自动补 role="button" 与 tabIndex，Enter / Space / ↓ 打开，关闭后焦点回到触发器；disabled 改用 aria-disabled。

项目负责人操作
Alpha运营
Beta运营

API

属性覆盖：示例用到 46 / 47 个自有属性（97.9%）

由 scripts/demo-coverage.mjs 统计，不含 className / style / 原生透传属性与纯转发事件。

  • DropdownMenu.returnFocusRef：焦点目标 ref，效果不可见；行为见“无障碍”
  • DropdownMenuPortal.container：Portal 挂载目标，默认 body；文档页无需更换挂载点

DropdownMenu

DropdownMenu 根。无布局 DOM。

属性说明类型默认值
size菜单字号与项内距；省略取 Provider → md。"xs" | "sm" | "md" | "lg" | "xl" | "2xl"-
disabled为真时禁止打开并立即抑制可见层。boolean-
loop当前菜单面上下导航是否循环。默认 true。booleantrue
closeOnEscape顶层 Esc 是否进入关闭流程。默认 true。booleantrue
closeOnOutsidePress外部主指针是否关闭整棵菜单树。默认 true。booleantrue
returnFocusRef整棵关闭后适用的返回焦点目标。RefObject<HTMLElement | null>-
open受控打开；与 defaultOpen 互斥。boolean-
defaultOpen非受控默认打开；挂载时读取一次。boolean-
onOpenChange请求变更；不强改父状态。((open: boolean, details: OverlayChangeDetails) => void)-
children复合子树。ReactNode-

DropdownMenuArrow

DropdownMenuArrow。

属性说明类型默认值
children装饰内容。ReactNode-

另有 278 项原生属性与事件继承自 HTMLAttributes，原样透传。

DropdownMenuCheckboxItem

DropdownMenuCheckboxItem。

属性说明类型默认值
textValue *typeahead 文本。string-
defaultChecked非受控默认选中。boolean-
disabled禁用。boolean-
inset起步缩进。boolean-
onAction可选；在 checked 变更后通知。((details: MenuActionDetails) => void)-
closeOnAction默认 false，保持菜单打开。booleanfalse
checked受控选中。boolean-
onCheckedChange选中变更。((checked: boolean, details: MenuActionDetails) => void)-
children可见内容。ReactNode-

另有 283 项原生属性与事件继承自 ButtonHTMLAttributes / HTMLAttributes，原样透传。

DropdownMenuContent

DropdownMenuContent。

属性说明类型默认值
style普通样式；受管定位不可绕过。CSSProperties-
side物理四向；根默认 bottom，子默认逻辑外向。"top" | "bottom" | "left" | "right"bottom
align对齐；默认 start。"start" | "end" | "center"start
sideOffset侧向间距（CSS px）。number-
collisionPadding碰撞内边距（CSS px）。number-
onEscapeKeyDownEsc；preventDefault 取消关闭。((event: KeyboardEvent) => void)-
onPointerDownOutside外部主指针；preventDefault 取消关闭。((event: Event) => void)-
children菜单面子树。ReactNode-

另有 277 项原生属性与事件继承自 HTMLAttributes，原样透传。

DropdownMenuGroup

DropdownMenuGroup。

属性说明类型默认值
children组内容。ReactNode-

另有 278 项原生属性与事件继承自 HTMLAttributes，原样透传。

DropdownMenuItem

DropdownMenuItem。

属性说明类型默认值
textValue *可访问名与 typeahead 来源；必填非空。string-
disabled禁用；aria-disabled，集合内仍可达。boolean-
variant危险动作外观。"default" | "destructive"-
inset无前导图标时的起步缩进。boolean-
onAction统一激活入口。((details: MenuActionDetails) => void)-
closeOnAction激活后是否关闭整棵菜单。默认 true。booleantrue
children可见内容。ReactNode-

另有 285 项原生属性与事件继承自 ButtonHTMLAttributes / HTMLAttributes，原样透传。

DropdownMenuLabel

DropdownMenuLabel。

属性说明类型默认值
children标签文本。ReactNode-

另有 279 项原生属性与事件继承自 HTMLAttributes，原样透传。

DropdownMenuPortal

DropdownMenuPortal。

属性说明类型默认值
container挂载目标；省略默认 body；显式 null 等待就绪。PortalContainerInputbody
childrenPortal 子树。ReactNode-

DropdownMenuRadioGroup

DropdownMenuRadioGroup。

属性说明类型默认值
defaultValue非受控默认值。string-
value受控值。string-
onValueChange值变更。((value: string, details: MenuActionDetails) => void)-
children组内项。ReactNode-

另有 277 项原生属性与事件继承自 HTMLAttributes，原样透传。

DropdownMenuRadioItem

DropdownMenuRadioItem。

属性说明类型默认值
value *组内唯一值。string-
textValue *typeahead 文本。string-
disabled禁用。boolean-
inset起步缩进。boolean-
onAction可选激活通知。((details: MenuActionDetails) => void)-
closeOnAction默认 false。booleanfalse
children可见内容。ReactNode-

另有 283 项原生属性与事件继承自 ButtonHTMLAttributes / HTMLAttributes，原样透传。

DropdownMenuSeparator

DropdownMenuSeparator。

无自有属性；其余 278 项原生属性继承自 HTMLAttributes。

DropdownMenuShortcut

DropdownMenuShortcut。

属性说明类型默认值
children提示文本。ReactNode-

另有 279 项原生属性与事件继承自 HTMLAttributes，原样透传。

DropdownMenuSub

DropdownMenuSub。

属性说明类型默认值
open受控打开。boolean-
defaultOpen非受控默认。boolean-
onOpenChange子菜单开关变更。((open: boolean, details: OverlayChangeDetails) => void)-
children子树。ReactNode-

DropdownMenuSubContent

DropdownMenuSubContent。

属性说明类型默认值
style普通样式；受管定位不可绕过。CSSProperties-
side物理四向；根默认 bottom，子默认逻辑外向。"top" | "bottom" | "left" | "right"bottom
align对齐；默认 start。"start" | "end" | "center"start
sideOffset侧向间距（CSS px）。number-
collisionPadding碰撞内边距（CSS px）。number-
onEscapeKeyDownEsc；preventDefault 取消关闭。((event: KeyboardEvent) => void)-
onPointerDownOutside外部主指针；preventDefault 取消关闭。((event: Event) => void)-
children菜单面子树。ReactNode-

另有 277 项原生属性与事件继承自 HTMLAttributes，原样透传。

DropdownMenuSubTrigger

DropdownMenuSubTrigger。

属性说明类型默认值
textValue *typeahead 文本。string-
disabled禁用。boolean-
inset起步缩进。boolean-
children可见内容。ReactNode-

另有 283 项原生属性与事件继承自 ButtonHTMLAttributes / HTMLAttributes，原样透传。

DropdownMenuTrigger

DropdownMenuTrigger。

属性说明类型默认值
render与 children 互斥。ReactElement<unknown, string | JSXElementConstructor<any>>-
nativeButtonrender 落到的宿主是否为原生 <button>。省略时自动判断：内置元素看标签，组件挂载后看实际 DOM。 渲染为链接、头像、图标、span 等非按钮宿主时，自动补 role="button"、tabIndex，禁用改为 aria-disabled 并移出 Tab 序列；SSR 首屏需要准确语义时可显式传 false。boolean-
children按钮内容。ReactNode-

另有 284 项原生属性与事件继承自 ButtonHTMLAttributes / HTMLAttributes，原样透传。

导出类型：DropdownMenuArrowProps、DropdownMenuCheckboxItemProps、DropdownMenuContentProps、DropdownMenuGroupProps、DropdownMenuItemProps、DropdownMenuItemVariant、DropdownMenuLabelProps、DropdownMenuPortalProps、DropdownMenuProps、DropdownMenuRadioGroupProps、DropdownMenuRadioItemProps、DropdownMenuSeparatorProps、DropdownMenuShortcutProps、DropdownMenuSize、DropdownMenuSubContentProps、DropdownMenuSubProps、DropdownMenuSubTriggerProps、DropdownMenuTriggerHostOptions、DropdownMenuTriggerProps、MenuActionDetails、OverlayAlign、OverlayChangeDetails、OverlayChangeReason、OverlaySide、PortalContainerInput

函数与常量

名称说明签名 / 类型
dropdownMenuSizes合法尺寸集合。Set<DropdownMenuSize>
resolveDropdownMenuSize按显式值、最近 Provider、md 的顺序解析尺寸。(size: DropdownMenuSize | undefined, configured: DropdownMenuSize | undefined) => DropdownMenuSize

无障碍

摘自源码 JSDoc。

  • DropdownMenu.closeOnEscape：顶层 Esc 是否进入关闭流程。
  • DropdownMenu.returnFocusRef：整棵关闭后适用的返回焦点目标。
  • DropdownMenuContent.onEscapeKeyDown：Esc；preventDefault 取消关闭。
  • DropdownMenuItem.disabled：禁用；aria-disabled，集合内仍可达。
  • DropdownMenuSubContent.onEscapeKeyDown：Esc；preventDefault 取消关闭。
  • 渲染为链接、头像、图标、span 等非按钮宿主时，自动补 role="button"、tabIndex，禁用改为
  • aria-disabled 并移出 Tab 序列；SSR 首屏需要准确语义时可显式传 false。