组合框

概述

用于搜索并从选项列表中快速选择值的组合框组件，支持显式锚点组合、可清空输入以及完整的弹层/过滤交互。输入即过滤，键盘导航遵循 WAI-ARIA combobox 模式。适用于需要输入关键字过滤列表的场景；无需输入的选择请用 SSelect；对文本做模糊匹配建议请用 SAutocomplete。

用法

特性

🔍 输入即过滤，三态过滤模型（有匹配 / 空 / 未参与）
⌨️ 完整键盘导航——方向键、Enter/Space 选择、typeahead、Escape 关闭
📜 可选虚拟滚动（ComboboxVirtualizer）
🗂 分组，支持组标签与分隔符
🧹 触发器清除图标取消选择（clearable）；浮窗内取消按钮仅清空搜索输入
🧩 ComboboxValue 原语渲染已选标签（或占位符），便于自定义触发器布局
📊 数据驱动 ComboboxCompact API——items（选项使用 label / value 字段）+ 分组
🎛 受控/非受控，支持 v-model:open 与过滤语义（ignoreFilter、resetSearchTermOnBlur）
♿ 完整无障碍支持——role="combobox" / listbox / option、aria-activedescendant、axe 零违规

演示

基础

100%

Selected: None

分组

100%

自定义样式

100%

Value

100%

API

Aria 层

Combobox<M>

38 属性11 事件12 插槽

属性

属性名	类型	默认值	描述
class	ClassValue	—	应用于根元素的额外类名。
size	ThemeSize	—	组件的视觉尺寸。
ui	Partial<ComboboxUi>	—	该组件的按槽类重写。
items	ComboboxOptionData[]	—	由该组件渲染的项。
placeholder	string	—	占位符。
searchPlaceholder	string	—	搜索占位符。
clearLabel	string	—	标签清晰。
emptyLabel	string	—	空标签。
anchorProps	ComboboxAnchorProps	—	转发给锚元素的属性。
triggerProps	ComboboxTriggerProps	—	转发给触发元素的属性。
cancelProps	ComboboxCancelProps	—	转发给 cancel 元素的属性。
valueProps	ComboboxValueProps	—	转发至 value 元素的属性。
portalProps	ComboboxPortalProps	—	转发给 portal 元素的属性。
contentProps	ComboboxContentProps	—	转发给内容元素的属性。
viewportProps	ComboboxViewportProps	—	转发给视口元素的属性。
inputProps	ComboboxInputProps	—	转发给输入元素的属性。
emptyProps	ComboboxEmptyProps	—	转发给空元素的属性。
groupProps	ListboxGroupProps	—	转发给 group 元素的属性。
groupLabelProps	ComboboxGroupLabelProps	—	转发至组标签元素的属性。
itemProps	ComboboxItemProps	—	转发给 item 元素的属性。
itemIndicatorProps	ComboboxItemIndicatorProps	—	转发至项指示器元素的属性。
separatorProps	ComboboxSeparatorProps	—	转发给分隔符元素的属性。
open	boolean	—	下拉列表（Combobox）的受控打开状态。可通过 `v-model:open` 进行绑定。
defaultOpen	boolean	—	下拉列表框在初始渲染时的打开状态。<br> 当您无需控制其打开状态时使用。
resetSearchTermOnBlur	boolean	`true`	当下拉列表（Combobox）输入框失去焦点时，是否重置搜索词（searchTerm）
resetSearchTermOnSelect	boolean	`true`	当下拉列表（Combobox）的值被选中时，是否重置搜索词（searchTerm）
openOnFocus	boolean	`false`	当输入框获得焦点时是否打开下拉列表
openOnClick	boolean	`false`	点击输入框时是否打开下拉列表
ignoreFilter	boolean	—	当值为 `true` 时，禁用默认过滤器
clearable	boolean	—	当 `multiple` 为 false 时，是否可以清除所选项目。
modelValue	(M extends true ? string[] : string)	—	所选项的受控值。当需要控制项的状态时使用此属性。可通过 `v-model` 进行绑定。
defaultValue	(M extends true ? string[] : string)	—	所选项的默认值。当需要设置项的初始状态时，请使用此选项。
multiple	M	—	用于确定一次可选择“单个”还是“多个”项目。此属性将覆盖根据 `modelValue` 和 `defaultValue` 推断出的类型。
disabled	boolean	—	当值为 `true` 时，禁止用户与列表框进行交互
dir	Direction	—	列表框的阅读方向（如适用）。<br> 若省略，则从全局 `ConfigProvider` 继承，或默认采用 LTR（从左到右）阅读模式。
name	string	—	字段的名称。作为名称/值对的一部分，与其所属表单一同提交。
highlightOnHover	boolean	—	当值为 `true` 时，将鼠标悬停在项目上会触发高亮显示
required	boolean	—	当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。

事件

事件名	参数	描述
update:modelValue	M extends true ? string[] : string	—
highlight	CollectionItemData<ListboxCollectionItemData> \| undefined	当选中元素发生变化时的事件处理程序。
update:open	boolean	在打开状态发生变化时触发。
escapeKeyDown	KeyboardEvent	当 Esc 键被按下时触发的事件处理程序。可被阻止。
pointerDownOutside	PointerDownOutsideEvent	当 `pointerdown` 事件发生在 `DismissableLayer` 外部时调用的事件处理程序。可被阻止。
focusOutside	FocusOutsideEvent	当焦点移出 `DismissableLayer` 时触发的事件处理程序。可被阻止。
interactOutside	PointerDownOutsideEvent \| FocusOutsideEvent	当在 `DismissableLayer` 外部发生交互时触发的事件处理程序。具体而言，当 `pointerdown` 事件在该区域外部发生，或焦点移出该区域时触发。此事件可被阻止。
openAutoFocus	Event	在打开页面时自动聚焦时触发的事件处理程序。可被阻止。
closeAutoFocus	Event	在关闭时自动聚焦时触发的事件处理程序。可被阻止。
placed	—	当定位器被放置时调用的事件处理程序
select	SelectEvent<string>	当选中某项时触发的事件处理程序。<br> 可以通过调用 `event.preventDefault` 来阻止该事件。

插槽

插槽名	参数	描述
trigger-leading	—	触发器首槽的自定义内容。
trigger-value	ComboboxCompactTriggerValueSlotProps<M>	触发值插槽的自定义内容。
trigger-trailing	—	触发器尾部插槽的自定义内容。
trigger-icon	—	触发图标槽位的自定义内容。
input-leading	ComboboxCompactInputSlotProps	输入首槽的自定义内容。
input-trailing	ComboboxCompactInputSlotProps	输入末尾槽位的自定义内容。
empty	—	为空槽位添加自定义内容。
group-label	ComboboxCompactGroupLabelSlotProps	组标签槽位的自定义内容。
item-leading	ComboboxCompactItemSlotProps	用于项目引导槽位的自定义内容。
item-text	ComboboxCompactItemSlotProps	针对“项文本”插槽的自定义内容。
item-trailing	ComboboxCompactItemSlotProps	用于项目尾部槽位的自定义内容。
item-indicator	ComboboxCompactItemSlotProps	项目指示符插槽的自定义内容。

ComboboxAnchor

3 属性

属性

属性名	类型	默认值	描述
reference	ReferenceElement	—	—
asChild	boolean	—	将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。
as	AsTag \| Component	'div'	该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。

ComboboxArrow

ComboboxCancel

3 属性

属性

属性名	类型	默认值	描述
disabled	boolean	—	该组件是否已禁用。
asChild	boolean	—	将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。
as	AsTag \| Component	'div'	该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。

ComboboxClear

2 属性

属性

属性名	类型	默认值	描述
ariaLabel	string	—	“清除”按钮的 ARIA 标签。
disabled	boolean	—	“清除”按钮是否处于禁用状态。

ComboboxCompact<M>

35 属性11 事件12 插槽

属性

属性名	类型	默认值	描述
items	ComboboxOptionData[]	—	由该组件渲染的项。
placeholder	string	—	占位符。
searchPlaceholder	string	—	搜索占位符。
clearLabel	string	—	标签清晰。
emptyLabel	string	—	空标签。
anchorProps	ComboboxAnchorProps	—	转发给锚元素的属性。
triggerProps	ComboboxTriggerProps	—	转发给触发元素的属性。
cancelProps	ComboboxCancelProps	—	转发给 cancel 元素的属性。
valueProps	ComboboxValueProps	—	转发至 value 元素的属性。
portalProps	ComboboxPortalProps	—	转发给 portal 元素的属性。
contentProps	ComboboxContentProps	—	转发给内容元素的属性。
viewportProps	ComboboxViewportProps	—	转发给视口元素的属性。
inputProps	ComboboxInputProps	—	转发给输入元素的属性。
emptyProps	ComboboxEmptyProps	—	转发给空元素的属性。
groupProps	ListboxGroupProps	—	转发给 group 元素的属性。
groupLabelProps	ComboboxGroupLabelProps	—	转发至组标签元素的属性。
itemProps	ComboboxItemProps	—	转发给 item 元素的属性。
itemIndicatorProps	ComboboxItemIndicatorProps	—	转发至项指示器元素的属性。
separatorProps	ComboboxSeparatorProps	—	转发给分隔符元素的属性。
open	boolean	—	下拉列表（Combobox）的受控打开状态。可通过 `v-model:open` 进行绑定。
defaultOpen	boolean	—	下拉列表框在初始渲染时的打开状态。<br> 当您无需控制其打开状态时使用。
resetSearchTermOnBlur	boolean	`true`	当下拉列表（Combobox）输入框失去焦点时，是否重置搜索词（searchTerm）
resetSearchTermOnSelect	boolean	`true`	当下拉列表（Combobox）的值被选中时，是否重置搜索词（searchTerm）
openOnFocus	boolean	`false`	当输入框获得焦点时是否打开下拉列表
openOnClick	boolean	`false`	点击输入框时是否打开下拉列表
ignoreFilter	boolean	—	当值为 `true` 时，禁用默认过滤器
clearable	boolean	—	当 `multiple` 为 false 时，是否可以清除所选项目。
modelValue	(M extends true ? string[] : string)	—	所选项的受控值。当需要控制项的状态时使用此属性。可通过 `v-model` 进行绑定。
defaultValue	(M extends true ? string[] : string)	—	所选项的默认值。当需要设置项的初始状态时，请使用此选项。
multiple	M	—	用于确定一次可选择“单个”还是“多个”项目。此属性将覆盖根据 `modelValue` 和 `defaultValue` 推断出的类型。
disabled	boolean	—	当值为 `true` 时，禁止用户与列表框进行交互
dir	Direction	—	列表框的阅读方向（如适用）。<br> 若省略，则从全局 `ConfigProvider` 继承，或默认采用 LTR（从左到右）阅读模式。
name	string	—	字段的名称。作为名称/值对的一部分，与其所属表单一同提交。
highlightOnHover	boolean	—	当值为 `true` 时，将鼠标悬停在项目上会触发高亮显示
required	boolean	—	当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。

事件

事件名	参数	描述
update:modelValue	M extends true ? string[] : string	—
highlight	CollectionItemData<ListboxCollectionItemData> \| undefined	当选中元素发生变化时的事件处理程序。
update:open	boolean	在打开状态发生变化时触发。
escapeKeyDown	KeyboardEvent	当 Esc 键被按下时触发的事件处理程序。可被阻止。
pointerDownOutside	PointerDownOutsideEvent	当 `pointerdown` 事件发生在 `DismissableLayer` 外部时调用的事件处理程序。可被阻止。
focusOutside	FocusOutsideEvent	当焦点移出 `DismissableLayer` 时触发的事件处理程序。可被阻止。
interactOutside	PointerDownOutsideEvent \| FocusOutsideEvent	当在 `DismissableLayer` 外部发生交互时触发的事件处理程序。具体而言，当 `pointerdown` 事件在该区域外部发生，或焦点移出该区域时触发。此事件可被阻止。
openAutoFocus	Event	在打开页面时自动聚焦时触发的事件处理程序。可被阻止。
closeAutoFocus	Event	在关闭时自动聚焦时触发的事件处理程序。可被阻止。
placed	—	当定位器被放置时调用的事件处理程序
select	SelectEvent<string>	当选中某项时触发的事件处理程序。<br> 可以通过调用 `event.preventDefault` 来阻止该事件。

插槽

插槽名	参数	描述
trigger-leading	—	触发器首槽的自定义内容。
trigger-value	ComboboxCompactTriggerValueSlotProps<M>	触发值插槽的自定义内容。
trigger-trailing	—	触发器尾部插槽的自定义内容。
trigger-icon	—	触发图标槽位的自定义内容。
input-leading	ComboboxCompactInputSlotProps	输入首槽的自定义内容。
input-trailing	ComboboxCompactInputSlotProps	输入末尾槽位的自定义内容。
empty	—	为空槽位添加自定义内容。
group-label	ComboboxCompactGroupLabelSlotProps	组标签槽位的自定义内容。
item-leading	ComboboxCompactItemSlotProps	用于项目引导槽位的自定义内容。
item-text	ComboboxCompactItemSlotProps	针对“项文本”插槽的自定义内容。
item-trailing	ComboboxCompactItemSlotProps	用于项目尾部槽位的自定义内容。
item-indicator	ComboboxCompactItemSlotProps	项目指示符插槽的自定义内容。

ComboboxContent

27 属性7 事件

属性

属性名	类型	默认值	描述
position	'inline' \| 'popper'	—	职位。
bodyLock	boolean	—	是否启用正文锁定。
hideWhenEmpty	boolean	—	是否在为空时隐藏。
popupProps	PopperPositioningPopupProps	—	转发给弹出窗口元素的属性。
open	boolean	true	浮动层是否处于打开状态。该状态驱动定位生命周期（当打开状态切换时，`isPositioned` 会重置）；定位原语本身没有打开状态，因此调用方需在此处自行处理打开状态。
placement	Placement	undefined	浮动元素的位置。若使用该属性，它将覆盖 `side` 和 `align` 属性。
side	Side	'bottom'	打开时优先渲染的锚点侧。当发生冲突且启用了 avoidCollisions 时，该侧将反转。
sideOffset	number	0	距锚点的像素距离。
sideFlip	boolean	true	遇到边界时，请翻转至另一侧。
align	Align	'center'	首选与锚点对齐。发生冲突时可能会调整对齐方式。
alignOffset	number	0	相对于 `start` 或 `end` 对齐选项的像素偏移量。
alignFlip	boolean	true	当与边界发生冲突时，翻转对齐方式。此情况仅在 `prioritizePosition` 为 true 时才会发生。
avoidCollisions	boolean	true	当值为 `true` 时，将覆盖“侧边”和“对齐”首选项，以避免与边界边缘发生冲突。
collisionBoundary	Element \| (Element \| null)[] \| null	[ ]	用作碰撞边界的元素。默认情况下，该边界为视口，但您可以提供额外的元素以纳入此检查范围。
collisionPadding	Padding	0	从边界边缘开始，碰撞检测应发生的距离（以像素为单位）。接受一个数字（所有边均相同），或一个部分填充对象，例如：{ top: 20, left: 20 }。
arrowPadding	number	0	箭头与内容边缘之间的间距。如果您的内容使用了 border-radius，这将防止内容溢出到角落。
hideShiftedArrow	boolean	false	当值为 `true` 时，若无法将箭头居中对齐到引用元素上，则隐藏该箭头。
sticky	'partial' \| 'always'	'partial'	在对齐轴上的“粘附”行为。`partial` 会在锚点至少部分位于边界内时将内容保留在边界内，而 “always” 则无论如何都会将内容保留在边界内。
hideWhenDetached	boolean	false	当锚点被完全遮挡时，是否隐藏内容。
positionStrategy	'fixed' \| 'absolute'	'fixed'	要使用的 CSS `position` 属性的类型。
updatePositionStrategy	'always' \| 'optimized'	'optimized'	在每个动画帧中更新浮动元素位置的策略。
disableUpdateOnLayoutShift	boolean	false	当布局发生变化时，是否禁用内容的更新位置。
prioritizePosition	boolean	false	强制内容位于视口内。可能会与参考元素重叠，这可能并非预期效果。
reference	ReferenceElement	—	将作为浮动元素定位参考点的自定义元素或虚拟元素。如果提供了该元素，它将替换默认的锚点元素。
trapFocus	boolean	false	当设置为 `true` 时，焦点无法通过键盘、指针或程序化焦点离开该内容。
disableOutsidePointerEvents	boolean	—	当值为 `true` 时，`DismissableLayer` 外部元素的悬停/聚焦/点击交互将被禁用。用户需要双击外部元素才能与其交互：第一次用于关闭 `DismissableLayer`，第二次用于触发该元素。
forceMount	boolean	—	用于在需要更多控制时强制挂载。在使用 Vue 动画库控制动画时非常有用。

事件

事件名	参数	描述
escapeKeyDown	KeyboardEvent	当 Esc 键被按下时触发的事件处理程序。可被阻止。
pointerDownOutside	PointerDownOutsideEvent	当 `pointerdown` 事件发生在 `DismissableLayer` 外部时调用的事件处理程序。可被阻止。
focusOutside	FocusOutsideEvent	当焦点移出 `DismissableLayer` 时触发的事件处理程序。可被阻止。
interactOutside	PointerDownOutsideEvent \| FocusOutsideEvent	当在 `DismissableLayer` 外部发生交互时触发的事件处理程序。具体而言，当 `pointerdown` 事件在该区域外部发生，或焦点移出该区域时触发。此事件可被阻止。
openAutoFocus	Event	在打开页面时自动聚焦时触发的事件处理程序。可被阻止。
closeAutoFocus	Event	在关闭时自动聚焦时触发的事件处理程序。可被阻止。
placed	—	当定位器被放置时调用的事件处理程序

ComboboxEmpty

2 属性

属性

属性名	类型	默认值	描述
asChild	boolean	—	将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。
as	AsTag \| Component	'div'	该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。

ComboboxGroup

ComboboxGroupLabel

ComboboxInput

18 属性1 事件

属性

属性名	类型	默认值	描述
displayValue	((value: MaybeArray<string>) => string)	—	显示值。
inputRef	((el: HTMLInputElement) => void)	—	用于设置输入元素的函数。
controlProps	InputControlProps	—	输入的额外属性。
defaultValue	string	—	输入的默认值
modelValue	string	—	输入的受控值
disabled	boolean	—	当值为 `true` 时，禁止用户与输入内容进行交互。
readonly	boolean	—	当值为 `true` 时，输入内容为只读。
rootProps	BaseProps	—	转发至根元素的属性
name	string	—	字段的名称。作为名称/值对的一部分，与其所属表单一同提交。
required	boolean	—	当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。
id	string	—	输入元素的 ID
autofocus	boolean	—	当值为 `true` 时，系统会自动聚焦于输入内容。
autocomplete	'search' \| 'name' \| 'email' \| 'tel' \| 'url' \| 'on' \| 'off' \| 'username' \| 'current-password' \| 'new-password' \| 'one-time-code' \| 'given-name' \| 'family-name' \| 'organization' \| 'street-address' \| 'address-level2' \| 'postal-code' \| 'country' \| 'cc-name' \| 'cc-number' \| 'cc-exp' \| 'cc-csc' \| 'transaction-amount'	—	输入字段的 autocomplete 属性。除 `on` / `off` 开关外，还支持 HTML 自动填充标记（包括密码管理器的值，例如 `current-password` / `new-password`）。
maxlength	number	—	输入内容允许的最大字符数
minlength	number	—	输入内容允许的最小字符数
pattern	string	—	输入的 pattern 属性
placeholder	string	—	输入的占位符
type	InputTypeHTMLAttribute	—	输入元素的类型。

事件

事件名	参数	描述
update:modelValue	string	当模型值发生变化时触发。

ComboboxItem

5 属性1 事件

属性

属性名	类型	默认值	描述
textValue	string	—	文本值。
value	string	—	作为数据提交时与 `name` 关联的值。
disabled	boolean	—	当值为 `true` 时，禁止用户与该项进行交互。
asChild	boolean	—	将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。
as	AsTag \| Component	'div'	该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。

事件

事件名	参数	描述
select	SelectEvent<string>	当选中某项时触发的事件处理程序。<br> 可以通过调用 `event.preventDefault` 来阻止该事件。

ComboboxItemIndicator

2 属性

属性

属性名	类型	默认值	描述
asChild	boolean	—	将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。
as	AsTag \| Component	'div'	该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。

ComboboxPortal

ComboboxRoot<M>

16 属性3 事件

属性

属性名	类型	默认值	描述
open	boolean	—	下拉列表（Combobox）的受控打开状态。可通过 `v-model:open` 进行绑定。
defaultOpen	boolean	—	下拉列表框在初始渲染时的打开状态。<br> 当您无需控制其打开状态时使用。
resetSearchTermOnBlur	boolean	`true`	当下拉列表（Combobox）输入框失去焦点时，是否重置搜索词（searchTerm）
resetSearchTermOnSelect	boolean	`true`	当下拉列表（Combobox）的值被选中时，是否重置搜索词（searchTerm）
openOnFocus	boolean	`false`	当输入框获得焦点时是否打开下拉列表
openOnClick	boolean	`false`	点击输入框时是否打开下拉列表
ignoreFilter	boolean	—	当值为 `true` 时，禁用默认过滤器
clearable	boolean	—	当 `multiple` 为 false 时，是否可以清除所选项目。
modelValue	(M extends true ? string[] : string)	—	所选项的受控值。当需要控制项的状态时使用此属性。可通过 `v-model` 进行绑定。
defaultValue	(M extends true ? string[] : string)	—	所选项的默认值。当需要设置项的初始状态时，请使用此选项。
multiple	M	—	用于确定一次可选择“单个”还是“多个”项目。此属性将覆盖根据 `modelValue` 和 `defaultValue` 推断出的类型。
disabled	boolean	—	当值为 `true` 时，禁止用户与列表框进行交互
dir	Direction	—	列表框的阅读方向（如适用）。<br> 若省略，则从全局 `ConfigProvider` 继承，或默认采用 LTR（从左到右）阅读模式。
name	string	—	字段的名称。作为名称/值对的一部分，与其所属表单一同提交。
highlightOnHover	boolean	—	当值为 `true` 时，将鼠标悬停在项目上会触发高亮显示
required	boolean	—	当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。

事件

事件名	参数	描述
update:modelValue	M extends true ? string[] : string	—
highlight	CollectionItemData<ListboxCollectionItemData> \| undefined	当选中元素发生变化时的事件处理程序。
update:open	boolean	在打开状态发生变化时触发。

ComboboxSeparator

2 属性

属性

属性名	类型	默认值	描述
asChild	boolean	—	将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。
as	AsTag \| Component	'div'	该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。

ComboboxTrigger

3 属性

属性

属性名	类型	默认值	描述
disabled	boolean	—	该组件是否已禁用。
asChild	boolean	—	将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。
as	AsTag \| Component	'div'	该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。

ComboboxValue

5 属性

属性

属性名	类型	默认值	描述
items	ComboboxOptionData[]	—	用于解析所选标签的项目。
placeholder	string	—	当未选择任何值时，显示占位符。
separator	string	`', '`	用于连接多个选定标签的分隔符。
asChild	boolean	—	将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。
as	AsTag \| Component	'div'	该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。

ComboboxViewport

1 属性

属性

属性名	类型	默认值	描述
nonce	string	—	随机数。

ComboboxVirtualizer

4 属性

属性

属性名	类型	默认值	描述
options	string[]	—	项目列表
overscan	number	—	渲染在可见区域外的项目数量
estimateSize	number \| ((index: number) => number)	—	每个项目的估计大小（单位：px）
textContent	((option: string) => string)	—	每个条目的文本内容需支持联想输入功能

注意事项

架构与对标差异

VeanUI 通过复用 listbox 基座与 Popper 定位构建组合框：ComboboxRoot（选择状态 + useControllableState(open) + 三态过滤）→ ComboboxInput（role="combobox" + aria-autocomplete）→ ComboboxTrigger → ComboboxContentImpl（DismissableLayer + FocusScope + bodyLock）→ ComboboxItem → ListboxItem。scv() 配方 comboboxVariants 声明 16 个插槽与 7 个尺寸变体。这与 reka-ui / shadcn 的 combobox 语义一致，虚拟滚动与数据驱动 compact API 为 VeanUI 的差异化增强。

能力	VeanUI	reka-ui `Combobox`	shadcn `Combobox`	Ant Design `Select` (showSearch)
Aria/styled 分离	✅	✅	—	—
输入即过滤 + 三态 filter	✅	✅	✅	✅
combobox/listbox 角色	✅	✅	✅	✅
键盘导航 + typeahead	✅	✅	—	✅
虚拟滚动	✅	✅	—	✅
分组 + 组标签	✅	✅	✅	✅
取消按钮（clear）	✅	✅	✅	✅
空态	✅	✅	—	—
数据驱动 Compact API	✅	—	—	—
axe 零违规（打开态）	✅	—	✅	—

注意事项

输入过滤在客户端进行；远程/异步过滤需自行禁用内置过滤或对 inputValueChange 做防抖。
resetSearchTermOnBlur 控制失焦后是否保留搜索词——按你的交互预期设置（如 false 保留已输入内容）。
根节点 disabled 时所有条目都不可选——包括自带 disabled 的条目（统一 rootDisabled || item.disabled 守卫）。

常见问题

`SCombobox` 与 `SSelect` 有什么区别？

SCombobox 随输入过滤选项（role="combobox" + aria-autocomplete）；SSelect 由触发器驱动，仅支持 typeahead。需要输入搜索时选组合框。

大数据列表如何启用虚拟滚动？

在内容中加入 ComboboxVirtualizer（或对应 compact 开关），会激活内部虚拟列表，同时保留键盘导航。

如何取消选择或只清空搜索词？

传入 clearable。已选中值时，触发器会显示 ✕ 清除图标——点击后取消选择并发出空 modelValue（单选为 undefined，多选为 []）。浮窗内的取消按钮只清空搜索输入，不影响已选值。

为什么禁用条目仍可选中？

这曾是真实缺陷（Vue withDefaults 的 Boolean prop 隐式默认化问题），现已修复。禁用条目遵循统一 rootDisabled || item.disabled 守卫，与 SSelect 一致。

快速跳转

同分类组件

组合框

概述

用法

特性

演示

基础

分组

自定义样式

Value

API

Aria 层

Combobox<M>

属性

事件

插槽

ComboboxAnchor

属性

ComboboxArrow

ComboboxCancel

属性

ComboboxClear

属性

ComboboxCompact<M>

属性

事件

插槽

ComboboxContent

属性

事件

ComboboxEmpty

属性

ComboboxGroup

ComboboxGroupLabel

ComboboxInput

属性

事件

ComboboxItem

属性

事件

ComboboxItemIndicator

属性

ComboboxPortal

ComboboxRoot<M>

属性

事件

ComboboxSeparator

属性

ComboboxTrigger

属性

ComboboxValue

属性

ComboboxViewport

属性

ComboboxVirtualizer

属性

注意事项

架构与对标差异

注意事项

常见问题

SCombobox 与 SSelect 有什么区别？

大数据列表如何启用虚拟滚动？

如何取消选择或只清空搜索词？

为什么禁用条目仍可选中？

更新日志

v0.31.0

优化

重构

v0.16.0

优化

优化

v0.15.1

修复

v0.15.0

优化

重构

重构

优化

`SCombobox` 与 `SSelect` 有什么区别？