Menu 菜单

从触发器打开一组操作命令。

HeadlessStylesVueReactWeb Components

用法

从按钮打开一组操作

主题跟随站点浅色深色密度宽松紧凑对比度基线高对比方向从左到右从右到左

组件结构

加粗的是必需部件。

data-scope="menu"：trigger · positioner · content · item · item-icon · item-text · item-description · item-shortcut · item-suffix · item-indicator · separator · group · group-label · arrow

示例

图标与快捷键

为常用命令补充识别信息

主题跟随站点浅色深色密度宽松紧凑对比度基线高对比方向从左到右从右到左

分组

使用标题与分隔线组织命令

主题跟随站点浅色深色密度宽松紧凑对比度基线高对比方向从左到右从右到左

子菜单

将相关操作收进下一层

主题跟随站点浅色深色密度宽松紧凑对比度基线高对比方向从左到右从右到左

破坏性命令

用语气把删除一类命令与其余区分开

主题跟随站点浅色深色密度宽松紧凑对比度基线高对比方向从左到右从右到左

说明与快捷键

只交数据，副文本与按键提示自动落位

主题跟随站点浅色深色密度宽松紧凑对比度基线高对比方向从左到右从右到左

选择型条目

CheckboxItem 与 RadioGroup 修改持久设置，切换后菜单保持展开

主题跟随站点浅色深色密度宽松紧凑对比度基线高对比方向从左到右从右到左

设计指引

何时使用

• 收纳次要操作、账户命令或多级命令。

何时不用

• 选择并保留一个值时使用选择器。
• 一两个主要操作直接使用按钮。
• 站点主导航使用导航菜单。

特性

• collection 可直接生成条目、分组、图标、说明、快捷键提示和分隔线。条目的 icon 是图标记录，铺进文字之前的 item-icon（装饰态，读屏从条目文字取意），item-prefix 插槽也落在这一格、压过 icon。同一层（跨分组与分隔线，子菜单另算）里只要有一条带图标，所有条目都空出图标那一格，正文左缘对齐；整层都没有图标就不留。勾选与单选条目的勾在 item-indicator，两者各占一格。勾选与单选条目的勾是条目的最后一个部件，排在正文、说明与快捷键之后，与子菜单箭头同列，图标与普通条目左缘对齐；手写部件时写在哪都排到行尾。同一层有勾选条目时，普通条目的快捷键与它们同列。
• 只给 collection 时照标准结构铺：触发按钮（内容归作者，没写时取 label），定位层里的条目、分组与分隔线；带 children 的条目是一个嵌套的子菜单，它的触发条目与普通条目一样铺：图标取 icon（铺进 item-icon），文字取 label（铺进 item-text）。Vue / React 不写默认插槽与 Web Components 不写部件时生成的节点出自同一个结构函数；Web Components 的部件直接长在 <xh-menu> 里，触发按钮的内容与条目可用宿主直接子节点 slot="trigger"、slot="item:<值>" 等接管（只到根菜单这一层），子菜单生成嵌套的 <xh-menu submenu>，触发条目写着它的 value。指向锚点的箭头要手写结构时自己摆。
• anchor 换成外部锚点：由别处的按钮（工具栏命令等）受控打开时，把那颗按钮交给 anchor，菜单就贴着它定位、收起时焦点归还给它；按数据铺设时不再铺触发按钮。展开期间这颗按钮带 aria-haspopup、aria-expanded 与 aria-controls，收起或换锚点时还原；点它算菜单内的交互，开合交给打开它的那条命令。没有触发器替菜单命名，名字写在 translations.content 上。
• 触发按钮里只放图标（皮肤画的字形，没有文字）时，名字写在 translations.trigger 上，落成按钮的 aria-label；菜单容器经 aria-labelledby 指回触发器，跟着取到同一个名字。表格数据驱动模式下列头里的筛选钮就是这样一颗菜单。
• 条目可逐条声明语气，删除一类命令自带该族字色与高亮底。
• 快捷键提示贴行尾，与说明同档同色；它是纯装饰，读屏从命令文字取意。要读屏念出快捷键，条目再写 keyshortcuts，落成条目的 aria-keyshortcuts。
• 支持方向键、首字符检索、禁用条目和多级子菜单。数据驱动时节点写 children 即为子菜单入口，Vue / React 的默认树按 children 递归铺出下一层，深度不限，路由菜单这类按数据生成的多级菜单不必手写 Sub 部件；子层与本层同用 item / item-prefix / item-suffix 插槽，叶子的选中汇到根级 item-select。入口只能是普通条目，勾选与单选条目带 children 直接报错。子菜单那一层的勾选值与单选值写在带 children 的条目上（checkboxValue / radioValue），与子菜单自己的同名属性同义，写了即受控；按数据铺时子层的勾选改动不另外上报，勾选条目写 closeOnSelect，由根上的 item-select 得知。
• 子菜单使用安全三角避免指针斜向移动时误关闭。
• 内容高度缺省以 20rem 一档封顶，--xh-menu-max-h 可改；写 fitAvailableHeight 则只按落定那一侧的可用高度封顶，菜单栏的子菜单由菜单栏自动带上。
• 条目可组合图标、文字、说明和快捷键提示。
• CheckboxItem 与 RadioGroup / RadioItem 表达菜单内的持久选项，值分别由 checkboxValue 与 radioValue 控制；默认切换后保持展开，逐条可用 closeOnSelect 改为收起。
• 行首与行尾两格各有逐条钩子，只想加个图标不必把整条重搭；item 插槽仍是整条的接管口。
• 选中命令后发出根级 item-select 并关闭菜单链。

组合

• 触发器通常使用中性按钮，避免与页面主操作争夺层级。

最佳实践

• 破坏性命令放在末尾、与普通命令分隔，并同时给出 danger 语气和图标。
• 条目使用简短的动宾短语。
• 仅为已注册的快捷键显示提示。
• 一组选项只能取其一时使用 RadioGroup，不用多个互不关联的 CheckboxItem 模拟。

反模式

• 不要用命令菜单代替持久选择控件。
• 不要在菜单中放置长段说明或复杂表单。

API 参考

产物

层	值
自定义元素	<xh-menu>
Vue 组件	XhMenuArrow XhMenuCheckboxItem XhMenuContent XhMenuGroup XhMenuGroupLabel XhMenuItem XhMenuItemDescription XhMenuItemIcon XhMenuItemIndicator XhMenuItemShortcut XhMenuItemSuffix XhMenuItemText XhMenuPositioner XhMenuRadioGroup XhMenuRadioItem XhMenuRoot XhMenuSeparator XhMenuSub XhMenuSubTrigger XhMenuTrigger
组合式函数	useMenu
状态机	menuMachine
皮肤	@xihan-ui/styles/menu.css

Props

属性	类型	必填	说明
collection	MenuNode[]		条目数据，显示文本、禁用、逐条语气与分组的事实源。提供后条目部件只需声明 value。 未提供时回到这些事实都写在条目部件上的方式（语气写成条目的 data-tone）。
checkboxValue	string[]		checkbox 条目的选中集合；提供即受控。
defaultCheckboxValue	string[]
radioValue	MenuRadioValue		RadioGroup 身份到当前条目值的映射；提供即受控。
defaultRadioValue	MenuRadioValue
open	boolean		展开态，提供即受控；受控下内部不自行修改，只发 onOpenChange。
defaultOpen	boolean
anchor	HTMLElement | null		外部锚点：给了就锚在它上面、收起时焦点归还到它，不再取 trigger；用于由别处的按钮受控打开菜单，按数据铺设时不再铺触发按钮。 展开期间它带 aria-haspopup、aria-expanded、aria-controls，收起或换锚点时还原；点它算层内交互，不会先被判为层外交互关掉。 content 不再由触发器命名，名字写在 translations.content 上。只用于根菜单。
placement	Placement
offset	number
loop	boolean		方向键到达末尾是否回绕，默认 true。
dir	Direction		文字方向，默认 ltr。
tone	Tone		整张菜单的语气：brand / neutral / success / warning / danger / info。 只为浮层与作者放进来的内容备好该族颜色，不下发给条目——条目保持中性档， 逐条的语气写在 collection 的 tone 上（见 MenuNode）。
size	Size		尺寸：sm / md / lg，决定条目高度、内边距与字号档位。
fitAvailableHeight	boolean		内容只按落定那一侧的可用高度封顶，不叠菜单的固定上限（20rem 一档）；作者写的 --xh-menu-max-h 照样生效。 菜单栏的子菜单由菜单栏传入，再往下一层跟着上一层；单独用的菜单一般不写。
typeahead	boolean		首字符连打检索，默认开启。
disabled	boolean		整张菜单禁用：触发器不再展开，条目全部为 aria-disabled。
translations	Partial<MenuTranslations>
submenu	boolean		本菜单是另一张菜单的子菜单：触发器渲染为父菜单的条目形态 （经 getSubmenuTriggerProps），默认落位改为侧向，悬停触发默认开启。
openOnHover	boolean		悬停触发：进入触发器延时展开、经安全三角离开才收起。子菜单默认开启，普通菜单默认关闭。
hoverOpenDelay	number		悬停到展开的延时（ms），默认 100。
hoverCloseDelay	number		离开到收起的延时（ms），也是安全三角中的停滞上限，默认 300。
onOpenChange	(details: MenuOpenChangeDetails) => void		open 变化回调。
onItemSelect	(details: MenuItemSelectDetails) => void		条目被选中；菜单随之关闭。
onCheckboxValueChange	(details: MenuCheckboxValueChangeDetails) => void
onRadioValueChange	(details: MenuRadioValueChangeDetails) => void

MenuNode

collection 的元素。

字段	类型	必填	说明
value	string	是
kind	MenuChoiceKind		条目语义；普通命令缺省为 item。radio 条目必须同时声明 group。
label	string		展示文本；默认回退为 value。
disabled	boolean		条目禁用：方向键跳过它，但它仍可聚焦、仍是导航起点。
tone	Tone		该条命令自身动作的性质：删除写 danger、停用写 warning。不写即与其余条目同档。 只换字色与悬停 / 按下的面，不改字重与缩进，也不表达选中或校验；禁用压过它。 红字不是唯一通道，破坏性命令仍要配图标。整张菜单的 tone 不下发给条目。
icon	IconRecord		图标，写入 item-icon 部件，排在条目文字之前；未提供时本条不铺该部件。 纯装饰：读屏从条目文字取意，不念它。勾选与单选条目的勾仍在 item-indicator，两者各占一格。
description	string		副文本，写入 item-description 部件；未提供时本条不铺该部件。
shortcut	string		快捷键提示，写入 item-shortcut 部件；未提供时本条不铺该部件。 纯装饰：读屏从条目文字取意，不念它；只为真正注册了的组合写提示。
keyshortcuts	string		条目的 aria-keyshortcuts：读屏念的快捷键，写法照 ARIA（修饰键在前，如 Control+S、Meta+Shift+Z，几组用空格隔开）， 未提供时不写。与 shortcut 各管各：shortcut 是看得见的提示、读屏不念，这一项只给读屏，两处说的应是同一组键。
group	string		归属分组的身份值；相邻同值的条目收进同一个 group 部件。未提供时本条直接落在 content 上。
groupLabel	string		分组标题文字，取本组首个提供它的条目；本组无人提供时不铺 group-label。
separatorBefore	boolean		本条之前绘制一条分隔线；写在首条上不产出分隔线。本条领头一个分组时，分隔线绘制在分组外。
closeOnSelect	boolean		激活后是否关闭菜单；普通命令默认 true，checkbox / radio 默认 false。
children	MenuNode[]		子菜单的条目：给了 children 这一条就是子菜单的入口，Vue / React 的默认树按 children 递归铺出下一层， 深度不限；本条只能是普通条目（kind 为 item）。子层的选中经菜单树汇到根上，勾选与单选由各层自持。 手写部件时改用 Sub 部件；Web Components 由作者写 Light DOM，不读这一项。
checkboxValue	string[]		子菜单那一层的勾选值：只在带 children 的条目上读取，交给按数据铺出的那一层，与子菜单自己的 checkboxValue 同义， 写了即受控。按数据铺时子层的勾选改动不另外上报，勾选条目写 closeOnSelect，由根上的 item-select 得知。
radioValue	MenuRadioValue		子菜单那一层的单选值（组 → 选中的值）：只在带 children 的条目上读取，其余同 checkboxValue。

事件

自定义元素将载荷放在 detail；Vue 使用同名 emit。

事件	载荷	说明
open-change	MenuOpenChangeDetails	open 状态变化；detail 为 { open: boolean }
item-select	MenuItemSelectDetails	条目被选中（菜单随之关闭）；detail 为 { value: string }
checkbox-value-change	MenuCheckboxValueChangeDetails	checkbox 选中集合变化；detail 为 { value: string[] }
radio-value-change	MenuRadioValueChangeDetails	RadioGroup 选中映射变化；detail 为 { value: Record<string, string> }

插槽

仅列出带载荷的插槽。

Vue 组件	插槽	载荷	说明
XhMenuRoot	default	MenuRootSlotProps
XhMenuRoot	trigger	—
XhMenuRoot	item	MenuNodeMeta	整条的接管口：写了它，代铺的各格一概不铺，作者自己放置部件
XhMenuRoot	item-prefix	MenuNodeMeta	只接管行首那一格，其余槽照旧由数据铺
XhMenuRoot	item-suffix	MenuNodeMeta	只接管行尾那一格（计数、徽标、次级图标），其余槽照旧由数据铺
XhMenuSub	default	MenuSubSlotProps

React 适配器 props

只列各组件自己声明的那些：继承自 ComponentPropsWithRef 的 DOM 属性不在其中，根组件上与上面 Props 表同名的也不重复列。Vue 的对应物是上面的插槽表。

React 组件	属性	类型	必填	说明
XhMenuGroup	value	string	是
XhMenuItem	value	string	是
XhMenuItem	disabled	boolean		默认交给 connect 查询 collection，写死 false 会覆盖数据中的禁用。
XhMenuPositioner	container	() => Element | null		浮层挂载的容器；未提供时按全局配置，再未提供时挂载到 body。
XhMenuRadioGroup	value	string	是
XhMenuRoot	trigger	ReactNode		触发器中放置的内容；只提供 collection 时由它承载。
XhMenuRoot	triggerAsChild	boolean		只提供 collection 时，trigger 给出的节点直接作为触发器使用，不再外包一个 button。
XhMenuRoot	label	string		按数据铺设时触发按钮的文字；给了 trigger 时以它为准。
XhMenuRoot	renderItem	(node: MenuNodeMeta) => ReactNode		每个条目的自定义内容；未提供时使用 collection 中的 label。
XhMenuRoot	renderItemPrefix	(node: MenuNodeMeta) => ReactNode		只接管条目行首那一格；其余槽仍由数据铺。
XhMenuRoot	renderItemSuffix	(node: MenuNodeMeta) => ReactNode		只接管条目行尾那一格（计数、徽标、次级图标）；其余槽仍由数据铺。
XhMenuRoot	children	SlotChildren<MenuRootSlotProps>
XhMenuSub	value	string	是	它在父菜单中的条目身份。
XhMenuSub	label	string		按数据铺设时触发条目的文字；缺省取父菜单 collection 里这一条的 label。
XhMenuSub	icon	IconRecord		按数据铺设时触发条目的图标；缺省取父菜单 collection 里这一条的 icon。
XhMenuSub	disabled	boolean
XhMenuSub	collection	MenuNode[]
XhMenuSub	checkboxValue	string[]
XhMenuSub	defaultCheckboxValue	string[]
XhMenuSub	radioValue	MenuRadioValue
XhMenuSub	defaultRadioValue	MenuRadioValue
XhMenuSub	placement	Placement
XhMenuSub	offset	number
XhMenuSub	loop	boolean
XhMenuSub	openOnHover	boolean
XhMenuSub	hoverOpenDelay	number
XhMenuSub	hoverCloseDelay	number
XhMenuSub	dir	Direction		文字方向；默认继承父层。子层被迁移到浮层落点，无法继承父层的方向。
XhMenuSub	tone	Tone		语气；默认继承父层。子层是浮层落点下的同级节点，CSS 私有槽无法继承。
XhMenuSub	size	Size		尺寸；默认继承父层，理由同 tone。
XhMenuSub	fitAvailableHeight	boolean		只按可用高度封顶；默认继承父层，理由同 tone。
XhMenuSub	onCheckboxValueChange	MenuProps['onCheckboxValueChange']
XhMenuSub	onRadioValueChange	MenuProps['onRadioValueChange']
XhMenuSub	children	SlotChildren<MenuSubSlotProps>

状态

公开状态写入 data-state。

部件	取值
trigger	'open' | 'closed'
positioner	'open' | 'closed'
content	'open' | 'closed'
item-indicator	'checked' | 'unchecked' | 'checked' | 'unchecked' | undefined
submenu-trigger	'open' | 'closed'

以下名称仅用于内部状态机。

状态：open · closed

事件：OPEN · TOGGLE · CLOSE · PRESS.START · PRESS.END · CHECKBOX.VALUE.SET · RADIO.VALUE.SET · CONTROLLED.OPEN · CONTROLLED.CLOSE · ITEM.FOCUS · FOCUS.CLEAR · ITEM.LOST · ITEM.SELECT

判据：isOpenControlled · canPress · keepsMenuOpen

connect API

getXxxProps() 返回对应部件的宿主属性。

成员	类型	说明
open	boolean
disabled	boolean	整张菜单是否禁用。
collection	readonly MenuNodeMeta[]	由 collection 推导的条目元信息，按数据顺序排列；未提供 collection 时为空数组。
focusedValue	string | null	焦点锚点；收起时为 null。
checkboxValue	readonly string[]
radioValue	Readonly<MenuRadioValue>
isCheckboxItemChecked	(value: string) => boolean
isRadioItemChecked	(group: string, value: string) => boolean
setCheckboxValue	(next: string[]) => void
setRadioValue	(next: MenuRadioValue) => void
setOpen	(next: boolean) => void
getTriggerProps	() => T['button']
getPositionerProps	() => T['element']
getContentProps	() => T['element']
getItemProps	(props: MenuItemProps) => T['element']
getCheckboxItemProps	(props: MenuCheckboxItemProps) => T['element']
getRadioItemProps	(props: MenuRadioItemProps) => T['element']
getItemIconProps	(props: MenuAnyItemProps) => T['element']	条目文字之前的图标格；装饰态，读屏不念。
getItemTextProps	(props: MenuAnyItemProps) => T['element']
getItemIndicatorProps	(props: MenuAnyItemProps) => T['element']
getItemDescriptionProps	(props: MenuAnyItemProps) => T['element']
getItemShortcutProps	(props: MenuAnyItemProps) => T['element']
getItemSuffixProps	(props: MenuAnyItemProps) => T['element']
getSubmenuTriggerProps	(props: MenuItemProps) => T['element']	子菜单触发条目（submenu 模式）：既是父菜单中的一条 item（value 是它在父菜单 中的身份，父层的方向键与高亮照常识别它），又是本子菜单的触发器（aria-haspopup、 悬停 / 点击 / 右方向键展开）。父层的选中会跳过带 aria-haspopup 的条目。
getSeparatorProps	() => T['element']
getGroupProps	(props: MenuGroupProps) => T['element']
getRadioGroupProps	(props: MenuGroupProps) => T['element']
getGroupLabelProps	(props: MenuGroupProps) => T['element']
getArrowProps	() => T['element']

无障碍

键盘

规格出处：W3C APG

按键	生效条件	行为
Enter / Space / ArrowDown	focus in trigger	展开菜单并把焦点落到首个可用条目
ArrowUp	focus in trigger	展开菜单并把焦点落到末个可用条目
ArrowDown	open, focus in content	焦点移到下一个条目（禁用项跳过、尽头按 loop 回绕）
ArrowUp	open, focus in content	焦点移到上一个条目（禁用项跳过、尽头按 loop 回绕）
Home	open, focus in content	焦点移到首个可用条目
End	open, focus in content	焦点移到末个可用条目
Enter / Space	focus in item, not disabled	派发选中详情并关闭菜单，焦点归还 trigger
Enter / Space	held in item, not disabled	按住期间该条目投影 data-pressed，与指针 :active 同一副按压面；抬起、失焦或菜单收起撤下
Escape	open	关闭菜单并把焦点归还 trigger
Tab / Shift+Tab	open	关闭菜单，焦点不归还 trigger，按 Tab 序列自然离开

ARIA

以下属性由 connect 生成。

部件	属性	值
trigger	aria-controls	content 部件的 id
trigger	aria-expanded	'true' | 'false'
trigger	aria-haspopup	'menu'
trigger	aria-label	props.translations.trigger
content	aria-hidden	!open || undefined
content	aria-label	props.translations.content
content	aria-labelledby	trigger 部件的 id | undefined
content	role	'menu'
item-icon	aria-hidden	'true'
item-shortcut	aria-hidden	'true'
item-indicator	aria-hidden	'true'
separator	aria-orientation	'horizontal'
separator	role	'separator'
group	aria-labelledby	group-label 部件的 id
group	role	'group'
arrow	aria-hidden	'true'
submenu-trigger	aria-controls	content 部件的 id
submenu-trigger	aria-disabled	'true' | 'false'
submenu-trigger	aria-expanded	'true' | 'false'
submenu-trigger	aria-haspopup	'menu'
radio-group	aria-labelledby	group-label 部件的 id
submenu-trigger	role	'menuitem'
radio-group	role	'group'

样式参考

皮肤

@xihan-ui/styles/menu.css 按 [data-scope="menu"][data-part="trigger"] 部件选择器书写，发布产物以挂载类 .xh-scope-menu 代替其中的 data-scope（特异性相同），位于 xihan.components 层。覆盖样式使用 xihan.overrides，部件选择器照常可用。

forced-colors: active 下另有一套规则：颜色交给系统，边框与状态标记改用系统色关键字。

数据属性

由 connect 生成；条件不成立时不输出无值属性。

部件	属性	值
trigger	data-disabled	''（条件成立时才出现）
trigger	data-state	'open' | 'closed'
positioner	data-hidden	''（条件成立时才出现）
positioner	data-placement	定位引擎算出的实际落位
positioner	data-positioned	''（条件成立时才出现）
positioner	data-state	'open' | 'closed'
content	data-fit-available-height	''（条件成立时才出现）
content	data-instant	''（条件成立时才出现）
content	data-placement	定位引擎算出的实际落位
content	data-size	props.size
content	data-state	'open' | 'closed'
content	data-tone	props.tone
content	data-xh-material	'frosted'
item	data-xh-collection-context	'overlay'
item	data-xh-collection-item	''
item-icon	data-disabled	''（条件成立时才出现）
item-icon	data-highlighted	''（条件成立时才出现）
item-icon	data-xh-collection-slot	'icon'
item-text	data-disabled	''（条件成立时才出现）
item-text	data-highlighted	''（条件成立时才出现）
item-text	data-xh-collection-slot	'text'
item-description	data-disabled	''（条件成立时才出现）
item-description	data-highlighted	''（条件成立时才出现）
item-description	data-xh-collection-slot	'description'
item-shortcut	data-disabled	''（条件成立时才出现）
item-shortcut	data-highlighted	''（条件成立时才出现）
item-shortcut	data-xh-collection-slot	'shortcut'
item-suffix	data-disabled	''（条件成立时才出现）
item-suffix	data-highlighted	''（条件成立时才出现）
item-suffix	data-xh-collection-slot	'suffix'
item-indicator	data-disabled	''（条件成立时才出现）
item-indicator	data-highlighted	''（条件成立时才出现）
item-indicator	data-state	'checked' | 'unchecked' | 'checked' | 'unchecked' | undefined
item-indicator	data-xh-collection-slot	'indicator'
item-indicator	data-xh-menu-choice-indicator	item.kind | undefined
separator	data-xh-collection-separator	''
arrow	data-placement	定位引擎算出的实际落位
submenu-trigger	data-disabled	''（条件成立时才出现）
submenu-trigger	data-in-path	''（条件成立时才出现）
submenu-trigger	data-pressed	''（条件成立时才出现）
submenu-trigger	data-state	'open' | 'closed'
radio-group	data-value	group.value
submenu-trigger	data-xh-collection-context	'overlay'
submenu-trigger	data-xh-collection-item	''
submenu-trigger	data-xh-collection-size	props.size

CSS 变量

本组件公开覆盖槽由独立皮肤的实际消费位生成；默认来源、作用部件和状态均与 CSS 同源。

变量	部件	CSS 属性	状态	默认来源	说明
--xh-menu-arrow-size	arrow	--xh-_overlay-arrow-size	default	--xh-overlay-arrow-size	menu 的 arrow 部件 --xh-_overlay-arrow-size 覆盖槽。
--xh-menu-backdrop	content	-webkit-backdrop-filter backdrop-filter	xh-material=frosted	--xh-_material-backdrop	menu 的 content 部件 -webkit-backdrop-filter、backdrop-filter 覆盖槽。
--xh-menu-border	arrow content	border	default not([data-xh-action-control]) xh-material=frosted	--xh-_material-border --xh-material-frosted-border	menu 的 arrow、content 部件 border 覆盖槽。
--xh-menu-content-bg	arrow content	background	default not([data-xh-action-control]) xh-material=frosted	--xh-_material-bg --xh-material-frosted-bg	menu 的 arrow、content 部件 background 覆盖槽。
--xh-menu-content-fg	content	color	not([data-xh-action-control]) xh-material=frosted	--xh-_material-fg	menu 的 content 部件 color 覆盖槽。
--xh-menu-content-gap	content	gap	default	--xh-list-option-gap	menu 的 content 部件 gap 覆盖槽。
--xh-menu-content-px	content	padding-inline	default	--xh-space-1	menu 的 content 部件 padding-inline 覆盖槽。
--xh-menu-content-py	content	padding-block	default	--xh-surface-pad-xs	menu 的 content 部件 padding-block 覆盖槽。
--xh-menu-content-radius	content	border-radius	default	--xh-shape-overlay	menu 的 content 部件 border-radius 覆盖槽。
--xh-menu-content-shadow	content	box-shadow	not([data-xh-action-control]) xh-material=frosted	--xh-_material-shadow	menu 的 content 部件 box-shadow 覆盖槽。
--xh-menu-group-gap	group	gap	default	--xh-list-option-gap	menu 的 group 部件 gap 覆盖槽。
--xh-menu-group-label-fg	group-label	color	default	--xh-material-frosted-fg-muted	menu 的 group-label 部件 color 覆盖槽。
--xh-menu-group-label-font-size	group-label	font-size	default	--xh-text-caption-size	menu 的 group-label 部件 font-size 覆盖槽。
--xh-menu-group-label-font-weight	group-label	font-weight	default	--xh-font-weight-regular	menu 的 group-label 部件 font-weight 覆盖槽。
--xh-menu-group-label-mt	group-label	margin-block-start	default	--xh-space-2	menu 的 group-label 部件 margin-block-start 覆盖槽。
--xh-menu-group-label-px	group-label	padding-inline	default	--xh-_menu-item-px	menu 的 group-label 部件 padding-inline 覆盖槽。
--xh-menu-group-label-py	group-label	padding-block	default	--xh-space-1	menu 的 group-label 部件 padding-block 覆盖槽。
--xh-menu-highlight	content	background	not([data-xh-action-control]) xh-material=frosted	--xh-_material-highlight	menu 的 content 部件 background 覆盖槽。
--xh-menu-icon-size	content	--xh-icon-size	default size=lg size=sm	--xh-glyph-size-lg --xh-glyph-size-md --xh-glyph-size-sm	menu 的 content 部件 --xh-icon-size 覆盖槽。
--xh-menu-item-bg-active	item	background-color	in-path	--xh-bg-subtle	menu 的 item 部件 background-color 覆盖槽。
--xh-menu-item-bg-hover	item	background-color	disabled error highlighted hover is(:focus-visible, [data-highlighted]) not([aria-disabled='true'], [data-disabled], [aria-busy='true'], [data-error])	--xh-bg-subtle	menu 的 item 部件 background-color 覆盖槽。
--xh-menu-item-bg-pressed	item	background-color	disabled error is(:active, [data-pressed]) not([aria-disabled='true'], [data-disabled], [aria-busy='true'], [data-error]) pressed	--xh-bg-subtle-hover	menu 的 item 部件 background-color 覆盖槽。
--xh-menu-item-description-fg	item-description	color	default	--xh-material-frosted-fg-muted	menu 的 item-description 部件 color 覆盖槽。
--xh-menu-item-description-font-size	item-description	font-size	default	--xh-control-caption-md	menu 的 item-description 部件 font-size 覆盖槽。
--xh-menu-item-fg	item	color	default disabled error highlighted hover in-path is(:active, [data-pressed]) is(:focus-visible, [data-highlighted]) not([aria-disabled='true'], [data-disabled], [aria-busy='true'], [data-error]) pressed	--xh-material-frosted-fg	menu 的 item 部件 color 覆盖槽。
--xh-menu-item-font-size	item	font-size	default	--xh-_menu-font-size	menu 的 item 部件 font-size 覆盖槽。
--xh-menu-item-gap	item	gap	default	--xh-_menu-item-gap	menu 的 item 部件 gap 覆盖槽。
--xh-menu-item-h	item	min-block-size	default	--xh-_menu-item-h	menu 的 item 部件 min-block-size 覆盖槽。
--xh-menu-item-indicator-fg	item-indicator	color	default	--xh-_tone	menu 的 item-indicator 部件 color 覆盖槽。
--xh-menu-item-indicator-size	content group item item-indicator	--xh-icon-size block-size inline-size	default has(> [data-scope='menu'][data-part='item'] > [data-xh-menu-choice-indicator], > [data-scope='menu'][data-part='group'] > [data-scope='menu'][data-part='item'] > [data-xh-menu-choice-indicator]) not([aria-haspopup='menu'], [aria-checked]) xh-menu-choice-indicator	--xh-control-indicator-size	menu 的 content、group、item、item-indicator 部件 --xh-icon-size、block-size、inline-size 覆盖槽。
--xh-menu-item-leading	item	line-height	default	--xh-leading-normal	menu 的 item 部件 line-height 覆盖槽。
--xh-menu-item-px	item	padding-inline	default	--xh-_menu-item-px	menu 的 item 部件 padding-inline 覆盖槽。
--xh-menu-item-py	item	padding-block	default	--xh-_menu-item-py	menu 的 item 部件 padding-block 覆盖槽。
--xh-menu-item-radius	item	border-radius	default	--xh-shape-inset	menu 的 item 部件 border-radius 覆盖槽。
--xh-menu-layer	positioner	z-index	default	--xh-_layer	menu 的 positioner 部件 z-index 覆盖槽。
--xh-menu-max-h	content	max-block-size	default	--xh-_menu-max-h	menu 的 content 部件 max-block-size 覆盖槽。
--xh-menu-max-w	content	max-inline-size	default	--xh-overlay-max-w	menu 的 content 部件 max-inline-size 覆盖槽。
--xh-menu-min-w	content	min-inline-size	default	--xh-overlay-menu-min-w	menu 的 content 部件 min-inline-size 覆盖槽。
--xh-menu-separator-color	separator	background	default	--xh-material-frosted-separator	menu 的 separator 部件 background 覆盖槽。
--xh-menu-separator-my	separator	margin-block	default	--xh-space-0_5	menu 的 separator 部件 margin-block 覆盖槽。
--xh-menu-separator-radius	separator	border-radius	default	--xh-shape-pill	menu 的 separator 部件 border-radius 覆盖槽。
--xh-menu-separator-thickness	separator	block-size	default	--xh-stroke-thin	menu 的 separator 部件 block-size 覆盖槽。
--xh-menu-submenu-indicator-fg	item	background-color	default	currentColor	menu 的 item 部件 background-color 覆盖槽。
--xh-menu-submenu-indicator-size	item	block-size inline-size	default	--xh-control-indicator-size	menu 的 item 部件 block-size、inline-size 覆盖槽。
--xh-menu-trigger-bg-active	trigger	background	disabled not([data-disabled]) state=open	--xh-bg-subtle	menu 的 trigger 部件 background 覆盖槽。

动效

动效角色：按压 · 状态 · 出现（见动效规范）。

共享关键帧 xh-overlay-pop-in · xh-pop-out 由 family/motion.css 提供，皮肤 @import 它，单独引入仍成立。时长与缓动读动效令牌，改令牌即改全局节奏。

皮肤之外还有一段：退场由适配器的退场闸门把关，动画播完才真收起。

系统开启减弱动效时由令牌层统一收敛，皮肤不另作判断。

RTL

皮肤用逻辑属性排布（inline-start 一族），dir="rtl" 下自动镜像；另有按 dir 分支的规则。