Combobox
Combobox 将自由文本输入与选项选择结合起来，适用于可搜索的单选和多选流程。
Combobox 与 Select 共用尺寸和菜单颜色偏好。尺寸说明见 Select 尺寸与工具栏对齐，颜色说明见 Select 菜单外观。其 labelClearance 属性继承自 fieldContextKey。请保持周围布局预期的紧凑程度，仅在浮动标签需要额外空间时增加间距。详见字段布局指南。
属性
| 名称 | 说明 | 默认值 | 控件 |
|---|---|---|---|
shape可选 | Corner style; inherits the shared shape default. M3Shape | undefined | - | - |
size可选 | The trigger height. Matches the 32px, 40px, and 56px TextField and Button sizes. TextFieldSize | undefined | - | - |
disabled可选 | Whether the control is disabled. boolean | undefined | - | |
name可选 | Name used for hidden inputs during form submission. string | undefined | - | |
multiple可选 | Enables multi-select behavior. boolean | undefined | - | - |
label可选 | Floating label, or accessible-name fallback in external mode. Otherwise supply an external label or ARIA name. string | undefined | - | |
labelBehavior可选 | Floating label or externally arranged visible label; label remains an accessible-name fallback. FieldLabelBehavior | undefined | - | - |
id可选 | Optional explicit id for the trigger element. string | undefined | - | |
options必填 | Selectable options rendered in the menu. SelectOption[] | - | - |
filterMode可选 | Consumer-owned search results bypass local filtering. localexternal | - | |
resolveLabel可选 | Resolve selected values absent from current results; reactive caches are supported. ((value: SelectOptionValue) => string | undefined) | undefined | - | |
supportingText可选 | Supporting text shown below the field when not in error state. string | undefined | - | |
error可选 | Error text shown below the field. When provided, field is invalid. string | undefined | - | |
required可选 | Whether the control is required. boolean | undefined | - | |
placeholder可选 | Placeholder shown when nothing is selected. string | undefined | - | |
labelClearance可选 | CSS length reserved at block-start for the floating label. Overrides FieldContext. string | undefined | - | |
showSelectedIcon可选 | Show selected checkmarks; inherits Select defaults, then falls back to true. boolean | undefined | undefined | |
clearable可选 | Shows a trailing button that clears the current selection. boolean | undefined | - | |
clearLabel可选 | Accessible label for the clear button. string | undefined | - | |
menuColor可选 | Visual color style of the dropdown menu. MenuColor | undefined | - | - |
displaySeparator可选 | Separator used when showing multiple selected labels. string | undefined | - | |
filterPlaceholder可选 | Placeholder shown in the field while filtering. string | undefined | - | |
filterNoResultsText可选 | Message shown when filtering returns no matching options. string | undefined | - | |
modelValue可选 | - SelectModelValue | - | - |
query可选 | - string | undefined | "" | |
open可选 | - boolean | undefined | false |
事件7
| 名称 | 类型 | 说明 |
|---|---|---|
update:open | [value: boolean] | - |
closed | [] | - |
update:modelValue | [value: SelectModelValue] | - |
update:query | [value: string] | - |
change | [value: SelectModelValue] | - |
focus | [event: FocusEvent] | - |
blur | [event: FocusEvent] | - |
插槽7
| 名称 | 参数 | 说明 |
|---|---|---|
list | - | - |
leading | - | - |
prefix | - | - |
suffix | - | - |
trailing | - | - |
optionLeading | - | - |
optionTrailing | - | - |
下拉菜单完成退出后，Combobox 会转发 Select 的 closed 事件。若要释放选项插槽使用的数据，请使用此事件，而不是 update:open(false)。
INFO
Combobox 封装了 Select，并共享其 select scope。详见 Select Anatomy。
showSelectedIcon 和 selectDefaults 与 Select 共享；详见选中标记。
标签遵循共享的 fieldLabelBehavior 默认值（floating；compact 中为 external）。可用 label-behavior 覆盖。External 模式不显示内置标签和描边缺口，不应用 labelClearance，且仅将 label 用作无障碍名称的回退值。自定义标签布局请参阅字段布局。
虚拟列表与外部搜索
Combobox 会将 list、v-model:query、filterMode 和 resolveLabel 转发给 Select。虚拟行使用相同的 SelectItem；筛选和导航针对完整逻辑结果集进行，焦点仍保留在输入框中。详见外部虚拟列表和搜索结果与选中标签。
示例
默认
多选
组合式函数
Combobox 与 Select 共用同一个组合式函数。
useSelect
完整类型签名
function useSelect(opts: UseSelectOptions): { filterQuery: import("vue").Ref<string, string>; selectedOptions: import("vue").ComputedRef<UseSelectOption[]>; hasValue: import("vue").ComputedRef<boolean>; displayText: import("vue").ComputedRef<string>; submittedValues: import("vue").ComputedRef<string[]>; filteredOptionEntries: import("vue").ComputedRef<import("./selectModel").SelectOptionEntry[]>; hasFilteredOptions: import("vue").ComputedRef<boolean>; activeIndex: import("vue").ComputedRef<number>; activeDescendant: import("vue").ComputedRef<string | undefined>; list: import("vue").ComputedRef<{ entries: import("./selectModel").SelectOptionEntry[]; scrollElement: HTMLElement | undefined; activeIndex: number; open: boolean; setScrollToIndex: (callback: ((index: number) => void) | undefined) => void; }>; optionProps: (index: number, option: UseSelectOption) => { id: string; 'aria-posinset': number; 'aria-setsize': number; 'data-active': string | undefined; 'data-keyboard-active': string | undefined; 'data-first': string | undefined; 'data-last': string | undefined; ref: (instance: Element | ComponentPublicInstance | null) => void; onMousedown: (event: MouseEvent) => void; onPointermove: () => void; onClick: () => void; }; isOptionSelected: (option: UseSelectOption) => boolean; toggleOption: (option: UseSelectOption) => void; clearValue: () => void; focus: () => void; blur: () => void; show: () => Promise<void>; hide: () => void; toggle: () => void; openMenu: (target?: "first" | "last") => void; closeMenu: () => void; handleFieldClick: () => void; handleFieldInput: () => void; handleFilterKeydown: (event: KeyboardEvent) => void; handleMenuClosed: () => void; }来源：src/composables/useSelect.ts
| 字段 | 类型 | 必填 | 说明 | 默认值 |
|---|---|---|---|---|
options | () => UseSelectOption[] | 是 | Unique, stable values identify the complete logical result set. | - |
multiple | () => boolean | 是 | - | - |
filterable | () => boolean | 是 | - | - |
disabled | () => boolean | 是 | - | - |
displaySeparator | () => string | 是 | - | - |
locale | (() => string | undefined) | undefined | 否 | - | - |
filterMode | (() => "local" | "external") | undefined | 否 | Disable local filtering when the consumer supplies search results. | - |
resolveLabel | ((value: UseSelectOptionValue) => string | undefined) | undefined | 否 | Resolve values missing from current results. Falls back to String(value). | - |
query | Ref<string, string> | undefined | 否 | - | - |
modelValue | Ref<UseSelectModelValue, UseSelectModelValue> | 是 | - | - |
open | Ref<boolean, boolean> | 是 | - | - |
onChange | ((value: UseSelectModelValue) => void) | undefined | 否 | - | - |
onClosed | (() => void) | undefined | 否 | - | - |
id | () => string | 是 | Stable listbox id, normally derived from useId(). | - |
focus | () => void | 是 | - | - |
blur | () => void | 是 | - | - |
showMenu | () => void | 是 | Use the shared Menu overlay, including source anchoring and close completion. | - |
hideMenu | () => void | 是 | - | - |
scrollElement | () => HTMLElement | undefined | 是 | The MenuContainer is the single scroll owner. | - |
| 字段 | 类型 | 必填 | 说明 | 默认值 |
|---|---|---|---|---|
filterQuery | import("vue").Ref<string, string> | 是 | - | - |
selectedOptions | import("vue").ComputedRef<UseSelectOption[]> | 是 | - | - |
hasValue | import("vue").ComputedRef<boolean> | 是 | - | - |
displayText | import("vue").ComputedRef<string> | 是 | - | - |
submittedValues | import("vue").ComputedRef<string[]> | 是 | - | - |
filteredOptionEntries | import("vue").ComputedRef<import("./selectModel").SelectOptionEntry[]> | 是 | - | - |
hasFilteredOptions | import("vue").ComputedRef<boolean> | 是 | - | - |
activeIndex | import("vue").ComputedRef<number> | 是 | - | - |
activeDescendant | import("vue").ComputedRef<string | undefined> | 是 | - | - |
list | import("vue").ComputedRef<{ entries: import("./selectModel").SelectOptionEntry[]; scrollElement: HTMLElement | undefined; activeIndex: number; open: boolean; setScrollToIndex: (callback: ((index: number) => void) | undefined) => void; }> | 是 | - | - |
optionProps | (index: number, option: UseSelectOption) => { id: string; 'aria-posinset': number; 'aria-setsize': number; 'data-active': string | undefined; 'data-keyboard-active': string | undefined; 'data-first': string | undefined; 'data-last': string | undefined; ref: (instance: Element | ComponentPublicInstance | null) => void; onMousedown: (event: MouseEvent) => void; onPointermove: () => void; onClick: () => void; } | 是 | - | - |
isOptionSelected | (option: UseSelectOption) => boolean | 是 | - | - |
toggleOption | (option: UseSelectOption) => void | 是 | - | - |
clearValue | () => void | 是 | - | - |
focus | () => void | 是 | - | - |
blur | () => void | 是 | - | - |
show | () => Promise<void> | 是 | - | - |
hide | () => void | 是 | - | - |
toggle | () => void | 是 | - | - |
openMenu | (target?: "first" | "last") => void | 是 | - | - |
closeMenu | () => void | 是 | - | - |
handleFieldClick | () => void | 是 | - | - |
handleFieldInput | () => void | 是 | - | - |
handleFilterKeydown | (event: KeyboardEvent) => void | 是 | - | - |
handleMenuClosed | () => void | 是 | - | - |