Autocomplete 自动补全输入框
根据输入内容提供对应的输入建议。
基础用法
通过 fetch-suggestions 属性设置获取建议列表的方法。
基础用法
自定义模板
使用 default 插槽自定义建议项的显示内容。
自定义模板
远程搜索
通过模拟延时从服务器获取建议数据。
远程搜索
禁用状态
使用 disabled 属性禁用输入框。
禁用状态
可清空
使用 clearable 属性可快速清空内容。
可清空
不同尺寸
支持 large、default 和 small 三种尺寸。
不同尺寸
自定义插槽
可以使用 loading 和 empty 插槽来自定义加载中和无数据时的内容。
自定义插槽
在 Nuxt 中使用
Autocomplete 组件在 Nuxt 3/4 环境下运行良好。由于支持自动导入，你只需直接编写组件名即可。
Nuxt 中使用
SSR 注意事项：
- ✅ 输入框的初始状态（包含
v-model值）在服务端正确渲染 - ✅ 尺寸（size）、占位符（placeholder）支持 SSR
- ✅ 前后缀插槽在 SSR 阶段即已生成 HTML
- ⚠️ 候选建议列表（Dropdown）仅在客户端交互（输入或聚焦）时弹出，不影响首屏 HTML 结构
- 💡 搜索防抖和下拉定位在客户端激活（Hydration）后生效
SSR 安全性
Autocomplete 组件内部封装了 YhInput 和 Popper 系统，通过 useId 确保了首屏渲染时 Input 与下拉关联 ID 的稳定性，完美避免了 SSR 下常见的 ID 冲突警报。
API
Props
| 属性名 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| model-value / v-model | 绑定值 | string | — |
| placeholder | 占位文本 | string | — |
| disabled | 是否禁用 | boolean | false |
| clearable | 是否可清空 | boolean | false |
| size | 输入框尺寸 | 'large' | 'default' | 'small' | 'default' |
| fetch-suggestions | 获取建议的方法 | (query: string, callback: (suggestions: any[]) => void) => void | — |
| trigger-on-focus | 是否在聚焦时触发建议 | boolean | true |
| debounce | 防抖延迟 (ms) | number | 300 |
| placement | 下拉框位置 | 'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'bottom-start' |
| value-key | 建议对象中用于显示的键名 | string | 'value' |
| highlight-first-item | 是否默认高亮第一项 | boolean | false |
| teleported | 是否将下拉框插入到 body | boolean | true |
| fit-input-width | 下拉框宽度是否与输入框一致 | boolean | true |
| prefix-icon | 前置图标 | string | Component | — |
| suffix-icon | 后置图标 | string | Component | — |
| name | 原生 name 属性 | string | — |
| autofocus | 自动聚焦 | boolean | false |
| autocomplete | 原生 autocomplete 属性 | string | 'off' |
Events
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| input | 输入值变化时触发 | (value: string) => void |
| change | 值改变时触发 | (value: string) => void |
| focus | 获取焦点时触发 | (event: FocusEvent) => void |
| blur | 失去焦点时触发 | (event: FocusEvent) => void |
| clear | 点击清空按钮时触发 | () => void |
| select | 选中建议项时触发 | (item: any) => void |
Slots
| 插槽名 | 说明 | 作用域 |
|---|---|---|
| default | 自定义建议项内容 | { item: any } |
| prefix | 输入框前缀内容 | — |
| suffix | 输入框后缀内容 | — |
| prepend | 输入框前置内容 | — |
| append | 输入框后置内容 | — |
| loading | 正在加载中的内容 | — |
| empty | 无匹配数据时的内容 | — |
Expose
| 属性名 | 说明 | 类型 |
|---|---|---|
| focus | 使 input 获取焦点 | () => void |
| blur | 使 input 失去焦点 | () => void |
| close | 关闭建议列表 | () => void |
| highlight | 高亮指定项 | (index: number) => void |
主题变量
Autocomplete 组件使用以下 CSS 变量，你可以通过覆盖这些变量来自定义样式：
| 变量名 | 说明 | 默认值 |
|---|---|---|
--yh-autocomplete-border-color | 边框颜色 | var(--yh-border-color) |
--yh-autocomplete-hover-border-color | 悬停边框色 | var(--yh-border-color-hover) |
--yh-autocomplete-focus-border-color | 聚焦边框色 | var(--yh-color-primary) |
--yh-autocomplete-disabled-bg-color | 禁用背景色 | var(--yh-fill-color-light) |