自动完成

概述

用于根据输入内容筛选建议项并快速填充文本的自动完成组件。输入即打开，基于 Fuse 模糊搜索匹配选项，支持分组、可清空输入与数据驱动的 compact API。适用于让用户输入关键词获得自由文本建议的场景；选项来自固定列表时优先用 SSelect；选项来自已知集合且需要输入过滤时，SCombobox 是更接近的同类组件。

用法

特性

🔍 输入即打开，基于 Fuse 模糊搜索（threshold: 0.3，匹配 label / value / keywords / groupLabel）
⌨️ 完整键盘导航——ArrowDown/Up/Home/End 打开与移动、Enter/Space 选择、typeahead、Escape 关闭
🗂 分组，支持组标签、分隔符与空态（无匹配 / 空数据）
🧹 可清空输入（clearable → clearLabel / resetModelValueOnClear）
🎛 openOnFocus / openOnClick 双打开策略，支持受控 v-model:open
📊 数据驱动 AutocompleteCompact API——items / labelField + 分组
♿ 遵循 WAI-ARIA combobox 模式——role="combobox" / listbox / option、aria-activedescendant、打开态 axe 零违规
🎨 autocompleteVariants 提供 17 个配方插槽与 7 个尺寸变体

演示

基础

100%

Value: —

分组

100%

自定义样式

100%

API

Aria 层

Autocomplete<T>

32 属性4 事件9 插槽

属性

属性名	类型	默认值	描述
class	ClassValue	—	根类。
size	ThemeSize	—	组件的视觉尺寸。
ui	Partial<AutocompleteUi>	—	该组件的按槽类重写。
modelValue	string	—	自动完成输入框的受控值。
defaultValue	string	—	自动完成输入框的初始值。
items	AutocompleteOptionData<T>[]	—	由该组件渲染的项。
placeholder	string	—	占位符。
clearable	boolean	—	是否可清除。
clearLabel	string	—	标签清晰。
emptyLabel	string	—	空标签。
fuseOptions	UseFuseOptions<T>	—	Fuse 选项。
anchorProps	AutocompleteAnchorProps	—	转发给锚元素的属性。
inputProps	AutocompleteInputProps	—	转发给输入元素的属性。
triggerProps	AutocompleteTriggerProps	—	转发给触发元素的属性。
portalProps	PortalProps	—	转发给 portal 元素的属性。
contentProps	AutocompleteContentProps	—	转发给内容元素的属性。
viewportProps	AutocompleteViewportProps	—	转发给视口元素的属性。
groupProps	AutocompleteGroupProps	—	转发给 group 元素的属性。
groupLabelProps	AutocompleteGroupLabelProps	—	转发至组标签元素的属性。
itemProps	Omit<AutocompleteItemProps, 'disabled' \| 'value'>	—	转发给 item 元素的属性。
itemIndicatorProps	AutocompleteItemIndicatorProps	—	转发至项指示器元素的属性。
separatorProps	AutocompleteSeparatorProps	—	转发给分隔符元素的属性。
open	boolean	—	自动完成弹出窗口的受控打开状态。
defaultOpen	boolean	—	自动完成弹出窗口在初始渲染时的状态为“打开”。
disabled	boolean	—	当值为 `true` 时，禁止用户与自动完成功能进行交互。
dir	Direction	—	在适用情况下，自动补全功能的阅读方向。
name	string	—	字段的名称。作为名称/值对的一部分，与其所属表单一同提交。
highlightOnHover	boolean	—	当值为 `true` 时，将鼠标悬停在项目上会触发高亮显示。
openOnFocus	boolean	—	当输入框获得焦点时，是否打开自动完成功能。
openOnClick	boolean	—	点击输入框时是否打开自动完成功能。
resetModelValueOnClear	boolean	—	当 `true` 时，清除搜索词也会将 `modelValue` 重置为空字符串。
required	boolean	—	当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。

事件

事件名	参数	描述
update:modelValue	string	当模型值发生变化时触发。
update:open	boolean	在打开状态发生变化时触发。
highlight	AutocompleteHighlightPayload \| undefined	当发生高亮时触发。
select	T	在发生 select 事件时触发。

插槽

插槽名	参数	描述
input-leading	—	输入首槽的自定义内容。
input-trailing	—	输入末尾槽位的自定义内容。
trigger-icon	—	触发图标槽位的自定义内容。
empty	—	为空槽位添加自定义内容。
group-label	{ item: AutocompleteGroupOptionData<T> \| Extract<T, { items: T[]; }>; }	组标签槽位的自定义内容。
item-leading	{ item: T; }	用于项目引导槽位的自定义内容。
item-text	{ item: T; }	针对“项文本”插槽的自定义内容。
item-trailing	{ item: T; }	用于项目尾部槽位的自定义内容。
item-indicator	{ item: T; }	项目指示符插槽的自定义内容。

AutocompleteAnchor

3 属性

属性

属性名	类型	默认值	描述
reference	ReferenceElement	—	—
asChild	boolean	—	将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。
as	AsTag \| Component	'div'	该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。

AutocompleteCompact<T>

29 属性4 事件9 插槽

属性

属性名	类型	默认值	描述
modelValue	string	—	自动完成输入框的受控值。
defaultValue	string	—	自动完成输入框的初始值。
items	AutocompleteOptionData<T>[]	—	由该组件渲染的项。
placeholder	string	—	占位符。
clearable	boolean	—	是否可清除。
clearLabel	string	—	标签清晰。
emptyLabel	string	—	空标签。
fuseOptions	UseFuseOptions<T>	—	Fuse 选项。
anchorProps	AutocompleteAnchorProps	—	转发给锚元素的属性。
inputProps	AutocompleteInputProps	—	转发给输入元素的属性。
triggerProps	AutocompleteTriggerProps	—	转发给触发元素的属性。
portalProps	PortalProps	—	转发给 portal 元素的属性。
contentProps	AutocompleteContentProps	—	转发给内容元素的属性。
viewportProps	AutocompleteViewportProps	—	转发给视口元素的属性。
groupProps	AutocompleteGroupProps	—	转发给 group 元素的属性。
groupLabelProps	AutocompleteGroupLabelProps	—	转发至组标签元素的属性。
itemProps	Omit<AutocompleteItemProps, 'disabled' \| 'value'>	—	转发给 item 元素的属性。
itemIndicatorProps	AutocompleteItemIndicatorProps	—	转发至项指示器元素的属性。
separatorProps	AutocompleteSeparatorProps	—	转发给分隔符元素的属性。
open	boolean	—	自动完成弹出窗口的受控打开状态。
defaultOpen	boolean	—	自动完成弹出窗口在初始渲染时的状态为“打开”。
disabled	boolean	—	当值为 `true` 时，禁止用户与自动完成功能进行交互。
dir	Direction	—	在适用情况下，自动补全功能的阅读方向。
name	string	—	字段的名称。作为名称/值对的一部分，与其所属表单一同提交。
highlightOnHover	boolean	—	当值为 `true` 时，将鼠标悬停在项目上会触发高亮显示。
openOnFocus	boolean	—	当输入框获得焦点时，是否打开自动完成功能。
openOnClick	boolean	—	点击输入框时是否打开自动完成功能。
resetModelValueOnClear	boolean	—	当 `true` 时，清除搜索词也会将 `modelValue` 重置为空字符串。
required	boolean	—	当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。

事件

事件名	参数	描述
update:modelValue	string	当模型值发生变化时触发。
update:open	boolean	在打开状态发生变化时触发。
highlight	AutocompleteHighlightPayload \| undefined	当发生高亮时触发。
select	T	在发生 select 事件时触发。

插槽

插槽名	参数	描述
input-leading	—	输入首槽的自定义内容。
input-trailing	—	输入末尾槽位的自定义内容。
trigger-icon	—	触发图标槽位的自定义内容。
empty	—	为空槽位添加自定义内容。
group-label	{ item: Extract<AutocompleteOptionData<T>, { items: T[]; }>; }	组标签槽位的自定义内容。
item-leading	{ item: T; }	用于项目引导槽位的自定义内容。
item-text	{ item: T; }	针对“项文本”插槽的自定义内容。
item-trailing	{ item: T; }	用于项目尾部槽位的自定义内容。
item-indicator	{ item: T; }	项目指示符插槽的自定义内容。

AutocompleteContent

27 属性7 事件

属性

属性名	类型	默认值	描述
position	'inline' \| 'popper'	—	职位。
bodyLock	boolean	—	是否启用正文锁定。
hideWhenEmpty	boolean	—	是否在为空时隐藏。
popupProps	PopperPositioningPopupProps	—	转发给弹出窗口元素的属性。
open	boolean	true	浮动层是否处于打开状态。该状态驱动定位生命周期（当打开状态切换时，`isPositioned` 会重置）；定位原语本身没有打开状态，因此调用方需在此处自行处理打开状态。
placement	Placement	undefined	浮动元素的位置。若使用该属性，它将覆盖 `side` 和 `align` 属性。
side	Side	'bottom'	打开时优先渲染的锚点侧。当发生冲突且启用了 avoidCollisions 时，该侧将反转。
sideOffset	number	0	距锚点的像素距离。
sideFlip	boolean	true	遇到边界时，请翻转至另一侧。
align	Align	'center'	首选与锚点对齐。发生冲突时可能会调整对齐方式。
alignOffset	number	0	相对于 `start` 或 `end` 对齐选项的像素偏移量。
alignFlip	boolean	true	当与边界发生冲突时，翻转对齐方式。此情况仅在 `prioritizePosition` 为 true 时才会发生。
avoidCollisions	boolean	true	当值为 `true` 时，将覆盖“侧边”和“对齐”首选项，以避免与边界边缘发生冲突。
collisionBoundary	Element \| (Element \| null)[] \| null	[ ]	用作碰撞边界的元素。默认情况下，该边界为视口，但您可以提供额外的元素以纳入此检查范围。
collisionPadding	Padding	0	从边界边缘开始，碰撞检测应发生的距离（以像素为单位）。接受一个数字（所有边均相同），或一个部分填充对象，例如：{ top: 20, left: 20 }。
arrowPadding	number	0	箭头与内容边缘之间的间距。如果您的内容使用了 border-radius，这将防止内容溢出到角落。
hideShiftedArrow	boolean	false	当值为 `true` 时，若无法将箭头居中对齐到引用元素上，则隐藏该箭头。
sticky	'partial' \| 'always'	'partial'	在对齐轴上的“粘附”行为。`partial` 会在锚点至少部分位于边界内时将内容保留在边界内，而 “always” 则无论如何都会将内容保留在边界内。
hideWhenDetached	boolean	false	当锚点被完全遮挡时，是否隐藏内容。
positionStrategy	'fixed' \| 'absolute'	'fixed'	要使用的 CSS `position` 属性的类型。
updatePositionStrategy	'always' \| 'optimized'	'optimized'	在每个动画帧中更新浮动元素位置的策略。
disableUpdateOnLayoutShift	boolean	false	当布局发生变化时，是否禁用内容的更新位置。
prioritizePosition	boolean	false	强制内容位于视口内。可能会与参考元素重叠，这可能并非预期效果。
reference	ReferenceElement	—	将作为浮动元素定位参考点的自定义元素或虚拟元素。如果提供了该元素，它将替换默认的锚点元素。
trapFocus	boolean	false	当设置为 `true` 时，焦点无法通过键盘、指针或程序化焦点离开该内容。
disableOutsidePointerEvents	boolean	—	当值为 `true` 时，`DismissableLayer` 外部元素的悬停/聚焦/点击交互将被禁用。用户需要双击外部元素才能与其交互：第一次用于关闭 `DismissableLayer`，第二次用于触发该元素。
forceMount	boolean	—	用于在需要更多控制时强制挂载。在使用 Vue 动画库控制动画时非常有用。

事件

事件名	参数	描述
escapeKeyDown	KeyboardEvent	当 Esc 键被按下时触发的事件处理程序。可被阻止。
pointerDownOutside	PointerDownOutsideEvent	当 `pointerdown` 事件发生在 `DismissableLayer` 外部时调用的事件处理程序。可被阻止。
focusOutside	FocusOutsideEvent	当焦点移出 `DismissableLayer` 时触发的事件处理程序。可被阻止。
interactOutside	PointerDownOutsideEvent \| FocusOutsideEvent	当在 `DismissableLayer` 外部发生交互时触发的事件处理程序。具体而言，当 `pointerdown` 事件在该区域外部发生，或焦点移出该区域时触发。此事件可被阻止。
openAutoFocus	Event	在打开页面时自动聚焦时触发的事件处理程序。可被阻止。
closeAutoFocus	Event	在关闭时自动聚焦时触发的事件处理程序。可被阻止。
placed	—	当定位器被放置时调用的事件处理程序

AutocompleteGroup

AutocompleteGroupLabel

AutocompleteInput

15 属性

属性

属性名	类型	默认值	描述
inputRef	((el: HTMLInputElement) => void)	—	输入参考。
controlProps	InputControlProps	—	转发给控件的属性。
disabled	boolean	—	当值为 `true` 时，禁止用户与输入内容进行交互。
id	string	—	输入元素的 ID
placeholder	string	—	输入的占位符
type	InputTypeHTMLAttribute	—	输入元素的类型。
autofocus	boolean	—	当值为 `true` 时，系统会自动聚焦于输入内容。
name	string	—	字段的名称。作为名称/值对的一部分，与其所属表单一同提交。
required	boolean	—	当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。
readonly	boolean	—	当值为 `true` 时，输入内容为只读。
rootProps	BaseProps	—	转发至根元素的属性
autocomplete	'search' \| 'name' \| 'email' \| 'tel' \| 'url' \| 'on' \| 'off' \| 'username' \| 'current-password' \| 'new-password' \| 'one-time-code' \| 'given-name' \| 'family-name' \| 'organization' \| 'street-address' \| 'address-level2' \| 'postal-code' \| 'country' \| 'cc-name' \| 'cc-number' \| 'cc-exp' \| 'cc-csc' \| 'transaction-amount'	—	输入字段的 autocomplete 属性。除 `on` / `off` 开关外，还支持 HTML 自动填充标记（包括密码管理器的值，例如 `current-password` / `new-password`）。
maxlength	number	—	输入内容允许的最大字符数
minlength	number	—	输入内容允许的最小字符数
pattern	string	—	输入的 pattern 属性

AutocompleteItem

5 属性1 事件

属性

属性名	类型	默认值	描述
textValue	string	—	文本值。
value	string	—	作为数据提交时与 `name` 关联的值。
disabled	boolean	—	当值为 `true` 时，禁止用户与该项进行交互。
asChild	boolean	—	将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。
as	AsTag \| Component	'div'	该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。

事件

事件名	参数	描述
select	SelectEvent<string>	当选中某项时触发的事件处理程序。<br> 可以通过调用 `event.preventDefault` 来阻止该事件。

AutocompleteItemIndicator

2 属性

属性

属性名	类型	默认值	描述
asChild	boolean	—	将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。
as	AsTag \| Component	'div'	该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。

AutocompletePortal

AutocompleteRoot

12 属性3 事件

属性

属性名	类型	默认值	描述
modelValue	string	—	自动完成输入框的受控值。
defaultValue	string	—	初始渲染时自动完成输入框的值。
open	boolean	—	自动完成弹出窗口的受控打开状态。
defaultOpen	boolean	—	自动完成弹出窗口在初始渲染时的状态为“打开”。
dir	Direction	—	在适用情况下，自动补全功能的阅读方向。
disabled	boolean	—	当值为 `true` 时，禁止用户与自动完成功能进行交互。
highlightOnHover	boolean	—	当值为 `true` 时，将鼠标悬停在项目上会触发高亮显示。
openOnFocus	boolean	—	当输入框获得焦点时，是否打开自动完成功能。
openOnClick	boolean	—	点击输入框时是否打开自动完成功能。
resetModelValueOnClear	boolean	—	当 `true` 时，清除搜索词也会将 `modelValue` 重置为空字符串。
name	string	—	字段的名称。作为名称/值对的一部分，与其所属表单一同提交。
required	boolean	—	当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。

事件

事件名	参数	描述
update:modelValue	string	当模型值发生变化时触发。
update:open	boolean	在打开状态发生变化时触发。
highlight	AutocompleteHighlightPayload \| undefined	当发生高亮时触发。

AutocompleteSeparator

2 属性

属性

属性名	类型	默认值	描述
asChild	boolean	—	将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。
as	AsTag \| Component	'div'	该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。

AutocompleteTrigger

3 属性

属性

属性名	类型	默认值	描述
disabled	boolean	—	该组件是否已禁用。
asChild	boolean	—	将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。
as	AsTag \| Component	'div'	该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。

AutocompleteViewport

1 属性

属性

属性名	类型	默认值	描述
nonce	string	—	随机数。

注意事项

架构与对标差异

VeanUI 通过复用 combobox 组件族（Anchor/Content/Item/Viewport/Trigger/Empty/Cancel，全部基于 listbox 基座 + Popper 定位）构建自动完成。AutocompleteRoot 关闭 combobox 内置过滤（ignoreFilter），把匹配委托给 compact 层的 useFuse，使 autocomplete 与 combobox 共享同一套交互内核，仅过滤与展示策略不同。scv() 配方 autocompleteVariants 声明 17 个插槽与 7 个尺寸变体。

能力	VeanUI	reka-ui `Combobox`	Algolia Autocomplete	Ant Design `AutoComplete`
Aria/styled 分离	✅	✅	—	—
输入即过滤 + 模糊匹配	✅	—	✅	✅
combobox/listbox 角色	✅	✅	✅	✅
键盘导航 + typeahead	✅	✅	✅	✅
分组 + 组标签	✅	✅	—	—
`openOnFocus` / `openOnClick`	✅	—	✅	✅
清空按钮 + 空态	✅	✅	—	✅
数据驱动 Compact API	✅	—	—	—
axe 零违规（打开态）	✅	—	—	—

注意事项

过滤在客户端以 Fuse 完成；远程建议需自行传入已过滤的 items 或对输入做防抖。
焦点移到清空按钮时弹出层保持打开（blur 圈闭判定覆盖整个 anchor 区域），仅当焦点真正离开组件时才关闭——这是已修复的回归行为，不要改回只判 trigger 的旧逻辑。
根节点 disabled 时所有条目都不可选——包括自带 disabled 的条目（统一 rootDisabled || item.disabled 守卫）。
viewport（role="listbox"）默认注入本地化的 aria-label；可通过 viewportProps['aria-label'] 覆盖。

常见问题

如何在不输入时也显示建议？

使用 openOnFocus 让输入框聚焦即打开弹出层，openOnClick 让点击输入框时打开。

如何调节模糊匹配的宽松程度？

传入 fuseOptions 调优 Fuse 搜索——例如调高 threshold 放宽匹配，或用 keys 限定参与匹配的字段。

`SAutocomplete`、`SCombobox` 与 `SSelect` 有什么区别？

SAutocomplete 对自由文本做模糊匹配建议（Fuse）；SCombobox 对已知选项列表做输入过滤；SSelect 由触发器驱动、仅支持 typeahead、无文本输入。

如何清空输入并重置模型值？

传入 clearable。resetModelValueOnClear 决定清除时是否同时发出空 modelValue，还是仅重置搜索词。

快速跳转

同分类组件

自动完成

概述

用法

特性

演示

基础

分组

自定义样式

API

Aria 层

Autocomplete<T>

属性

事件

插槽

AutocompleteAnchor

属性

AutocompleteCompact<T>

属性

事件

插槽

AutocompleteContent

属性

事件

AutocompleteGroup

AutocompleteGroupLabel

AutocompleteInput

属性

AutocompleteItem

属性

事件

AutocompleteItemIndicator

属性

AutocompletePortal

AutocompleteRoot

属性

事件

AutocompleteSeparator

属性

AutocompleteTrigger

属性

AutocompleteViewport

属性

注意事项

架构与对标差异

注意事项

常见问题

如何在不输入时也显示建议？

如何调节模糊匹配的宽松程度？

SAutocomplete、SCombobox 与 SSelect 有什么区别？

如何清空输入并重置模型值？

更新日志

v0.31.0

重构

v0.16.0

重构

v0.15.0

优化

优化

`SAutocomplete`、`SCombobox` 与 `SSelect` 有什么区别？