Combobox 组合框

将输入框与候选列表结合，用于搜索并选择选项。

HeadlessStylesVueReactWeb Components

用法

搜索并选择城市：filter="contains" 按打的字筛候选，不必自己写过滤；选中后再展开看到全部城市

城市

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

组件结构

加粗的是必需部件。

data-scope="combobox"：root · label · control · tag-list · input · trigger · clear-trigger · positioner · content · item · item-prefix · item-text · item-description · item-suffix · item-indicator · group · group-label · empty · loading · hidden-input

示例

多选

已选城市在输入框前排成标签

常去城市

Beijing 北京Chengdu 成都

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

自定义值

选择候选项或输入新值

技术栈

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

分组

按分类组织候选项

城市

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

变体

设置输入框外观

outline

subtle

ghost

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

校验状态

标记无效输入

常驻城市

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

异步候选

查询远程数据

城市

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

自定义内容

在候选项中显示辅助信息

邮箱

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

候选虚拟化

过滤后的完整 collection 与 count 同步，高亮仍可跨窗口移动

城市

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

设计指引

何时使用

• 选项较多，需要通过输入快速筛选。
• 候选来自远程数据或允许输入自定义值。

何时不用

• 选项固定且不多时，使用选择器。
• 在正文中插入引用时，使用提及。
• 输入一组自由标签时，使用标签输入。

特性

• 支持单选、多选、分组和自定义值。
• 不写结构时按标准结构铺出整套部件（Vue 不写默认插槽、React 不给 children、Web Components 不写部件或只写 root），三端出自同一个结构函数：label 给标题文字、empty 给空态文字、clearable 带清空按钮，空态之后是在途占位（文字取 translations.loading，展开、在途且没有候选时露出），末尾一份表单影子，给了 name 或必填时才铺（必填时那份空值占位拦得住空表单），两样都没有就不铺。Web Components 里标题、空态、条目文字与行首行尾可以写在宿主的直接子节点上接管：slot="label"、slot="empty"、slot="item:<值>"、slot="item-prefix:<值>"、slot="item-suffix:<值>"。
• 多选的已选项在输入框前排成标签，与选择器同一套呈现：超出 maxTagCount（默认 3）合并为 +N，标签带删除钮，输入串为空时退格删掉最后一个；已选项被筛出候选后标签仍显示选中那一刻的文字。
• 候选可逐条声明语气，失效或需要留意的那条自带该族字色与高亮底。
• 候选可写副文本，第 2 行放一句解释，与标题同列、走 muted 档。
• 行首与行尾两格各有逐条钩子：只想加个图标或计数，不必把整条重搭。
• 同一层里只要有一条写了行首格，这一层的行首格都至少一个图标宽，没写的条目也空出这一格，正文左缘对齐；整层都没有就不留。
• 输入值、选中值与展开状态均可独立受控。
• loading 与 empty 分别表示加载和空结果。
• 内置过滤：给了 collection 再写 filter 即按用户打的字筛候选，contains 显示文本包含检索词、startsWith 以检索词开头，都不分大小写，也可以给函数 (node, query) => boolean 自己判。检索词是用户打的那段字，不是输入框里的字：选中后回显的选中项文字、inputBehavior="autocomplete" 补出的那段都不拿去筛，再展开看到全部候选。没写 filter 即不过滤，候选由调用方按 onInputValueChange 换，远程搜索就这么写。
• 支持异步候选和自定义条目内容。
• 候选面板与输入框所在的字段盒等宽，长候选在条目里截断。
• 通过隐藏输入参与原生表单提交。
• 占位态：首次加载时在途占位在文案前转一枚加载环；已有选项时后台刷新保留上一帧、只报 aria-busy，选项照常可选、不淡化（淡到禁用透明度会把文字压到 4.5:1 以下），在途占位让位；空态与加载文字取次要文字、上下内距一档。
• 值可以是任意类型：value、defaultValue 与 collection 里交进来数字、对象都行，onValueChange、v-model、插槽、renderItem 与自定义 filter 拿到的是原值；Vue 与 React 按 value 或 collection 推断值的类型，两处对不上、valueKey 写错字段编译即报错。数字转成字符串当键，对象值给 valueKey（字段名或取值函数），同一个选项每次都是新对象（接口刚取回来）也认得出来，不给按对象身份认；键也是条目的 data-value与随表单提交的值。Vue 的 h() 推断不了泛型，那里按宽松的类型检查；Web Components 经 property 交值，写 querySelector<XhComboboxElement<number>>("xh-combobox") 收窄。

组合

• 放进表单字段获得标签、说明与错误信息，字段状态会接到输入框上。
• 候选列表是常驻的列表框收进浮层的形态；选项固定且不需要输入时换成选择器。
• 长候选列表接入 Virtualizer 时，当下候选（给了 filter 即 api.collection，否则是调用方筛过的 collection）与 count 必须同批更新；高亮、aria-activedescendant 与确认仍按完整候选序列计算。

最佳实践

• 为异步查询提供加载和空结果反馈。
• 远程过滤应使用防抖，并取消过期请求。
• 允许自定义值时，明确提示 Enter 会采用当前输入。
• 使用标签说明字段含义，使用占位文本提示搜索方式。

反模式

• 未经说明就接受候选列表之外的值。
• 每次按键都立即发起远程请求。

API 参考

产物

层	值
自定义元素	<xh-combobox>
Vue 组件	XhComboboxClearTrigger XhComboboxContent XhComboboxControl XhComboboxEmpty XhComboboxGroup XhComboboxGroupLabel XhComboboxHiddenInput XhComboboxInput XhComboboxItem XhComboboxItemDeleteTrigger XhComboboxItemDescription XhComboboxItemIndicator XhComboboxItemPrefix XhComboboxItemSuffix XhComboboxItemText XhComboboxLabel XhComboboxLoading XhComboboxOverflowTag XhComboboxPositioner XhComboboxRoot XhComboboxTag XhComboboxTagLabel XhComboboxTagList XhComboboxTrigger
组合式函数	useCombobox
状态机	comboboxMachine
皮肤	@xihan-ui/styles/combobox.css

Props

属性	类型	必填	说明
labelled	boolean		作者渲染了 label 部件时置真，由适配器统计而不是判断标题文字是否有值。 为假时可聚焦部件不把 label 的 id 写进 aria-labelledby：指向未渲染的 id 是无效引用，作者写在控件上的 aria-label 也会被它压住。
ariaLabel	string		不显示出来的名字，写成 aria-label 落在与字段标签同一个部件上。 放进字段（字段接线）或渲染了 label 部件时名字以它们为准，aria-labelledby 盖过它。
collection	ComboboxNode<V>[]		候选数据，显示文本与禁用的事实源。给了 filter 时传全集，组件按用户打的字筛； 没给时过滤由调用方完成，传入的即当前应显示的候选。 提供后条目部件只需声明 value，显示文本也不再从 DOM 查询。 未提供时回到文本写在条目中、从 DOM 查询的方式。
valueKey	SelectionValueKey<V>		对象值怎样取键：字段名或取值函数。同一个选项每次都是新对象（接口刚取回来）时给它； 不给时按对象身份认。值不是对象时用不着。键也是条目的 data-value 与随表单提交的值。
filter	ComboboxFilterMode | ComboboxFilter<V>		内置过滤：'contains' 显示文本包含检索词，'startsWith' 以检索词开头，都不分大小写；也可以给一个函数自己判。 检索词是用户打的那段字，不是输入框里的字：选中后回显的选中项文字、内联补全补出的那段都不拿去筛， 再展开时看到的是全部候选。没给即不过滤（远程搜索就不给，候选由调用方按 onInputValueChange 换）。 只作用于 collection，不给 collection 时没有效果。
virtualizer	CollectionVirtualizer		当前候选（给了 filter 即筛过的那份，见 api.collection）与 Virtualizer 的滚动桥；count 必须与 api.collection.length 一致。
value	V | V[]		选中值。提供即受控：cell 直读 prop，写入只发 onValueChange 不落内部值。 单选写为裸串是简写，内部一律归一为数组。
defaultValue	V | V[]
inputValue	string		输入框中的字符串。提供即受控，与选中值各自独立。 没给 filter 时过滤不由组件完成：调用方用该串筛选条目，把筛选结果重新渲染进来。
defaultInputValue	string
open	boolean		展开态。提供即受控：内部不再自行修改，只发 onOpenChange。
defaultOpen	boolean
name	string		表单字段名；hidden-input 按选中值逐个生成同名字段，不使用分隔符编码。
form	string		原生表单 ID；显式关联外部表单，提交与 reset 使用同一所有者。
multiple	boolean		多选：选中为集合，选中后列表不收起、输入串清空以便继续筛选；已选项在输入框前排成标签。
maxTagCount	number		多选标签最多显示的数量，其余折叠进 overflowCount、合成 +N 标签；默认 3。
disabled	boolean		整个控件禁用：输入框与两个按钮都使用原生 disabled。
readOnly	boolean		只读：文字可选可复制，但展开、选中、清空一概不发生。
invalid	boolean		校验失败：输入框报告 aria-invalid，各角色节点带 data-invalid。
required	boolean		必填：输入框报告 aria-required，根与标题带 data-required（标题据此画星号）。 一个选中值一份表单影子，没选值时没有影子；此时补一份空值的占位影子带原生 required，拦下空表单的提交。
loading	boolean		候选加载中：列表报告 aria-busy，显示在途占位、隐藏空态占位。
loop	boolean		方向键到达末尾是否回绕，默认 true。
placeholder	string		输入框占位文字。
translations	Partial<ComboboxTranslations>		读屏文案；未提供的键使用英文默认值。
allowCustomValue	boolean		允许提交候选列表中没有的值（回车与失焦时把输入串本身收为选中值）。
openOnClick	boolean		点击输入框即展开，默认 false（只有触发按钮与方向键展开）。
inputBehavior	ComboboxInputBehavior		输入行为，默认 none。
placement	Placement
dir	Direction		文字方向，默认 ltr。只改写浮层在行内轴上 start 与 end 的落点。
offset	number
variant	ControlVariant		形态：outline / subtle / ghost，决定输入行的描边与底色使用方式。默认 outline。
tone	Tone		语气：brand / neutral / success / warning / danger / info，决定聚焦与选中强调使用哪族颜色。
size	Size		尺寸：sm / md / lg，决定输入行高度、内边距与字号档位。
onValueChange	(details: ComboboxValueChangeDetails<V>) => void		value 变化意图回调；受控时是唯一出口，非受控时随内部写入一并通知。
onClear	() => void		用户按清空钮（clear-trigger）清掉了值；先发值变化，再发它。程序化的 clear() 不发。
onInputValueChange	(details: ComboboxInputValueChangeDetails) => void		输入串变化回调：没给 filter 时调用方据此重新过滤候选。
onOpenChange	(details: ComboboxOpenChangeDetails) => void		open 变化意图回调；受控时是唯一出口，非受控时随内部转移一并通知。

ComboboxNode

collection 的元素。

字段	类型	必填	说明
value	V	是
label	string		展示文本，也是选中后回填输入框的取字来源；默认回退为值（不是字符串的值退回它的键）。
disabled	boolean		候选禁用：方向键跳过它，点击与回车都不选中它。
tone	Tone		该条候选自身的性质：危险选项写 danger、需要留意的写 warning。不写即与其余候选同档。 只换字色与悬停 / 按下的面，不表达选中与校验；选中的标记与禁用都压过它。 彩字不是唯一通道，要紧的差别仍要配图标或文案。整个组合框的 tone 不下发给候选。
description	string		副文本，写入 item-description 部件；未提供时本条不铺该部件。 它是第 2 行的说明，跟着条目走 muted 档，不跟语气；放不下一行的解释才用它， 一句话能说清的写进 label。

事件

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

事件	载荷	说明
value-change	ComboboxValueChangeDetails	选中集合变化；detail 为 { value: 值[] }，值是 value / collection 里交进来的原值（字符串、数字或对象）
clear	``	用户按清空钮（clear-trigger）清掉了值；先发值变化，再发它。程序化的 clear() 不发。
input-value-change	ComboboxInputValueChangeDetails	输入串变化；detail 为 { inputValue: string }，作者据此过滤候选
open-change	ComboboxOpenChangeDetails	open 状态变化；detail 为 { open: boolean }

插槽

仅列出带载荷的插槽。

Vue 组件	插槽	载荷	说明
XhComboboxRoot	default	ComboboxRootSlotProps<V>
XhComboboxRoot	label	—
XhComboboxRoot	empty	—
XhComboboxRoot	item	ComboboxNodeMeta<V>	只填条目的文字槽，副文本与首尾两格照旧各归各的
XhComboboxRoot	item-prefix	ComboboxNodeMeta<V>	只接管行首那一格，其余槽照旧由数据铺
XhComboboxRoot	item-suffix	ComboboxNodeMeta<V>	只接管行尾那一格（计数、徽标、次级图标），其余槽照旧由数据铺

React 适配器 props

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

React 组件	属性	类型	必填	说明
XhComboboxGroup	value	string	是
XhComboboxInput	as	ComboboxInputHost		输入框渲染为哪个标签，默认 input。 写 textarea 即多行宿主：connect 随之撤销 type、role 与 aria-expanded。
XhComboboxItem	value	unknown	是	条目代表的值，与根上的值同类型：字符串、数字或对象。
XhComboboxItem	disabled	boolean		默认交给 connect 查询 collection，写死 false 会覆盖数据中的禁用。
XhComboboxPositioner	container	() => Element | null		浮层挂载的容器；未提供时按全局配置，再未提供时挂载到 body。
XhComboboxRoot	label	ReactNode		标题文字。提供后不必再写 label 部件。
XhComboboxRoot	empty	ReactNode		无匹配时的提示语。提供后不必再写 empty 部件。
XhComboboxRoot	clearable	boolean		自动铺开时是否渲染清空按钮；手写部件模式不使用它，写了节点即可清空。
XhComboboxRoot	renderItem	(node: ComboboxNodeMeta<V>) => ReactNode		每个候选的自定义内容；未提供时使用 collection 中的 label。
XhComboboxRoot	renderItemPrefix	(node: ComboboxNodeMeta<V>) => ReactNode		只接管条目行首那一格；其余槽仍由数据铺。
XhComboboxRoot	renderItemSuffix	(node: ComboboxNodeMeta<V>) => ReactNode		只接管条目行尾那一格；其余槽仍由数据铺。
XhComboboxRoot	children	SlotChildren<ComboboxRootSlotProps<V>>
XhComboboxTag	value	unknown	是	它代表哪个选中值，与根上的值同类型（标签插槽里的 tag.value 原样交回来）。

状态

公开状态写入 data-state。

部件	取值
root	'open' | 'closed'
control	'open' | 'closed'
input	'open' | 'closed'
trigger	'open' | 'closed'
positioner	'open' | 'closed'
content	'open' | 'closed'
item	'checked' | 'unchecked'
item-prefix	'checked' | 'unchecked'
item-text	'checked' | 'unchecked'
item-description	'checked' | 'unchecked'
item-suffix	'checked' | 'unchecked'
item-indicator	'checked' | 'unchecked'
empty	'open' | 'closed'
loading	'open' | 'closed'

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

状态：open · closed

事件：OPEN · TOGGLE · CLOSE · CONTROLLED.OPEN · CONTROLLED.CLOSE · ESCAPE · INPUT.CHANGE · INPUT.SET · INPUT.BLUR · ITEM.HIGHLIGHT · HIGHLIGHT.CLEAR · ITEM.SELECT · VALUE.COMMIT · VALUE.SET · VALUE.CLEAR · ITEMS.SYNC · FORM.RESET · PRESS.START · PRESS.END · TAG_LIST.TRACKED

判据：isOpenControlled · isMultiple · hasHighlight · canPress

connect API

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

成员	类型	说明
open	boolean
translations	ComboboxTranslations	解析后的读屏文案；loading 没写内容时显示其中的 loading。
collection	readonly ComboboxNodeMeta<V>[]	当下的候选元信息：由 collection 推导，给了 filter 即按检索词筛过，按数据顺序排列；未提供 collection 时为空数组。
value	V[]	选中集合；单选模式下长度 ≤ 1，形状不随模式变化。
valueKeys	string[]	选中值的键，与 value 逐项对应：字符串值即它本身，别的值是编出来的键。条目的 data-value 与随表单提交的都是它。
inputValue	string	输入框中的字符串。
valueText	string | null	单选选中项的显示文本；无选中或多选时为 null。
highlightedValue	V | null	高亮候选；收起时为 null。焦点不在它身上，只经 aria-activedescendant 上报。
multiple	boolean
disabled	boolean
readOnly	boolean
invalid	boolean
required	boolean
empty	boolean	候选为空（已结算且条数为 0）且当前展开：empty 角色节点据此显示。
canClear	boolean	清空按钮当前是否可按。
tags	ComboboxTagMeta<V>[]	多选时可见的标签（受 maxTagCount 截断），与 value 同序；单选恒为空数组，选中项的文字在输入框里。
overflowCount	number	被 maxTagCount 折叠的标签数。
overflowText	string	+N 标签显示的文字（由 translations.overflowTag 计算）；没有折叠的标签时为空串。
isSelected	(value: V) => boolean
setOpen	(next: boolean) => void
setValue	(next: V[]) => void
setInputValue	(next: string) => void
clear	() => void
deselect	(value: V) => void	移除一个选中值。
getRootProps	() => T['element']
getLabelProps	() => T['label']
getControlProps	() => T['element']
getTagListProps	() => T['element']	标签行：放在盒里、输入框之前，收纳可见标签与 +N 标签；单选或无选中时整体 hidden。
getTagProps	(props: ComboboxTagProps<V>) => T['element']	标签：一个选中值一个，即库内 tag 的 root（data-scope="tag"）：语气、尺寸与禁用从本控件传下，形态按控件的面派生，另带 data-value 记录代表的值。
getTagLabelProps	() => T['element']	标签文字所在的块（tag 的 label）：截断落在这一层；标签与 +N 共用。
getOverflowTagProps	() => T['element']	被折叠的标签合成的一个：同样是 tag 的 root，显示 overflowText、带 data-count；没有折叠的标签时 hidden。
getItemDeleteTriggerProps	(props: ComboboxTagProps<V>) => T['button']	标签删除按钮：即所在标签那份 tag 的 close-trigger（data-scope="tag"），可及名使用 translations.deleteItem， 禁用与只读时保留位置、原生 disabled。不占 Tab 位，按下不夺焦：焦点留在输入框，键盘用退格删掉最后一个。
getInputProps	(props?: ComboboxInputProps) => T['input']	不传参即单行 input，产出与增加此参数前逐字相同。
getTriggerProps	() => T['button']
getClearTriggerProps	() => T['button']
getPositionerProps	() => T['element']
getContentProps	() => T['element']
getGroupProps	(props: ComboboxGroupProps) => T['element']
getGroupLabelProps	(props: ComboboxGroupProps) => T['element']
getItemProps	(props: ComboboxItemProps<V>) => T['element']
getItemPrefixProps	(props: ComboboxItemProps<V>) => T['element']
getItemTextProps	(props: ComboboxItemProps<V>) => T['element']
getItemDescriptionProps	(props: ComboboxItemProps<V>) => T['element']
getItemSuffixProps	(props: ComboboxItemProps<V>) => T['element']
getItemIndicatorProps	(props: ComboboxItemProps<V>) => T['element']
getEmptyProps	() => T['element']
getLoadingProps	() => T['element']	在途占位：与空态占位同一位置，两者不同时显示：加载期间显示它，空态让位。 与 content 是兄弟，同样不进入 role=listbox。
getHiddenInputProps	(props?: { value: string }) => T['input']	单值表单出口；按 api.value 逐个调用并生成同名 input，零选中不生成提交项。不给 value 是必填且没选值时的空值占位，带原生 required。

无障碍

键盘

规格出处：W3C APG

按键	生效条件	行为
ArrowDown	closed, focus in input	展开候选列表并把高亮落到首个可选候选
ArrowUp	closed, focus in input	展开候选列表并把高亮落到末个可选候选
Alt+ArrowDown	closed, focus in input	展开候选列表但不预选任何候选
ArrowDown	open	高亮移到下一个候选（禁用项跳过、尽头按 loop 回绕），焦点不动
ArrowUp	open	高亮移到上一个候选（禁用项跳过、尽头按 loop 回绕），焦点不动
Home	open	高亮移到首个可选候选；收起态不接管，光标照常跳到行首
End	open	高亮移到末个可选候选；收起态不接管，光标照常跳到行尾
Enter	open, 有高亮且未禁用	选中高亮候选：单选把输入串换成它的文本并收起，多选把它并入集合、清空输入串且不收起
Enter	open, 有高亮且未禁用、未只读、未加载，按住	按住期间高亮候选投影 data-pressed，与指针 :active 同一副按压面；抬起或失焦撤下，候选随浮层收起一并撤下。展开钮与清空钮在焦点落到自己身上时由 Enter / Space 按住投影，没有东西可清时清空钮不进
Enter	open, 无高亮且 allowCustomValue	把输入串本身收成选中值
Escape	open	先清除高亮；高亮已空时才收起列表，选中值不变
Alt+ArrowUp	open	收起列表，选中值不变
Tab / Shift+Tab	open	收起列表且不拦按键，焦点按 Tab 序列自然离开
Backspace	multiple, 输入串为空且已有选中	删掉最后一个已选项，它的标签在原处淡出；标签里的删除钮不占 Tab 位，键盘走这一条
可打印字符	focus in input	改写输入串并展开列表；过滤由调用方按 onInputValueChange 自己做

ARIA

以下属性由 connect 生成。

部件	属性	值
input	aria-activedescendant	item 部件的 id | undefined
input	aria-autocomplete	'both' | 'list'
input	aria-controls	content 部件的 id
input	aria-expanded	undefined | 'true' | 'false'
input	aria-haspopup	'listbox'
input	aria-invalid	'true' | 'false'
input	aria-label	props.ariaLabel
input	aria-labelledby	label 部件的 id | undefined
input	aria-required	'true' | 'false'
input	role	undefined | 'combobox'
trigger	aria-controls	content 部件的 id
trigger	aria-label	translations.trigger
clear-trigger	aria-label	translations.clearTrigger
content	aria-busy	'true' | undefined
content	aria-hidden	!open || undefined
content	aria-label	props.ariaLabel
content	aria-labelledby	label 部件的 id | undefined
content	aria-multiselectable	'true' | 'false'
content	role	'listbox'
item	aria-disabled	'true' | 'false'
item	aria-selected	'true' | 'false'
item	role	'option'
item-prefix	aria-hidden	'true'
item-indicator	aria-hidden	'true'
group	aria-labelledby	group-label 部件的 id
group	role	'group'
empty	role	'status'
loading	role	'status'
hidden-input	aria-hidden	'true'

样式参考

皮肤

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

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

数据属性

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

部件	属性	值
root	data-disabled	''（条件成立时才出现）
root	data-invalid	''（条件成立时才出现）
root	data-loading	''（条件成立时才出现）
root	data-readonly	''（条件成立时才出现）
root	data-required	''（条件成立时才出现）
root	data-size	props.size
root	data-state	'open' | 'closed'
root	data-tone	props.tone
root	data-variant	props.variant
label	data-disabled	''（条件成立时才出现）
label	data-required	''（条件成立时才出现）
control	data-disabled	''（条件成立时才出现）
control	data-invalid	''（条件成立时才出现）
control	data-readonly	''（条件成立时才出现）
control	data-state	'open' | 'closed'
control	data-variant	props.variant
control	data-xh-action-owner	''
control	data-xh-field-chrome	''
control	data-xh-field-size	props.size
tag-list	data-disabled	''（条件成立时才出现）
tag-list	data-instant	''（条件成立时才出现）
tag-list	data-xh-tag-list	''
input	data-disabled	''（条件成立时才出现）
input	data-invalid	''（条件成立时才出现）
input	data-readonly	''（条件成立时才出现）
input	data-state	'open' | 'closed'
input	data-xh-field-input	''
input	data-xh-field-layout	'textarea' | 'single-line'
trigger	data-disabled	''（条件成立时才出现）
trigger	data-pressed	''（条件成立时才出现）
trigger	data-state	'open' | 'closed'
trigger	data-xh-action-control	''
trigger	data-xh-action-display	'always'
trigger	data-xh-action-profile	'field-inset'
trigger	data-xh-action-size	props.size
trigger	data-xh-action-variant	'ghost'
clear-trigger	data-pressed	''（条件成立时才出现）
clear-trigger	data-xh-action-control	''
clear-trigger	data-xh-action-display	'has-value'
clear-trigger	data-xh-action-has-value	''（条件成立时才出现）
clear-trigger	data-xh-action-profile	'field-inset'
clear-trigger	data-xh-action-size	props.size
clear-trigger	data-xh-action-variant	'ghost'
positioner	data-hidden	''（条件成立时才出现）
positioner	data-placement	定位引擎算出的实际落位
positioner	data-positioned	''（条件成立时才出现）
positioner	data-size	props.size
positioner	data-state	'open' | 'closed'
positioner	data-tone	props.tone
positioner	data-variant	props.variant
content	data-instant	''（条件成立时才出现）
content	data-placement	定位引擎算出的实际落位
content	data-state	'open' | 'closed'
content	data-xh-material	'frosted'
item	data-disabled	''（条件成立时才出现）
item	data-highlighted	''（条件成立时才出现）
item	data-pressed	''（条件成立时才出现）
item	data-state	'checked' | 'unchecked'
item	data-tone	metaOf.get(item.value)?.tone
item	data-xh-collection-context	'overlay'
item	data-xh-collection-item	''
item	data-xh-collection-size	props.size
item-prefix	data-disabled	''（条件成立时才出现）
item-prefix	data-highlighted	''（条件成立时才出现）
item-prefix	data-state	'checked' | 'unchecked'
item-prefix	data-xh-collection-slot	'prefix'
item-text	data-disabled	''（条件成立时才出现）
item-text	data-highlighted	''（条件成立时才出现）
item-text	data-state	'checked' | 'unchecked'
item-text	data-xh-collection-slot	'text'
item-description	data-disabled	''（条件成立时才出现）
item-description	data-highlighted	''（条件成立时才出现）
item-description	data-state	'checked' | 'unchecked'
item-description	data-xh-collection-slot	'description'
item-suffix	data-disabled	''（条件成立时才出现）
item-suffix	data-highlighted	''（条件成立时才出现）
item-suffix	data-state	'checked' | 'unchecked'
item-suffix	data-xh-collection-slot	'suffix'
item-indicator	data-disabled	''（条件成立时才出现）
item-indicator	data-highlighted	''（条件成立时才出现）
item-indicator	data-state	'checked' | 'unchecked'
item-indicator	data-xh-collection-slot	'indicator'
empty	data-state	'open' | 'closed'
loading	data-loading	''（条件成立时才出现）
loading	data-state	'open' | 'closed'
loading	data-xh-loading-ring	''
overflow-tag	data-count	String(overflowCount)
tag	data-value	v

CSS 变量

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

变量	部件	CSS 属性	状态	默认来源	说明
--xh-combobox-action-bg	clear-trigger trigger	--xh-ink-surface background-color	default xh-ink-surface	--xh-_action-variant-bg-rest	combobox 的 clear-trigger、trigger 部件 --xh-ink-surface、background-color 覆盖槽。
--xh-combobox-action-bg-active	clear-trigger trigger	background-color	disabled is(:active, [data-pressed]) loading not([data-disabled]) not([data-loading]) pressed	--xh-_action-variant-bg-pressed	combobox 的 clear-trigger、trigger 部件 background-color 覆盖槽。
--xh-combobox-action-bg-hover	clear-trigger trigger	background-color	disabled hover loading not([data-disabled]) not([data-loading])	--xh-_action-variant-bg-hover	combobox 的 clear-trigger、trigger 部件 background-color 覆盖槽。
--xh-combobox-action-fg	clear-trigger trigger	color	default	--xh-fg-field-clear --xh-fg-muted	combobox 的 clear-trigger、trigger 部件 color 覆盖槽。
--xh-combobox-action-fg-hover	clear-trigger trigger	color	disabled hover loading not([data-disabled]) not([data-loading])	--xh-fg-default	combobox 的 clear-trigger、trigger 部件 color 覆盖槽。
--xh-combobox-action-font-size	clear-trigger trigger	font-size	default	--xh-text-secondary-size	combobox 的 clear-trigger、trigger 部件 font-size 覆盖槽。
--xh-combobox-action-radius	clear-trigger trigger	border-radius	default	--xh-shape-circle --xh-shape-inset	combobox 的 clear-trigger、trigger 部件 border-radius 覆盖槽。
--xh-combobox-action-size	clear-trigger trigger	block-size inline-size min-inline-size	default xh-action-profile=field-inset	--xh-_action-profile-visual-size	combobox 的 clear-trigger、trigger 部件 block-size、inline-size、min-inline-size 覆盖槽。
--xh-combobox-content-backdrop	content	-webkit-backdrop-filter backdrop-filter	xh-material=frosted	--xh-_material-backdrop	combobox 的 content 部件 -webkit-backdrop-filter、backdrop-filter 覆盖槽。
--xh-combobox-content-bg	content	background	not([data-xh-action-control]) xh-material=frosted	--xh-_material-bg	combobox 的 content 部件 background 覆盖槽。
--xh-combobox-content-border	content	border	not([data-xh-action-control]) xh-material=frosted	--xh-_material-border	combobox 的 content 部件 border 覆盖槽。
--xh-combobox-content-fg	content	color	not([data-xh-action-control]) xh-material=frosted	--xh-_material-fg	combobox 的 content 部件 color 覆盖槽。
--xh-combobox-content-gap	content	gap	default	--xh-list-option-gap	combobox 的 content 部件 gap 覆盖槽。
--xh-combobox-content-highlight	content	background	not([data-xh-action-control]) xh-material=frosted	--xh-_material-highlight	combobox 的 content 部件 background 覆盖槽。
--xh-combobox-content-max-h	content	max-block-size	default	--xh-overlay-menu-max-h	combobox 的 content 部件 max-block-size 覆盖槽。
--xh-combobox-content-max-w	content	max-inline-size	default	none	combobox 的 content 部件 max-inline-size 覆盖槽。
--xh-combobox-content-min-h	content	min-block-size	default	--xh-_combobox-h	combobox 的 content 部件 min-block-size 覆盖槽。
--xh-combobox-content-min-w	content	inline-size	default	--xh-overlay-menu-min-w	combobox 的 content 部件 inline-size 覆盖槽。
--xh-combobox-content-px	content	padding-inline	default	--xh-space-1	combobox 的 content 部件 padding-inline 覆盖槽。
--xh-combobox-content-py	content	padding-block	default	--xh-space-1	combobox 的 content 部件 padding-block 覆盖槽。
--xh-combobox-content-radius	content	border-radius	default	--xh-shape-overlay	combobox 的 content 部件 border-radius 覆盖槽。
--xh-combobox-content-shadow	content	box-shadow	not([data-xh-action-control]) xh-material=frosted	--xh-_material-shadow	combobox 的 content 部件 box-shadow 覆盖槽。
--xh-combobox-control-bg	control	background-color	xh-field-chrome	--xh-_field-variant-bg-rest	combobox 的 control 部件 background-color 覆盖槽。
--xh-combobox-control-bg-disabled	control	background-color	disabled xh-field-chrome	--xh-_field-variant-bg-disabled	combobox 的 control 部件 background-color 覆盖槽。
--xh-combobox-control-bg-hover	control	background-color	disabled hover invalid loading not(:focus-within) not([data-disabled]) not([data-invalid]) not([data-loading]) not([data-readonly]) readonly xh-field-chrome	--xh-_field-variant-bg-hover	combobox 的 control 部件 background-color 覆盖槽。
--xh-combobox-control-bg-readonly	control	background-color	readonly xh-field-chrome	--xh-_field-variant-bg-read-only	combobox 的 control 部件 background-color 覆盖槽。
--xh-combobox-control-border	control	border	xh-field-chrome	--xh-_field-variant-border-rest	combobox 的 control 部件 border 覆盖槽。
--xh-combobox-control-border-focus	control	border-color box-shadow	disabled focus-within not([data-disabled]) xh-field-chrome	--xh-_field-variant-border-focus	combobox 的 control 部件 border-color、box-shadow 覆盖槽。
--xh-combobox-control-border-hover	control	border-color	disabled hover invalid loading not(:focus-within) not([data-disabled]) not([data-invalid]) not([data-loading]) not([data-readonly]) readonly xh-field-chrome	--xh-_field-variant-border-hover	combobox 的 control 部件 border-color 覆盖槽。
--xh-combobox-control-border-invalid	control	border-color	invalid xh-field-chrome	--xh-_field-variant-border-invalid	combobox 的 control 部件 border-color 覆盖槽。
--xh-combobox-control-fg	control input	color	xh-field-chrome xh-field-input	--xh-fg-default	combobox 的 control、input 部件 color 覆盖槽。
--xh-combobox-control-gap	control	gap	xh-field-chrome	--xh-_combobox-gap	combobox 的 control 部件 gap 覆盖槽。
--xh-combobox-control-h	control	block-size min-block-size	has([data-xh-field-input][data-xh-field-layout='multi-tag']) has([data-xh-field-input][data-xh-field-layout='single-line']) has([data-xh-field-input][data-xh-field-layout='textarea']) xh-field-chrome xh-field-input xh-field-layout=multi-tag xh-field-layout=single-line xh-field-layout=textarea	--xh-_combobox-h	combobox 的 control 部件 block-size、min-block-size 覆盖槽。
--xh-combobox-control-min-w	control root	min-inline-size	default xh-field-chrome	--xh-control-min-w	combobox 的 control、root 部件 min-inline-size 覆盖槽。
--xh-combobox-control-px	control	padding-inline	xh-field-chrome	--xh-_combobox-px	combobox 的 control 部件 padding-inline 覆盖槽。
--xh-combobox-control-radius	control	border-radius	xh-field-chrome	--xh-shape-control	combobox 的 control 部件 border-radius 覆盖槽。
--xh-combobox-control-shadow	control	box-shadow	xh-field-chrome	none	combobox 的 control 部件 box-shadow 覆盖槽。
--xh-combobox-control-w	root	inline-size min-inline-size	default	--xh-control-w	combobox 的 root 部件 inline-size、min-inline-size 覆盖槽。
--xh-combobox-empty-fg	empty	color	default	--xh-material-frosted-fg-muted	combobox 的 empty 部件 color 覆盖槽。
--xh-combobox-empty-font-size	empty	font-size	default	--xh-_combobox-font-size	combobox 的 empty 部件 font-size 覆盖槽。
--xh-combobox-empty-px	empty	padding-inline	default	--xh-_combobox-item-px	combobox 的 empty 部件 padding-inline 覆盖槽。
--xh-combobox-empty-py	empty	padding-block	default	--xh-space-3	combobox 的 empty 部件 padding-block 覆盖槽。
--xh-combobox-gap	label root	gap margin-block-end	default	--xh-space-1	combobox 的 label、root 部件 gap、margin-block-end 覆盖槽。
--xh-combobox-group-gap	group	gap	default	--xh-list-option-gap	combobox 的 group 部件 gap 覆盖槽。
--xh-combobox-group-label-fg	group-label	color	default	--xh-material-frosted-fg-muted	combobox 的 group-label 部件 color 覆盖槽。
--xh-combobox-group-label-font-size	group-label	font-size	default	--xh-text-caption-size	combobox 的 group-label 部件 font-size 覆盖槽。
--xh-combobox-group-label-font-weight	group-label	font-weight	default	--xh-font-weight-medium	combobox 的 group-label 部件 font-weight 覆盖槽。
--xh-combobox-group-label-px	group-label	padding-inline	default	--xh-_combobox-item-px	combobox 的 group-label 部件 padding-inline 覆盖槽。
--xh-combobox-group-label-py	group-label	padding-block	default	--xh-space-1	combobox 的 group-label 部件 padding-block 覆盖槽。
--xh-combobox-group-spacing	group	margin-block-start	default	--xh-space-1_5	combobox 的 group 部件 margin-block-start 覆盖槽。
--xh-combobox-icon-size	control positioner root	--xh-icon-size	is([data-part='root'], [data-part='positioner']) size=lg size=sm xh-field-chrome	--xh-_field-size-glyph-size --xh-glyph-size-lg --xh-glyph-size-md --xh-glyph-size-sm	combobox 的 control、positioner、root 部件 --xh-icon-size 覆盖槽。
--xh-combobox-input-autofill-bg	input	box-shadow	-webkit-autofill autofill xh-field-input	--xh-bg-canvas	combobox 的 input 部件 box-shadow 覆盖槽。
--xh-combobox-input-autofill-fg	input	-webkit-text-fill-color	-webkit-autofill autofill xh-field-input	--xh-fg-default	combobox 的 input 部件 -webkit-text-fill-color 覆盖槽。
--xh-combobox-input-fg	input	color	xh-field-input	--xh-combobox-control-fg	combobox 的 input 部件 color 覆盖槽。
--xh-combobox-input-font-size	input	font-size	xh-field-input	--xh-_combobox-font-size	combobox 的 input 部件 font-size 覆盖槽。
--xh-combobox-input-min-w	input	min-inline-size	default	--xh-control-input-min-w	combobox 的 input 部件 min-inline-size 覆盖槽。
--xh-combobox-item-bg-hover	item	background-color	disabled error highlighted hover is(:focus-visible, [data-highlighted]) is([aria-selected='true'], [data-selected]) not([aria-disabled='true'], [data-disabled], [aria-busy='true'], [data-error]) selected xh-collection-context=overlay	--xh-bg-subtle	combobox 的 item 部件 background-color 覆盖槽。
--xh-combobox-item-bg-pressed	item	background-color	disabled error is(:active, [data-pressed]) is([aria-selected='true'], [data-selected]) not([aria-disabled='true'], [data-disabled], [aria-busy='true'], [data-error]) pressed selected xh-collection-context=overlay	--xh-bg-subtle-hover	combobox 的 item 部件 background-color 覆盖槽。
--xh-combobox-item-check-fg	item	color	disabled error highlighted hover is(:active, [data-pressed]) is(:focus-visible, [data-highlighted]) is([aria-selected='true'], [data-selected]) not([aria-disabled='true'], [data-disabled], [aria-busy='true'], [data-error]) pressed selected state=checked xh-collection-context=overlay xh-collection-slot=indicator	--xh-combobox-item-indicator-fg	combobox 的 item 部件 color 覆盖槽。
--xh-combobox-item-fg	item	color	default disabled error highlighted hover is(:active, [data-pressed]) is(:focus-visible, [data-highlighted]) is([aria-selected='true'], [data-selected]) not([aria-disabled='true'], [data-disabled], [aria-busy='true'], [data-error]) pressed selected xh-collection-context=overlay	--xh-material-frosted-fg	combobox 的 item 部件 color 覆盖槽。
--xh-combobox-item-fg-selected	item	color	disabled error highlighted hover is(:active, [data-pressed]) is(:focus-visible, [data-highlighted]) is([aria-selected='true'], [data-selected]) not([aria-disabled='true'], [data-disabled], [aria-busy='true'], [data-error]) pressed selected xh-collection-context=overlay	--xh-combobox-item-fg	combobox 的 item 部件 color 覆盖槽。
--xh-combobox-item-font-size	item	font-size	default	--xh-_combobox-font-size	combobox 的 item 部件 font-size 覆盖槽。
--xh-combobox-item-font-weight-selected	item	font-weight	disabled error highlighted hover is(:active, [data-pressed]) is(:focus-visible, [data-highlighted]) is([aria-selected='true'], [data-selected]) not([aria-disabled='true'], [data-disabled], [aria-busy='true'], [data-error]) pressed selected xh-collection-context=overlay	--xh-font-weight-medium	combobox 的 item 部件 font-weight 覆盖槽。
--xh-combobox-item-gap	item	margin-inline-end margin-inline-start	default xh-collection-slot=indicator xh-collection-slot=prefix xh-collection-slot=shortcut xh-collection-slot=suffix	--xh-_combobox-gap	combobox 的 item 部件 margin-inline-end、margin-inline-start 覆盖槽。
--xh-combobox-item-h	item	min-block-size	default	--xh-_combobox-item-h	combobox 的 item 部件 min-block-size 覆盖槽。
--xh-combobox-item-indicator-fg	item	color	disabled error highlighted hover is(:active, [data-pressed]) is(:focus-visible, [data-highlighted]) is([aria-selected='true'], [data-selected]) not([aria-disabled='true'], [data-disabled], [aria-busy='true'], [data-error]) pressed selected state=checked xh-collection-context=overlay xh-collection-slot=indicator	--xh-_combobox-accent	combobox 的 item 部件 color 覆盖槽。
--xh-combobox-item-indicator-size	item-indicator	--xh-icon-size block-size inline-size	default	--xh-control-indicator-size	combobox 的 item-indicator 部件 --xh-icon-size、block-size、inline-size 覆盖槽。
--xh-combobox-item-leading	item	line-height	default	--xh-leading-normal	combobox 的 item 部件 line-height 覆盖槽。
--xh-combobox-item-px	item	padding-inline	default	--xh-_combobox-item-px	combobox 的 item 部件 padding-inline 覆盖槽。
--xh-combobox-item-py	item	padding-block	default	--xh-_combobox-item-py	combobox 的 item 部件 padding-block 覆盖槽。
--xh-combobox-item-radius	item	border-radius	default	--xh-shape-inset	combobox 的 item 部件 border-radius 覆盖槽。
--xh-combobox-label-fg	label	color	default	--xh-fg-muted	combobox 的 label 部件 color 覆盖槽。
--xh-combobox-label-fg-disabled	label	color	disabled	--xh-fg-muted	combobox 的 label 部件 color 覆盖槽。
--xh-combobox-label-font-size	label	font-size	default	--xh-text-label-size	combobox 的 label 部件 font-size 覆盖槽。
--xh-combobox-label-font-weight	label	font-weight	default	--xh-text-label-weight	combobox 的 label 部件 font-weight 覆盖槽。
--xh-combobox-label-gap	label	margin-block-end	default	--xh-space-2	combobox 的 label 部件 margin-block-end 覆盖槽。
--xh-combobox-layer	positioner	z-index	default	--xh-_layer	combobox 的 positioner 部件 z-index 覆盖槽。
--xh-combobox-loading-fg	loading	color	default	--xh-material-frosted-fg-muted	combobox 的 loading 部件 color 覆盖槽。
--xh-combobox-loading-font-size	loading	font-size	default	--xh-_combobox-font-size	combobox 的 loading 部件 font-size 覆盖槽。
--xh-combobox-loading-px	loading	padding-inline	default	--xh-_combobox-item-px	combobox 的 loading 部件 padding-inline 覆盖槽。
--xh-combobox-loading-py	loading	padding-block	default	--xh-space-3	combobox 的 loading 部件 padding-block 覆盖槽。
--xh-combobox-placeholder-fg	input	color	placeholder xh-field-input	--xh-fg-subtle	combobox 的 input 部件 color 覆盖槽。
--xh-combobox-tag-list-gap	tag-list	gap	xh-tag-list	--xh-space-1	combobox 的 tag-list 部件 gap 覆盖槽。

动效

动效角色：按压 · 状态 · 切换 · 指示与换位 · 出现 · 列表（见动效规范）。

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

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

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

响应式

皮肤另按输入能力分档：hover: hover · hover: none：同一份皮肤在触屏与带指针的设备上不一样，与视口宽度无关。

RTL

皮肤用逻辑属性排布（inline-start 一族），dir="rtl" 下自动镜像。