AutoComplete 自动完成
输入即推荐：值是自由文本（浏览器地址栏 / datalist 心智），建议列表只辅助输入，支持键盘选择、分组、防抖远程建议、自定义渲染。
与 Select(searchable) / Combobox 的边界
组件 值的来源 输入框形态 适用场景 oas-auto-complete任意自由文本，建议只是快捷方式 输入框即控件 搜索框联想、邮箱补全、标签自由输入 oas-select searchable必须来自选项集合 按钮触发，展开后才出现搜索框 收敛选择（值必须合法） oas-combobox必须来自选项集合 输入框即控件，输入仅过滤 常显输入框形态的收敛选择 需要值必须 ∈ 选项时用 select(searchable) 或 combobox，不要试图给 auto-complete 加「严格校验」；多选/标签场景用
oas-select multiple或oas-dynamic-tags，auto-complete 保持单值自由文本。
基础用法
基础用法
输入关键字会在下拉中自动过滤匹配项；首项默认高亮，Enter 直达首项；↑/↓ 移动高亮、Esc 关闭；失焦不清空输入（自由文本不回退）。
预设值
预设值（value）
程序性读/写当前值走公开 value property（el.value 读、el.value = x 写，对齐原生 input.value）。注意 label / 值分离：本组件提交语义为「可见文本」——选中某建议后 el.value 返回该建议的 label（可见文本），而 value 属性为 option.value（如 apple）；oas-form 的 values 快照读属性（= option.value），两者数据不同层，按需选用。
可清空
可清空（clearable）
输入框有内容时显示清空按钮，点击清空输入并派发 oas-clear 与 oas-change（空值）。
远程建议（debounce + loading）
远程搜索建议
debounce（毫秒，默认 0 不防抖）只防抖 oas-input 派发与过滤触发，输入回显不被防抖；宿主在 oas-input 里请求期间置 loading，下拉显示「加载中…」占位，回填 options 后即展示。
聚焦即展示（trigger-on-focus）
聚焦展示全部建议（trigger-on-focus）
默认关闭（聚焦空输入弹全量建议对紧凑表单是打扰）；显式开启后走 datalist 心智：聚焦即按当前输入过滤展示建议。
分组建议
分组（group）
选项带 group 字段时按组渲染组标题（不可选），组内选项缩进；键盘 ↑/↓ 跨组连续导航。
大数据量（虚拟滚动）
虚拟滚动（1000 项建议）
设置 virtual 后建议面板只渲染可视窗口（复用 oas-virtual-list 的窗口计算，首尾 padding 撑起滚动高度），千级建议滚动流畅、面板高度恒定；item-height 可调定高（默认 36）。键盘 ↑/↓ 导航时窗口自动跟随高亮项，aria-activedescendant 保持指向可见项；带 group 的选项自动回退全量渲染（同 oas-select 契约）。
自定义选项渲染
自定义选项（oas-option-render 事件）
自定义选项（template 插槽）
双通道与 oas-select 一致：监听 oas-option-render（detail.element 为文本容器，宿主可改写为图标/富文本）；或在组件内放 <template slot="option"> 提供静态骨架，[data-option-label] 节点自动绑定选项文本。
面板插槽（header / footer / empty）
面板头尾与空态插槽
header / footer 插槽渲染建议面板头尾（「输入试试 xx」提示条、「查看全部」链接）；empty 插槽替换默认「无匹配结果」空态文案。
尺寸与校验态
尺寸（size）
校验态（status）
size 支持 small / medium / large（就近跟随 oas-config-provider 的 size 注入）；status 支持 success / warning / error（error 同步 aria-invalid，可被 oas-form-item 校验态驱动）。
形态（variant）
形态（variant）
variant 对齐 oas-input 三值变体：outlined（默认，描边）/ filled（填充灰底，hover 显边）/ borderless（无框，聚焦无阴影）；非法值回落 outlined。
焦点事件（oas-focus / oas-blur）
focus / blur 事件
聚焦/失焦派发 oas-focus / oas-blur，detail: { value } 携带当前输入文本，对齐 oas-input 同名事件契约。
只读
只读（readonly）
readonly 可聚焦可复制、不可输入，聚焦与键盘不再展开建议。
中文输入法（IME）
输入法组合期间（拼音候选确认前）组件不触发过滤、不派发 oas-input、回车不误选建议；组合结束后以最终文本补发一次。本页所有 demo 直接用中文输入即可感知，无需额外配置。
禁用
禁用
无匹配结果
空态
事件
输入与选中事件
监听 oas-input（输入中，防抖后）、oas-change（选中或清空）、oas-clear（清空）：
required 必填
required 必填（原生校验链）
required 驱动原生校验链（form-associated）：未填时 checkValidity() 为 false（valueMissing），原生表单提交被阻止；填写后自动恢复 :valid。
程序性读/写当前值走公开 value property（对齐原生 input.value）：el.value 读取——当前输入文本；el.value = x 写入——写受控 value 属性并即时回写内部控件（清掉键入过滤词），不派发事件。
面板放置方向
placement 控制建议面板的 12 向放置（对齐浮层定位引擎，-start / -end 为书写方向逻辑语义，RTL 自动镜像）：空间不足沿主轴自动翻转、视口边缘避让。默认 bottom-start（面板左缘对齐输入框左缘、向下展开）；实际落位（含翻转结果）写入面板 data-placement。
placement=top-start（向上展开）
autofocus
autofocus 转发到内部输入框（原生 autofocus 不穿透 Shadow DOM）：组件挂载后自动聚焦一次。点击下方按钮重新挂载一个带 autofocus 的实例，观察光标自动落入输入框。
挂载即聚焦
API
oas-auto-complete
属性
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
autofocus | 挂载后聚焦内部输入框 | boolean | — |
clearable | 可清空（输入有内容时显示清空按钮，清空派发 oas-clear 与空值 oas-change） | boolean | — |
debounce | 输入防抖（毫秒，默认 0 不防抖）：只防抖 oas-input 派发与过滤触发，不防抖输入回显 | string | 0 |
disabled | 禁用 | boolean | — |
item-height | 虚拟滚动定高（px，配合 virtual，默认 36） | string | 36 |
loading | 加载占位（下拉显示「加载中…」，远程建议请求态） | boolean | — |
options | 选项，JSON 数组 [{ label, value, disabled?, group? }]（group 为分组标题） | Option[] | string | [] |
placeholder | 占位提示 | string | — |
placement | 面板 12 向放置（引擎翻转/RTL 镜像结果写 data-placement） | string | bottom-start |
readonly | 只读（可聚焦可复制不可输入，聚焦与键盘不展开建议） | boolean | — |
required | 必填标记（驱动原生校验链 valueMissing；不透传内层控件） | boolean | — |
size | 尺寸档位：small / medium / large（默认 medium，就近跟随 config-provider 注入） | string | medium |
status | 校验态：success / warning / error（error 同步 aria-invalid，可被 oas-form-item 校验驱动） | string | — |
trigger-on-focus | 聚焦即展示建议（datalist 心智；默认关闭，维持「输入优先」现状） | boolean | — |
value | 预设值 | string | — |
variant | 形态变体：outlined（默认）/ filled / borderless，非法值静默回落 | string | — |
virtual | 虚拟滚动（复用 oas-virtual-list 仅渲染可视窗口；带 group 的选项自动回退全量渲染） | boolean | — |
Property（JS property；是否写回 attribute 见各行说明）
| Property | 说明 | 类型 | 默认值 |
|---|---|---|---|
value | 当前值：可见文本（选中建议后为该项 label）；value 属性为 option.value | string | — |
事件
| 事件 | 说明 |
|---|---|
oas-blur | 失焦时派发，detail: { value } 携带当前输入文本 |
oas-change | 选中或清空，detail: { value, label } |
oas-clear | 点击清空按钮，detail: { value }（清空前的值） |
oas-focus | 聚焦时派发，detail: { value } 携带当前输入文本 |
oas-input | 输入中（防抖后），detail: { value } |
oas-option-render | 每个选项行渲染后派发，detail: { index, option, element }，宿主可改写 element（图标/富文本） |
插槽
| 名称 | 说明 |
|---|---|
empty | 自定义无匹配空态（替换默认文案） |
footer | 建议面板底部内容（如「查看全部」链接） |
header | 建议面板头部内容（如「输入试试 xx」提示条） |
template[slot="option"] | 自定义选项模板骨架，[data-option-label] 节点自动绑定选项文本 |
CSS 变量
| CSS 变量 | 默认值 |
|---|---|
--oas-auto-complete-dropdown-height | 240px |
--oas-glass-blur | none |
--oas-glass-ring | transparent |
键盘：↑/↓ 移动（循环），Enter 选中高亮项（首项默认高亮），Esc 关闭。