组合框 Combobox

Root · ClearTrigger · Content · Control · Input · Item · ItemGroup · ItemGroupLabel · ItemIndicator · ItemText · Label · List · Positioner · Trigger

#ClearTrigger

纯造型的部件——自身没有属性，沿用部件结构的共享样式。

#Content

纯造型的部件——自身没有属性，沿用部件结构的共享样式。

#Control

纯造型的部件——自身没有属性，沿用部件结构的共享样式。

#Empty

纯造型的部件——自身没有属性，沿用部件结构的共享样式。

#Input

纯造型的部件——自身没有属性，沿用部件结构的共享样式。

#ItemContext

纯造型的部件——自身没有属性，沿用部件结构的共享样式。

#ItemGroupLabel

纯造型的部件——自身没有属性，沿用部件结构的共享样式。

#ItemGroup

纯造型的部件——自身没有属性，沿用部件结构的共享样式。

#ItemIndicator

纯造型的部件——自身没有属性，沿用部件结构的共享样式。

#ItemText

纯造型的部件——自身没有属性，沿用部件结构的共享样式。

#Item

属性	类型	默认值	描述
`item`	`CollectionItem`		要渲染的条目
`persistFocus`	`boolean \| undefined`		悬停移出后是否清除高亮

#Label

纯造型的部件——自身没有属性，沿用部件结构的共享样式。

#List

纯造型的部件——自身没有属性，沿用部件结构的共享样式。

#Positioner

纯造型的部件——自身没有属性，沿用部件结构的共享样式。

#Root

属性	类型	默认值	描述
`size`	`String as PropType<"sm" \| "md" \| "lg">`	`"md"`	字段行高度，可为 `sm`、`md` 或 `lg`
`allowCustomValue`	`boolean`		是否允许在输入框中输入自定义值
`alwaysSubmitOnEnter`	`boolean`		是否跳过默认两步行为（先按 Enter 关闭组合框，再按 Enter 提交表单），让 Enter 直接提交表单；适合单字段自动补全表单
`autoFocus`	`boolean`		挂载时是否自动聚焦输入框
`closeOnSelect`	`boolean`		选中条目后是否关闭组合框
`collection`	`ListCollection<T>`		条目集合
`composite`	`boolean`	`true`	组合框是否与标签页等复合组件组合使用
`defaultHighlightedValue`	`string`		组合框初始高亮值；无需控制高亮值时使用
`defaultInputValue`	`string`	`""`	组合框输入框初始值；无需控制输入值时使用
`defaultOpen`	`boolean`		组合框初始是否展开；无需控制展开状态时使用
`defaultValue`	`string[]`	`[]`	组合框已选项初始值；无需控制已选值时使用
`disabled`	`boolean`		组合框是否禁用
`disableLayer`	`boolean`		是否禁止把该组件注册为可关闭层
`form`	`string`		组合框关联的表单
`highlightedValue`	`string`		组合框的受控高亮值
`id`	`string`		组件内部状态机的唯一标识
`ids`	`Partial<{ root: string; label: string; control: string; input: string; content: string; trigger: string; clearTrigger: string; item(id: string, index?: number): string; positioner: string; itemGroup(id: string \| number): string; itemGroupLabel(id: string \| number): string; }>`		组合框内各元素的 id；便于组合使用
`inputBehavior`	`'autohighlight' \| 'autocomplete' \| 'none'`	`"none"`	组合框的自动补全行为：`autohighlight` 表示输入时高亮第一个获得焦点的条目；`autocomplete` 表示用方向键在列表框中导航时选中条目并更新输入框
`inputValue`	`string`		组合框输入框的受控值
`invalid`	`boolean`		组合框是否无效
`loopFocus`	`boolean`	`true`	键盘导航是否在条目间循环
`modelValue`	`string[]`		组合框的 v-model 值
`multiple`	`boolean`		是否允许多选；`multiple` 为 `true` 时，`selectionBehavior` 会自动设为 `clear`，建议把已选项放在单独容器中渲染
`name`	`string`		组合框输入框的 `name` 属性，用于表单提交
`navigate`	`(details: combobox.NavigateDetails) => void`		用于导航到已选项的函数
`open`	`boolean`		组合框的受控展开状态
`openOnChange`	`boolean \| ((details: combobox.InputValueChangeDetails) => boolean)`	`true`	输入值变化时是否显示组合框弹层
`openOnClick`	`boolean`	`false`	首次点击输入框时是否打开组合框弹层
`openOnKeyPress`	`boolean`	`true`	按下方向键时是否打开组合框弹层
`placeholder`	`string`		组合框输入框的占位文本
`positioning`	`combobox.PositioningOptions`	`{ placement: "bottom-start" }`	组合框弹层的动态定位选项
`readOnly`	`boolean`		组合框是否只读；只读时输入框不可编辑，但仍可交互
`required`	`boolean`		组合框是否必填
`scrollToIndexFn`	`(details: combobox.ScrollToIndexDetails) => void`		滚动到指定索引的函数
`selectionBehavior`	`'clear' \| 'replace' \| 'preserve'`	`"replace"`	选中条目后输入框的处理方式：`replace` 表示把选中项文本设为输入值；`clear` 表示清空输入值；`preserve` 表示保留输入值
`translations`	`combobox.IntlTranslations`		无障碍元素及其状态的本地化文案

事件	载荷
`select`	`details: { value: string[]; itemValue: string; }`
`exitComplete`	`—`
`valueChange`	`details: ValueChangeDetails<T>`
`update:modelValue`	`value: string[]`
`openChange`	`details: OpenChangeDetails`
`update:open`	`value: boolean`
`focusOutside`	`event: FocusOutsideEvent`
`interactOutside`	`event: InteractOutsideEvent`
`pointerDownOutside`	`event: PointerDownOutsideEvent`
`highlightChange`	`details: HighlightChangeDetails<T>`
`inputValueChange`	`details: InputValueChangeDetails`
`update:highlightedValue`	`value: string \| null`
`update:inputValue`	`value: string`

#Trigger

属性	类型	默认值	描述
`focusable`	`boolean \| undefined`		触发器是否可聚焦