Combobox 组合框Combobox · Autocomplete

选项很多、用户大概知道自己要什么时，让他们边打字边筛选：国家、成员、仓库。Combobox 的值必须是选项之一；Autocomplete 允许任意输入，选项只是建议。选项不多时直接用 Select。

基本用法

点击或打字都会展开列表；刚展开、还没改过文字时显示全部选项。没选就离开，文字会回到当前选中项。

分组、图标与清除

选项的写法和 Select 相同（分组、禁用、图标、meta）。clearable 在有内容时显示清除按钮；icon 是输入框前面的图标。

尺寸与状态

受控用法

有两份状态：value 是选中项的值，inputValue 是输入框里的文字。把文字清空会把 value 置为 null。

value：jp · 输入框文字：“日本”

异步加载

选项来自接口时：监听 onInputChange 去请求，把 filter 设为 false（不在本地再筛一遍），请求期间传 loading。emptyText 传 null 可以在没有内容时干脆不弹出。

已选仓库：无

Autocomplete 自动补全

可以任意输入，选项只是建议：值就是输入框里的文字。适合邮箱后缀、标签、搜索历史这类“多半是这些，但也可能是别的”的输入。

邮箱后缀

可以选一个常用的，也可以自己输入

API

Combobox

属性	类型	默认值	说明
`options`*	`Array<SelectOption \| { label: string; options: SelectOption[] }>`	—	选项；可以混入分组。SelectOption 的字段见 Select。
`value`	`string \| null`	—	选中项的 value（受控）；null 表示没选。Autocomplete 时就是输入框里的文字。
`defaultValue`	`string \| null`	`null`	初始选中项（非受控）。
`onChange`	`(value: string \| null, option?: SelectOption) => void`	—	选中项变化时触发；清空时为 null。
`inputValue`	`string`	—	输入框里的文字（受控）。
`defaultInputValue`	`string`	—	输入框的初始文字，默认取选中项的文字。
`onInputChange`	`(text: string) => void`	—	文字变化时触发（打字、选中、清除）。
`filter`	`((option, query) => boolean) \| false`	`按文字包含（不分大小写）`	自定义筛选；false 表示不在本地筛选。
`loading`	`boolean`	`false`	正在加载选项：列表上方显示加载文字，输入框带 aria-busy。
`loadingText`	`ReactNode`	`'加载中…'`	加载时显示的内容。
`emptyText`	`ReactNode`	`'没有匹配的选项'`	没有匹配项时显示的内容；传 null 则不弹出。
`freeSolo`	`boolean`	`false`	允许任意输入。Autocomplete 就是固定开启它的 Combobox。
`clearable`	`boolean`	`false`	有内容时显示清除按钮。
`icon`	`IconName \| ReactNode`	—	输入框前面的图标。
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	尺寸。
`invalid / disabled / required`	`boolean`	—	校验未通过 / 禁用 / 必填。放在 Field 里时没传就取 Field 的。
`name / form`	`string`	—	配合表单提交：Combobox 提交选中项的 value，Autocomplete 提交输入的文字。
`open / defaultOpen / onOpenChange`	`boolean / boolean / (open) => void`	—	列表的展开状态。
`placement`	`Placement`	`'bottom-start'`	列表相对输入框的位置。
`ref`	`Ref<HTMLInputElement>`	—	指向里面的原生 <input>（和 Input、SearchInput 一致），可以直接 focus() / select()。
`rootRef`	`Ref<HTMLDivElement>`	—	外框（.ok-input）的 ref，需要量尺寸或以它为锚点时用。
`rootClassName / rootStyle`	`string / CSSProperties`	—	外框的类名与样式；className / style 也落在外框上。
`…rest`	`InputHTMLAttributes`	—	其余原生属性（id、placeholder、aria-*）落在 <input> 上。