Autocomplete 自动补全输入框

YhAutocomplete 会根据当前输入值提供候选建议，适用于搜索框、地址补全、快捷命令检索等场景。

基础用法

通过 fetch-suggestions 提供候选列表获取逻辑。

基础用法

自定义建议项模板

默认插槽可自定义每一条候选项的展示内容。

自定义建议项模板

远程搜索

可以在 fetch-suggestions 中发起异步请求，并在回调执行后刷新下拉建议列表。

远程搜索

禁用状态

设置 disabled 后，输入框与候选面板都不会响应交互。

禁用状态

可清空

开启 clearable 后，在输入框存在值且悬停或聚焦时会出现清空按钮。

可清空

不同尺寸

支持 large、默认和 small 三种尺寸。

不同尺寸

加载态与空态插槽

通过 loading 和 empty 插槽可自定义下拉面板的非数据态展示。

加载态与空态插槽

在 Nuxt 中使用

接入 @yh-ui/nuxt 后，可直接在页面中使用 YhAutocomplete。输入框本体可以参与 SSR 渲染，下拉候选面板会在客户端交互时再挂载；如果开启 teleported，下拉层会被插入到 body。

在 Nuxt 中使用

API

Props

名称	说明	类型	默认值
model-value / v-model	当前输入值	string	undefined
placeholder	占位文案	string	undefined
disabled	是否禁用	boolean	false
clearable	是否允许清空	boolean	false
size	输入框尺寸	'large' | 'default' | 'small'	undefined
fetch-suggestions	候选建议获取函数	(query: string, callback: (suggestions: AutocompleteSuggestion[]) => void) => void	undefined
trigger-on-focus	聚焦时是否立即触发建议获取	boolean	true
debounce	建议请求防抖时长，单位毫秒	number	300
placement	下拉面板位置	'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end'	'bottom-start'
value-key	建议对象中作为显示值的字段名	string	'value'
popper-class	下拉面板自定义类名	string	undefined
teleported	是否将下拉面板挂载到 body	boolean	true
fit-input-width	下拉面板宽度是否跟随输入框	boolean	true
highlight-first-item	是否默认高亮第一项	boolean	false
prefix-icon	前缀图标组件或图标名	string | Component	undefined
suffix-icon	后缀图标组件或图标名	string | Component	undefined
validate-event	是否触发表单校验	boolean	true
autofocus	是否自动聚焦	boolean	false
name	原生 name 属性	string	undefined
autocomplete	原生 autocomplete 属性	string	'off'
theme-overrides	组件级主题覆盖	ComponentThemeVars	undefined

Events

名称	说明	参数
update:modelValue	输入值变化时触发	(value: string) => void
input	输入过程中触发	(value: string) => void
change	输入值提交变化时触发	(value: string) => void
focus	输入框获取焦点时触发	(event: FocusEvent) => void
blur	输入框失去焦点时触发	(event: FocusEvent) => void
clear	点击清空按钮时触发	() => void
select	选中候选项时触发	(item: AutocompleteSuggestion) => void

Slots

名称	说明	参数
default	自定义候选项内容	{ item: AutocompleteSuggestion }
prefix	输入框前缀内容	-
suffix	输入框后缀内容	-
prepend	输入框包裹层前置内容	-
append	输入框包裹层后置内容	-
loading	自定义加载态内容	-
empty	自定义空态内容	-

Expose

名称	说明	类型
focus	让输入框获取焦点	() => void
blur	让输入框失去焦点	() => void
close	关闭候选面板	() => void
highlight	高亮指定索引的候选项	(index: number) => void
inputRef	原生输入框引用	HTMLInputElement | undefined

类型导出

名称	说明
YhAutocompleteSize	尺寸联合类型
YhAutocompletePlacement	下拉位置联合类型
YhAutocompleteSuggestion	候选项数据类型
YhAutocompleteProps	YhAutocomplete 的 props 类型
YhAutocompleteEmits	YhAutocomplete 的 emits 类型
YhAutocompleteSlots	YhAutocomplete 的 slots 类型
YhAutocompleteExpose	组件暴露实例类型
YhAutocompleteInstance	组件实例类型

主题变量

YhAutocomplete 当前没有额外暴露组件级专属 CSS 变量，主要消费全局输入框、边框、填充和文本相关令牌；如需统一调整，可结合 themeOverrides 与全局主题变量一起使用。