使用方法

Typeahead 是单选搜索框。输入框是 combobox，下拉列表是 listbox。本地数据用 createStaticSource，远程数据自己实现 search。

本地搜索按标签和可选关键词做子串匹配。debounceMs 设为 0 会立刻过滤：

<script setup lang="ts">
import { createStaticSource } from '@astryx-vue/core'
import { Typeahead } from '@astryx-vue/core/Typeahead'
import { ref } from 'vue'

const selected = ref(null)
const source = createStaticSource([
  { id: 'apple', label: '苹果' },
  { id: 'grape', label: '葡萄' },
], { keywords: item => item.id === 'grape' ? ['提子'] : [] })
</script>

<template>
  <Typeahead v-model="selected" :search-source="source" label="水果" :debounce-ms="0" show-on-focus />
</template>

异步数据源返回 Promise。useAsyncSource 会在输入停顿后发起请求，默认等待 150 毫秒。新的一次搜索会取消上一次，过期结果不会写回列表。空查询优先走 bootstrap。加载、没有结果、请求失败分别显示加载文案、空状态和错误文案。

方向键移动高亮项，Enter 选中，Escape 关闭列表。焦点在输入框里时，Home 和 End 移动光标。选中后结果收成一枚可聚焦的标签，再次聚焦会回到搜索。

内置文案默认是英文。调用 provideAstryxLocale('zh-CN') 后改为中文。文档页会按当前语言自动提供。

解剖

部分	说明
字段	提供标签和可选辅助内容的独立 Field 外壳。放在 InputGroup 里时不画这一层。
输入表面	装着可编辑输入或已选标签的着色控件表面。
图标渲染的起始图标	可选的前导语义图标或图标组件，通过 Icon 绘制。
使用方渲染的起始内容	直接画在输入表面开头的可选任意插槽内容。
已选标签	控件不在编辑状态时，用来呈现已选项的 Token。
转圈	搜索进行中时，输入表面末尾的加载指示。
清除按钮	共用的清除操作。clearable 打开时去掉已选项。
下拉	装着当前搜索结果的锚定列表框表面。
空状态	一次搜索完成但没有结果时的消息。
结果行	稳定的选项外层，负责高亮、选中、指针和键盘行为。
默认项内容	没有提供 item 插槽时，结果行里画出的标准标签和辅助内容。
使用方渲染的项内容	通过 item 插槽放进稳定结果行里的、由使用方拥有的结果内容。
结果分组标题	一组带标签的结果行的可见标题。
已选结果状态	当前结果行上的选中样式，以及尾部的勾。

最佳实践

指引	实践
推荐	本地数据把 debounceMs 设为 0，远程请求保留默认防抖。
推荐	远程源在 signal 被取消时中止请求，避免过期结果覆盖新结果。
避免	用自动补全做多选。多选固定列表用多选器，多选搜索用标签输入框。

示例

限制结果

Country

下拉最多显示三条结果。

搜索框

Team member

带搜索图标，聚焦后就给出建议。

辅助说明

Department

Select the department this request should be routed to

标签下面有一段说明。

校验

Office

Please select an office location

用错误状态提示必须选择一个地点。

无字段外壳

BaseTypeahead 没有字段标签和说明。命令面板这类已经有自己标题的地方用它，输入框的无障碍名用 label 传入。