---
id: "autocomplete"
title: "自动补全"
category: "输入组件"
document_type: "component-specification"
spec_status: "local-current-draft"
element_ui: "2.15.6"
vue: "2.6.14"
page: "../index.html#spec-autocomplete"
source_data: "../component-data.json"
official_components: ["autocomplete"]
template_components: ["el-autocomplete"]
scenario_count: 7
verification: "scenario-checklist-not-full-test-pass"
---

# 自动补全

专题 `autocomplete` · 输入组件 · Element UI 2.15.6

## 适用范围与组件映射

公共色板及字体基线适用于整个运营后台。本库整理基础组件、组件状态和可复用的组合模式；本轮补齐表单整体验证、页面布局和导航组合；具体业务字段与跨页流程仍在业务场景中说明。专题验收清单包含接入要求，不表示当前示例已实现或已验证全部场景。

官方条目映射：`autocomplete`。

本页模板直接使用的 Element UI 标签：`el-autocomplete`。

## 通用基线

- 组件库：Element UI **2.15.6**；运行样例 Vue **2.6.14**。
- 系统中文字体：macOS 优先苹方，Windows 通常微软雅黑；工程顺序固定为 `"PingFang SC", "Microsoft YaHei", sans-serif`。不要求安装或加载网络字体，兼容回退不是另一套可选样式。
- 后续仅采用经验证且固定版本的兼容 Element UI 2.x；Element Plus 属于独立迁移路线。
- 正文、数据值、输入及已选值：`14px / 400 / 21px`，`#303133`。
- 表头及组件分组标题：`14px / 600 / 21px`；弹窗标题：`16px / 600 / 24px`，均使用 `#303133`。
- 辅助说明：`12px / 400 / 18px`，`#595959`；错误、链接、状态、禁用与占位按各自语义处理。
- 适用组件的默认尺寸为 `small / 32px`；不得将这一高度机械应用于表格、文本域、浮层等全部组件。
- 规范正文与场景说明使用 `14px / 400 / 24px`、`#303133`，不降成灰蓝小字。
- 筛选文本输入占位统一“请输入”；未选择下拉统一“请选择”；默认全部的下拉显示“全部”。字段标签保留业务含义；日期保留开始/结束语义。
- 次级文字操作（查看更多、编辑、详情、数据中心、更多）：`12px / 400 / 18px`，`#3377BB`；保留点击热区。
- 本规范库的深色目录、蓝色展示区属于文档排版，不是业务组件颜色或业务导航规范。

## 本页用法与分类

默认用法：需要键入内容并从建议中快速填写时，使用单行自动补全框。本页本地样例允许保留手动值；新增账号的上级代理则要求该值匹配所选商户下已启用的代理。是否接受自由值由字段规则确定。

| 区分什么 | 本页内容 | 选用或触发条件 |
| --- | --- | --- |
| 用途：可输入建议 | 自动补全提供可编辑输入与建议；手动输入值是否必须匹配已有记录由业务字段校验决定。 | 需要按完整账号等键入并匹配建议时可用自动补全；只需选择封闭枚举时优先单选下拉。不得用关闭候选面板、无建议或成功回填代替业务合法性校验。 |
| 功能：建议与确认 | 输入文字、定位候选和接受候选是不同动作。 | 本页按关键词显示建议；方向键只定位，回车接受后才回填。聚焦查询、首项高亮和自定义候选由字段需要确定，未启用的不算默认配置。 |
| 自动状态：查询反馈 | 有建议、无建议、加载和失败由数据结果产生。 | 本页验证本地有建议、无建议及手动值保留；需要远程查询时再接入加载、失败和请求防抖，无建议不自动等于输入错误。 |

使用边界：不把候选高亮当作已选值。不把无建议、加载或失败列成可任选的外观。

## 组件规则

- **AUTOCOMPLETE-R01**：用于可键入内容并提供匹配建议的字段；手动输入是否必须匹配已有记录由字段校验决定，不能把可输入等同于任意值都可保存。仅需从封闭选项中选择、无需按账号等精确值检索时优先单选下拉。本页使用本地建议并支持清除，输入、查询和选择结果按实际状态反馈，不作为可选样式。
- **AUTOCOMPLETE-R02**：输入宽度统一参考输入框专题，与同组表单内容列对齐；建议面板以触发框为宽度基准，长建议换行或提供完整值读取，并受视口边界约束。查询、无结果或清除不改变输入外宽。
- **AUTOCOMPLETE-R03**：远程查询需要防抖，旧响应不得覆盖新关键词；组件失焦不吞掉用户输入。键盘上下只定位候选，回车键接受并回填，退出键关闭建议面板。
- **AUTOCOMPLETE-R04**：演示使用本地建议，不发网络；测试输入 A、Z 与清除。
- **AUTOCOMPLETE-R05**：【公共用色】颜色仅从公共色值 引用：主色系 3 个基础色值、辅助功能色 3 个、中性色 10 个，共 16 个基础色值。角色可以多个，实际色值复用；不为每个组件、悬停 或不同字段再新增近似颜色。透明效果仅限遮罩 35% 与阴影 12%，从 外壳深色 派生。
- **AUTOCOMPLETE-R06**：【统一字体】统一系统中文字体：macOS 优先苹方（PingFang SC），Windows 通常使用微软雅黑（Microsoft YaHei）；工程顺序固定为 "PingFang SC", "Microsoft YaHei", sans-serif。使用设备已有字体，不要求安装或加载网络字体；最后一项仅作兼容回退，不是供页面作者任选的另一套样式。正文 14px/400/21px；表头与分组标题 14px/600/21px，弹窗标题 16px/600/24px；次级文字操作和辅助说明 12px/400/18px。正文与标题同用 #303133；不通过额外加粗或透明度改变正文轻重。
- **AUTOCOMPLETE-R07**：【叠加优先级】状态叠加规则：禁用阻断交互；输入类控件错误边框覆盖蓝色聚焦边框；输入框不叠加外圈或阴影，其他无边框操作保留键盘焦点提示；选中底覆盖悬停底；只读不等于禁用；加载不等于成功；业务启用/停用的文字结果不等于控件是否可点击。
- **AUTOCOMPLETE-R08**：输入及选择触发框统一单层矩形：默认 白色 底、正文深灰 14px/400 字、禁用灰 占位、边框灰 边框；聚焦仅原边框 主题蓝，错误 错误红。鼠标点击与键盘进入均不新增外框或阴影。范围日期仅外层容器变边框，内部两个输入不重复画框。
- **AUTOCOMPLETE-R09**：仅接入真实字段校验时，触发框和就近错误短提示同步使用错误红；若配置错误图标，图标也同步。普通聚焦不报错，禁用不触发新校验；候选查询无匹配不等于字段错误，当前本地示例不伪造远端失败。
- **AUTOCOMPLETE-R10**：输入族统一直角 0px：普通输入、密码、文本域、自动补全、单选/多选触发框、级联、日期/时间与范围、数字输入及前后缀组合输入；默认/聚焦/错误/只读/禁用均不改变圆角。组合输入外侧和拼接处均不保留小圆角，弹出面板的圆角由面板规范独立定义。
- **AUTOCOMPLETE-R11**：【输入框】白底、正文深灰、边框灰；占位禁用灰；聚焦仅原边框主题蓝，不加外圈。
- **AUTOCOMPLETE-R12**：【候选项】普通项正文深灰；悬停或键盘定位使用浅灰背景，实际选中才回填输入值，不增加复选框。
- **AUTOCOMPLETE-R13**：【禁用与只读】禁用输入浅灰背景、禁用灰且不发起新查询；只读值正文深灰，可复制但不选择新建议。
- **AUTOCOMPLETE-R14**：【校验与查询反馈】真实输入错误时边框及短提示错误红；远程加载用主题蓝图标，无匹配为空值灰，失败才显示错误红。
- **AUTOCOMPLETE-R15**：【组件边界】自动补全包含可编辑输入和候选项定位；聚焦输入不等于选择候选项，没有复选半选态。

## 场景与验收清单

以下为需核对的场景组；`[ ]` 不代表已经测试通过。

- [ ] **AUTOCOMPLETE-S01**：当前样例使用本地Alpha/Atlas/Beta/Component建议；输入A、Z和清除，检查有建议、无建议及手动值保留。
- [ ] **AUTOCOMPLETE-S02**：当前样例：方向键定位、Enter接受、Esc关闭；候选高亮不等于最终选择。
- [ ] **AUTOCOMPLETE-S03**：接入验收：按字段需要确定聚焦查询、首项高亮和自定义候选；采用远程查询后再验证防抖、加载、失败、超时与旧响应竞态。上述配置不代表当前本地样例全部采用。
- [ ] **AUTOCOMPLETE-S04**：业务采用：新增账号 → 新增会员 → 上级代理。先选商户，再输入或选择该商户下已启用的代理账号；手动值必须匹配现有代理，未匹配时字段报错并保留待改输入。改变商户后清空原代理及继承配置。候选无匹配本身不直接报错，字段在既定校验时机判断必填和合法性。
- [ ] **AUTOCOMPLETE-S05**：共用视觉验收：仅核对本组件实际适用的颜色与组合状态；无此能力标为不适用，不给静态内容添加输入错误、半选或按下状态。
- [ ] **AUTOCOMPLETE-S06**：共用文字验收：正文14px/400、次级操作12px/400、标题600；检查实际子元素与弹出层。输入焦点只改自身边框，按钮和链接保留键盘焦点轮廓。
- [ ] **AUTOCOMPLETE-S07**：宽度联动验收：按输入框专题核对整项与边框口径、同组对齐、长内容、窄容器换行及状态不跳宽。

### 专题验收重点

当前样例核对快速改词、空建议、键盘接受候选及手动值保留。业务新增会员另核对手动值必须匹配所选商户的已启用代理、未匹配时就近报错和改变商户后清除旧代理。

## 当前示例模板

以下来自本专题的结构化示例，使用 Vue 2 模板语法。`v-model`、事件方法、数据列表等依赖 [components.js](../components.js)；完整样式文件及加载顺序见 [通用基线](FOUNDATIONS.md)。自定义组合标签的内部实现由下方依赖文件提供，不能仅复制标签作为完整组件。

```html
<label for="spec-autocomplete-value" class="audit-field-label">自动补全内容</label>
<el-autocomplete ref="autoDemo" id="spec-autocomplete-value" @keydown.native.esc.stop.prevent="$refs.autoDemo.close()" v-model="autoText" :fetch-suggestions="suggest" placeholder="请输入" clearable label="自动补全内容">
</el-autocomplete>
```

## 交付与使用边界

- 规范条款、示例代码与待验收场景分开理解；有示例不等于已覆盖所有样式、交互状态和使用场景。
- 业务接口、权限、时区、金额精度、数据规模等依赖应从实际项目读取，不使用演示值代替生产约定。
- 发生样式或文案变更时，同步专题数据、页面与 Markdown，避免规范和样例分离。

## 来源与关联

- 来源线索：本次补充。
- [打开本专题页面](../index.html#spec-autocomplete)
- [通用基线](FOUNDATIONS.md)
- [规范总索引](README.md)
- [结构化规范数据](../component-data.json)（记录 id：`autocomplete`）
- [原始历史样板](../original-20260621.html)
- [历史规范条目](../spec-notes.json)

## 本组件颜色状态表

| 状态 / 条件 | 统一规则 |
| --- | --- |
| 输入框 | 白底、正文深灰、边框灰；占位禁用灰；聚焦仅原边框主题蓝，不加外圈。 |
| 候选项 | 普通项正文深灰；悬停或键盘定位使用浅灰背景，实际选中才回填输入值，不增加复选框。 |
| 禁用与只读 | 禁用输入浅灰背景、禁用灰且不发起新查询；只读值正文深灰，可复制但不选择新建议。 |
| 校验与查询反馈 | 真实输入错误时边框及短提示错误红；远程加载用主题蓝图标，无匹配为空值灰，失败才显示错误红。 |

自动补全包含可编辑输入和候选项定位；聚焦输入不等于选择候选项，没有复选半选态。

[公共颜色与字体 token](../color-tokens.json) · [公共组件样式](../color-contract.css) · [系统字体合同（最后加载）](../font-contract.css)

## 业务落地场景

- [新增账号 · 新增会员 / 非总代 · 上级代理建议](../../showcase/index.html?example=member-form#create-account) · [场景文档](../../showcase/docs/create-account.md)

[竞品组件拆解](../../reference-review/竞品组件反推规范.html) · [业务场景分类](../../业务场景分类清单.md)