Skip to content

Tag Input 标签输入 ​

Tag Input 标签输入管理一个可增删的值集合,并协调文本编辑、候选选择、去重与令牌级删除。它适合标签数量有限且每项身份清楚的任务,不适合用来编辑任意长列表。

能力边界与前置知识 ​

Tag Input 标签输入负责把用户输入转换为可校验、可提交、可恢复的数据。它不能替代服务端授权、业务校验、唯一约束、恶意内容处理或并发控制。

前置知识:

  • 能定义字段或文档的数据类型、必填、范围和业务不变量;
  • 能区分原始输入、显示值、规范化值和稳定对象 ID;
  • 了解表单标签、可访问名称、焦点顺序和状态消息;
  • 能观察请求、响应、对象版本和权威写入结果。

组成部分 ​

  • token:已选择值、稳定 ID、显示文本和移除动作。
  • 编辑输入:创建或检索下一项。
  • 候选列表:排除已选、表达禁用和无结果。
  • 词表规则:自由标签、受控标签或混合模式。
  • 集合约束:去重、上限、规范化和是否有顺序。

每个令牌要区分稳定 ID、显示标签、来源和有效状态,输入框只保存尚未提交的查询。去重、数量上限和新建权限基于规范化身份判断,不能仅比较屏幕文字。

输入数据生命周期 ​

mermaid
flowchart LR
    R["原始输入"] --> C["客户端可快速检查"]
    C --> N["规范化或对象选择"]
    N --> D["本地草稿"]
    D --> S["服务端授权与业务校验"]
    S --> W["受控写入"]
    W --> E["结果、版本与审计"]
    S --> F["字段、全局、冲突或临时错误"]
    F --> D

原始输入 ​

保留正在输入的查询和已生成令牌的原始标签。逗号、Enter 或失焦是否完成一个标签必须显式定义,输入法组合期间的逗号和 Enter 不能提前创建令牌。

规范化值 ​

已有标签按标签 ID 去重;允许自由创建时,再按产品声明的大小写、Unicode 和空白规则生成规范键。C++、c++ 是否同一标签属于业务规则,不能由组件擅自决定。

草稿 ​

草稿保存有序令牌 ID、临时新标签和未完成查询。恢复时批量验证标签是否仍存在、是否被合并以及用户是否仍可使用;被合并标签应迁移到权威 ID 并告知用户。

权威结果 ​

提交后服务端返回最终标签 ID 集合和对象版本。新建标签可能被服务端合并到已有标签,界面必须采用返回 ID 和标签,而不是保留客户端临时令牌。

专属行为 ​

  • Backspace 删除前一个 token 前要有可预测焦点与公告。
  • 粘贴多个值时先解析预览,再明确无效、重复和超限项。
  • 大小写与空格规范化不能改变有意义内容。
  • 移除后播报标签名称和剩余数量。
  • 自由创建需要权限、审核或同义词治理。

设计决策 ​

  1. 标签是否用于展示、检索、权限还是自动化规则。
  2. 允许自由创建会产生多少同义词与垃圾值。
  3. 数量上限是界面建议还是服务端不变量。
  4. 排序是否影响语义和提交。
  5. 批量粘贴是否需要确认和逐项错误。

验收要覆盖自由创建开关、最大数量、同名标签、合并标签、Backspace 删除和输入法组合,证明集合身份和键盘操作不会相互混淆。

状态模型 ​

状态进入条件界面责任退出条件
Tag Input 标签输入未触碰还没有本次交互显示标签、规则和合理默认值用户输入或选择
编辑中原始值正在变化保持焦点和输入法行为完成输入、取消或提交
本地无效可确定格式或范围错误就近说明修正方式输入变为有效
可提交本地条件满足主操作可用,不承诺业务成功提交、继续编辑
提交中请求或上传进行防重复意图,保留输入成功、失败、超时、取消
令牌被拒绝标签已停用、数量超限或无新建权限标记具体令牌,保留其他有效令牌和查询移除、替换或申请权限
冲突基础对象版本变化比较、刷新或合并新版本确认
集合结果未知保存请求超时冻结再次提交,读取对象当前标签集合与版本对账后继续编辑或完成
成功权威结果完成显示结果和下一步后续操作

状态不能只存在于颜色。错误、等待、选中、进度和保存结果应有程序化表达。

工程状态示例 ​

json
{
  "query": "access",
  "selectedIds": [
    "tag-a11y"
  ],
  "maxItems": 8,
  "allowCreate": false
}

示例字段不是通用接口标准。项目应按Tag Input 标签输入的真实值类型定义 schema,并明确缺失值、无效值、服务端错误、版本和恢复语义。

校验顺序 ​

  1. Tag Input 标签输入输入前说明格式、单位、范围和不可接受内容。
  2. 输入期间只做不会打断输入法的安全检查。
  3. 完成输入或离开字段后给出可修正反馈。
  4. 提交时客户端汇总当前已知错误。
  5. 服务端重新执行格式、授权、业务和并发校验。
  6. 返回字段错误与全局错误的稳定代码和安全文案。
  7. 界面保留合法输入,把焦点移到合理错误入口。
  8. 修正后只清除已经解决的错误。
  9. 成功后从权威响应更新对象和版本。

客户端限制可以减少错误,不能防止直接请求、旧客户端或恶意输入。

案例一:Issue 从受控词表选择标签 ​

固定输入 ​

  • 使用合成账户与合成业务数据;
  • 正常网络 80 ms,另注入 2 秒延迟和一次 503;
  • 打开时对象版本为 17,提交前另一个会话更新为 18;
  • 覆盖空值、无效值、长值、重复值和权限撤销;
  • 记录可见结果、焦点、请求、响应和权威对象。

设计与实现 ​

  1. Backspace 删除前一个 token 前要有可预测焦点与公告。
  2. 粘贴多个值时先解析预览,再明确无效、重复和超限项。
  3. 大小写与空格规范化不能改变有意义内容。
  4. 移除后播报标签名称和剩余数量。
  5. 自由创建需要权限、审核或同义词治理。

服务端把临时标签 frontend-new 解析为既有标签 tag-81 后,组件替换临时 ID、更新显示名并保留原顺序;重复标签只出现一次。

验证 ​

  • 鼠标、键盘、触屏和屏幕阅读器都能完成;
  • 输入法组合期间不误提交;
  • 本地错误与服务端错误均能修正;
  • 请求失败和冲突不清空合法工作;
  • 重复触发只产生一个逻辑副作用;
  • 最终显示与权威数据对账一致。

失败分支 ​

输入法组合阶段误把半成品拆成标签

修复后重复相同输入和时序,确认界面状态、服务端副作用和审计记录同时正确。

案例二:知识库为文章添加可创建主题词 ​

固定输入 ​

  • 360 CSS px 视口与 200% 文本缩放;
  • 系统大字体、中文输入法和仅键盘操作;
  • 网络先离线,恢复后响应超时;
  • 会话在未提交工作存在时到期;
  • 数据包含同名对象、过期引用和被删除目标。

设计过程 ​

  1. Issue 标签只从受控词表选择,普通成员不能创建新标签。
  2. 候选排除已选 ID,并显示禁用和无结果原因。
  3. 粘贴多个标签时先解析预览,逐项显示重复与超限。
  4. Backspace 先把焦点移到前一个 token,再确认删除行为。
  5. 移除后播报标签名称与剩余数量。
  6. 服务端按 ID 去重并执行数量上限。

窄屏令牌在输入框前自然换行,删除按钮不覆盖标签文本;令牌过多时提供计数和可滚动区域,但 Tab 顺序仍按 DOM 集合顺序。离线新建令牌明确标为未验证。

验证 ​

  • 关闭和恢复网络后不重复写入;
  • 刷新后按声明的草稿策略恢复;
  • 会话到期不把敏感值写入不安全存储;
  • 失效引用有替换、清除或返回路径;
  • 读屏能获知结果而无需焦点被强制移动;
  • 长文本不会遮挡唯一保存或取消动作。

失败分支 ​

会话在Tag Input 标签输入进行中到期。界面必须暂停后续写入,保留允许保留的非敏感工作,重新认证后再次校验权限与版本;不能直接重放旧请求。

认证恢复后批量校验所有令牌:有效标签继续保留,停用或受限标签逐项标错,未完成查询保持文本状态;不能因为一个标签失败而清空整个集合。

无障碍实现 ​

名称与说明 ​

  • Tag Input 标签输入的可见标签进入可访问名称。
  • 帮助文本与错误通过程序化关系关联。
  • placeholder 不替代持久可见标签。
  • 必填、单位、格式和限制不只靠颜色或图标。
  • 复合输入使用与真实行为匹配的 APG 模式。

键盘与输入法 ​

  • Tag Input 标签输入的 Tab 顺序跟随 DOM 与视觉阅读顺序。
  • Enter、Space、方向键和 Escape 只按控件语义接管。
  • 输入法 composition 期间不把中间文本当成完成值。
  • 粘贴、语音输入和浏览器自动填充不被无理由阻止。
  • 临时弹层关闭后焦点回到触发点或下一逻辑位置。
  • 错误修正后焦点不被异步结果抢走。

重排 ​

在 320 CSS px 等效宽度和 200% 缩放下,令牌允许多行换行,文本和删除按钮都保持可辨认;输入框至少占一整行,错误说明紧跟对应令牌或集合。

安全、性能与一致性 ​

安全 ​

  • 所有输入均视为不可信;
  • 服务端重新授权和校验;
  • 富文本与文件按输出上下文净化或隔离;
  • 错误不泄露内部异常、受限对象或敏感路径;
  • 日志不默认记录正文、文件内容、密码或令牌。

性能 ​

  • 取消失效查询并丢弃乱序响应;
  • 长列表、长文档和大文件使用适合的分页、分片或后台任务;
  • 加载优化不改变可访问树的完整语义;
  • 缓存键包含租户、角色、语言和会改变结果的筛选条件;
  • 性能预算覆盖输入响应、候选出现、提交和恢复。

一致性 ​

  • 写请求带幂等或逻辑意图标识;
  • 对现有对象修改带期望版本;
  • 超时先查询结果而不是盲目重试;
  • 部分成功返回逐项稳定 ID 与结果;
  • 草稿与正式提交使用不同状态和权限;
  • 客户端缓存不能静默覆盖服务端新版本。

调试与观测 ​

  1. 固定Tag Input 标签输入的输入、角色、对象版本、网络、语言和视口。
  2. 检查原始值、显示值、选择 ID、错误和焦点。
  3. 检查请求参数、取消、响应顺序和业务错误码。
  4. 检查服务端授权、规范化、版本和权威写入。
  5. 注入超时、权限撤销、并发和页面刷新。
  6. 用键盘、读屏、输入法和窄屏重复。

观测指标:

  • 有效开始、提交、成功、失败、取消和恢复;
  • 首次错误类型与最终修正率;
  • 输入丢失和重复副作用;
  • 候选或校验响应延迟;
  • 键盘阻断、焦点丢失和错误未关联;
  • 按平台、语言、角色和数据量分群的完成时间。

综合练习 ​

为Tag Input 标签输入完成可运行原型和服务端模拟。覆盖正常、无效、等待、失败、权限、过期、冲突、取消和未知结果。

验收:

  • Tag Input 标签输入的数据类型、显示值、提交值和稳定 ID 边界明确;
  • 两个案例有固定输入、处理、结果、验证和失败;
  • 客户端与服务端校验责任分开;
  • 失败后保留允许保留的工作;
  • 键盘、屏幕阅读器和输入法完成任务;
  • 弱网、窄屏和长文本不隐藏恢复;
  • 日志与分析不收集不必要敏感内容;
  • 权威数据与界面结果可以对账。

来源 ​

从前端走向软件产品工程的长期路线图。