Typeahead Props

名称	类型	默认值	说明
modelValue	T | null	null	当前选中的条目。条目至少包含 id 和 label。
searchSource	SearchSource<T>	必需	静态或异步搜索源。空查询优先调用 bootstrap。
label	string	必需	字段标签。屏幕阅读器始终读得到。
description	string	—	标签下方的说明。
labelTooltip	string	—	标签旁边信息图标里的提示文字。
isLabelHidden	boolean	false	视觉上隐藏标签，读屏仍然读得到。旧名 labelHidden 同样可用，两者任一为真就隐藏。
containerClass / controlClass	class	—	外壳和输入外框。根上的 class 落在外框，不落到原生 input。候选项的 action 把菜单变成两列，点操作不会选中这一项。
startIcon	Component	—	输入框起始侧的图标。已有 icon 插槽时以插槽为准。
placeholder	string	Search… / 搜索…	占位符。未设置语言时为英文。
debounceMs	number	150	输入停顿后再搜索。本地数据可设为 0。
minQueryLength	number	1	够长才去搜索的下限，按人眼看到的字符数算。太短就完全不搜，下拉也不打开，免得为一个没搜过的查询显示「没有结果」。空查询不算太短，照旧走 bootstrap。
hasEntriesOnFocus	boolean	false	聚焦后还没输入就展示 bootstrap 结果。
showOnFocus	boolean	false	hasEntriesOnFocus 的旧名。两者任一为真即生效。
hasAutoFocus	boolean	false	挂载后自动聚焦输入框。
maxMenuItems	number	10	下拉最多显示多少条。
hasClear	boolean	true	是否显示清除按钮，用来取消当前选中值。
clearable	boolean	true	hasClear 的旧名。任一为假就不显示按钮。
emptySearchText	string | null	'No results found' / '未找到结果'	没有匹配结果时显示的文字。null 当作没给，退回默认；空字符串表示什么都不显示。要放链接这类富内容用 empty 插槽。
emptyText	string | null	—	emptySearchText 的旧名。
disabled	boolean	false	是否禁用。
disabledMessage	string	—	说明为什么被禁用。和 disabled 一起用时，控件改用 aria-disabled 加 readonly，因此仍然可聚焦，鼠标悬停或键盘聚焦都能读到这段说明。
disabledReason	string	—	disabledMessage 的旧名。
status	'default' | 'success' | 'warning' | 'error'	'default'	状态样式。
statusMessage	string	—	字段下方的状态说明。
size	'sm' | 'md' | 'lg'	'md'	输入框和标签的尺寸。
required	boolean	false	标记为必填。
optional	boolean	false	标签上显示「可选」标记。
name	string	—	表单字段名。提交选中条目的 id。
width	number | string	—	整个字段的宽度（数字按像素算，字符串原样使用）。

Typeahead Emits

名称	载荷	说明
update:modelValue	value: T | null	选中或清除时触发。
change	value: T | null	选中或清除时触发。
changeQuery	query: string	查询文字变化时触发。
search	query: string	changeQuery 的旧名。两个都会触发。
openChange	isOpen: boolean	列表打开或关闭时触发。

Typeahead Slots

名称	参数	说明
icon	—	输入框开头的图标。
item	{ item, isActive, isSelected }	自定义下拉条目，替换默认的 TypeaheadItem。
empty	—	自定义空状态。

createStaticSource

名称	类型	说明
items	T[]	本地条目。
keywords	(item: T) => string[]	除 label 之外还参与子串匹配的词。

结果分组

把分组名放在 item.auxiliaryData.group 上。同名的条目会渲染成一个 role="group" 区块，前面带可见的标题，顺序按分组第一次出现的先后。没有分组名的条目留在原位。

const items = [
  { id: 'apple', label: 'Apple', auxiliaryData: { group: 'Fruit' } },
  { id: 'carrot', label: 'Carrot', auxiliaryData: { group: 'Vegetable' } },
]

BaseTypeahead

没有字段标签、说明和校验文案。适合命令面板这类外面已经有标题的地方。label 在这里是输入框的无障碍名，外面已经有 <label for> 时不用传。默认下拉行是 TypeaheadItem，可以用 item 插槽换掉。

名称	类型	默认值	说明
modelValue	T | null	null	当前选中的条目。
searchSource	SearchSource<T>	必需	静态或异步搜索源。
label	string	—	输入框的无障碍名。
inputId	string	自动生成	输入框的 id，好让外面的标签用 for 对上。
describedBy	string	—	外面已经算好的说明和状态 id。
ariaDescribedBy	string	—	输入框专用的 aria-describedby 别名，给了就盖过原生属性。
ariaLabelledBy	string	—	输入框专用的 aria-labelledby 别名，给了就盖过原生属性。
anchorRef	HTMLElement | null	—	下拉挂靠并据此量宽度的元素。不传就用输入框所在的外框。
inputTabIndex	number	—	输入框在 Tab 序里的位置。选中值的标签盖住输入框时默认取 -1，免得留下看不见的停留点。
isFocusableDisabled	boolean	false	让禁用的输入框改用 aria-disabled 加 readonly，仍然可聚焦，好让调用方给的禁用说明读得到。输入内容照样被挡住。
hasAutoFocus	boolean	false	挂载后自动聚焦输入框。
hasEntriesOnFocus	boolean	false	聚焦后还没输入就展示 bootstrap 结果。
showOnFocus	boolean	false	hasEntriesOnFocus 的旧名。两者任一为真即生效。
minQueryLength	number	1	够长才去搜索的下限，按人眼看到的字符数算。太短就完全不搜，下拉也不打开。
menuWidth	number	—	下拉想要的宽度，单位像素。窄不过锚点，再宽会被视口截住。
maxMenuItems	number	10	下拉最多显示多少条。
emptySearchText	string | null	'No results found' / '未找到结果'	没有匹配结果时显示的文字。null 退回默认，空字符串什么都不显示。
emptyText	string | null	—	emptySearchText 的旧名。
placeholder	string	Search…	输入框占位符。
disabled	boolean	false	是否禁用。
disabledReason	string	—	禁用原因。鼠标悬停会显示提示，同时作为说明被读出来，输入框仍可聚焦。
status	'default' | 'success' | 'warning' | 'error'	'default'	外框的校验色。
size	'sm' | 'md' | 'lg'	'md'	输入框和标签的尺寸。
clearable	boolean	true	是否显示清除按钮。
debounceMs	number	150	输入停顿后再搜索。本地数据可设为 0。
required	boolean	false	标记为必填。
name	string	—	表单字段名。提交选中条目的 id。

名称	载荷	说明
update:modelValue	value: T | null	选中或清除时触发。
change	value: T | null	选中或清除时触发。
changeQuery	query: string	查询文字变化时触发。
search	query: string	changeQuery 的旧名。两个都会触发。
openChange	isOpen: boolean	列表打开或关闭时触发。

上面没列出的原生属性和事件监听会落到输入框上，所以 @keydown、@focus、@blur 和 aria-* 的用法跟普通 <input> 一样。keydown 监听先于内部键盘导航执行，调用 event.preventDefault() 就能跳过内部处理。

TypeaheadItem

名称	类型	默认值	说明
item	SearchableItem	必需	这一行对应的搜索结果。
description	string	—	盖过条目自己的说明。
group	string	—	为了和同名属性对得上而接受；这一行自己不会画标题。分组由下拉按 item.auxiliaryData.group 完成。
isDisabled	boolean	false	这一行看起来不可选。
icon（插槽）	—	—	标签前面的图标或头像。