跳转至

针对调用方渲染字段的 Combobox 系统规格

意图

用户从过滤后的列表中选择一项,同时焦点停留在产品自行渲染的文本字段中:聊天编辑器的 textarea、表情网格上方的搜索字段、结果会替换页面部分的设置搜索、匹配项在对话框中内联列出的“添加人员”字段。Astryx 为该字段提供与其自身 typeahead 输入相同的 combobox 语义和键盘模型。产品提供字段、行以及列表渲染的位置,并通过 hooks 组合该行为;每个此类字段的行为和播报方式都相同。

非目标

  • 字段的外壳和外观、行的外观以及列表渲染的位置(层或页面流)由调用方决定。
  • 搜索、过滤、防抖和异步数据源由调用方决定。
  • 在字段文本中查找查询,例如编辑器中触发字符之后的文本,由调用方决定。
  • 焦点位于按钮(Selector、MultiSelector)上或位于模态命令界面(CommandPalette)中的 combobox 保留各自的规格记录;本规格不为每种 combobox 设定一种交互模型。
  • 满足本契约的等效内部实现仍然有效。

需求

  • FR1 — 焦点保持在字段中。 移动活动选项 MUST NOT 将 DOM 焦点移出字段。字段 MUST 通过 aria-activedescendant 命名活动选项,该属性引用一个已渲染的选项;在没有选项处于活动状态时,字段 MUST 不携带 aria-activedescendant。
  • FR2 — 展开状态跟随列表。 当列表显示时,字段 MUST 暴露 aria-expanded="true" 和一个命名 listbox 的 aria-controls。当列表未显示时,字段 MUST 暴露 aria-expanded="false",并且 MUST NOT 引用未渲染的元素。textarea 字段(FR3)以相同方式暴露 aria-controls,且不携带 aria-expanded。
  • FR3 — 角色。 字段 MUST 暴露一个可访问名称。input 或 contenteditable 字段 MUST 暴露 role="combobox"。textarea 不接受显式角色,保持其隐式 textbox 角色,并且 MUST 暴露 aria-autocomplete="list"。列表 MUST 是一个已命名的 listbox,其行是 option,活动选项上带有 aria-selected="true"。listbox 可以渲染在文档中的任何位置,包括页面流中。不是选项的控件 MUST 渲染在 listbox 外部。
  • FR4 — 按键。 当列表显示时,ArrowDown 和 ArrowUp MUST 移动活动选项;在活动选项上按 Enter MUST 选择它,并且只有在那之后才阻止字段自身的 Enter;Escape MUST 隐藏列表,且在同一次按下中不关闭外层(family:overlay-dismissal)。当列表隐藏时,在单行 input 字段中按 ArrowDown MUST 在列表有选项时显示列表,如同 component:BaseTypeahead 对其自身输入所做的那样;在多行字段(textarea 或 contenteditable 元素)中,每个按键 MUST 原样到达字段及其周围环境,因此箭头键继续在行间移动光标。当列表显示时,Home 和 End 不在本需求范围内,直到 OQ2 被裁定;所有其他按键 MUST 原样到达字段。
  • FR5 — 输入法。 当输入法组合处于活动状态时,按键 MUST NOT 激活 combobox 命令,包括 Escape 的关闭行为(family:overlay-dismissal)。
  • FR6 — 指针。 将指针移到选项上 MUST 使其成为活动选项,但不移动 DOM 焦点。按下选项 MUST 选择它,并且字段 MUST 在整个按下过程中保持焦点。
  • FR7 — 结果数量。 当选项因新查询而改变时,选项的数量或没有选项这一情况 MUST 通过共享播报器以礼貌方式播报,而不是通过每个字段单独的 live region;这是通过字段自身的 useAnnounce({hasReplace: true}) 实例(spec:AST-086 FR9)完成的,以便较新的数量替换尚未播报的数量。
  • FR8 — Hooks 可作为 hooks 被发现。 实现本契约的每个公共 hook MUST 由 astryx hook <name> 和 astryx search 返回,并带有其参数、返回字段以及其满足的上述需求,以便产品无需先找到使用它的组件就能发现它。

平台支持

  • 支持的功能/引擎下限:仓库支持的引擎;无新增 CSS 或 DOM 特性。
  • 不支持的行为:无;屏幕阅读器在 contenteditable combobox 上对 aria-activedescendant 的播报不均衡,但 FR1 在那里仍然成立。
  • 浏览器证据:Chromium 可访问性树(accessibility tree)对 FR1–FR3 的证明,以及 FR4–FR6 的真实键盘和指针输入;屏幕阅读器的声明以 spec:AST-009 为界。

当前状态影响

  • component:BaseTypeahead 对其渲染的输入满足 AR1–AR5;本契约对调用方渲染的字段承担同样的义务。
  • component:ChatComposerInput 仅通过内部 hook 在其自身 contenteditable 字段内为触发器菜单暴露 combobox 语义。
  • useCombobox(从 @astryxdesign/core/Selector 导出)跟踪活动选项、打开和关闭,并处理 Selector 和 CommandPalette 的按键。对于调用方渲染的单行 input,在具有字符串 value 的任何选项类型上,其 getFieldProps、getListboxProps 和 getOptionProps 承载 FR1–FR6。它尚不支持多行字段(DEC-3),调用方通过自己的 useAnnounce({hasReplace: true}) 实例(FR7)播报结果数量,如 DEC-2 所述。
  • useMultiCombobox(从 @astryxdesign/core/MultiSelector 导出)对 MultiSelector 自身的控件执行相同操作。它接受 MultiSelector 的选项类型,将 ARIA 绑定留给调用方,并且不在输入法组合期间对按键进行保护。
  • useTypeahead 已在输入法组合期间忽略按键,useAnnounce 是 FR7 所指的共享播报器。
  • 两个 combobox hook 都附带 astryx hook 和 astryx search 返回的 hook 文档。useCombobox 文档列出了其满足的上述需求(FR8);useMultiCombobox 文档不涉及任何调用方渲染的字段,也未列出任何需求。

验证

契约 验证 代表性状态 变更或失败预期
FR1–FR3 依据 spec:AST-021 的 Chromium 无障碍树绑定;单元测试 input、textarea、contenteditable;层中的列表和文档流中的列表 焦点离开字段,陈旧的 aria-activedescendant 或 aria-controls 残留,或 axe 在字段上报告 aria-allowed-role 或 aria-allowed-attr
FR4, FR6 Chromium 中的真实键盘和指针输入 对话框中的方向键、Enter、Escape,悬停和按下;input 和 textarea 中隐藏列表上的 ArrowDown 某个按键或按下操作在错误的时机选中、关闭或使字段失焦
FR5 组合事件测试 通过 Enter 确认候选选择 组合期间按下 Enter 选中了某个选项
FR7 共享公告器测试 结果、无结果、新查询、同一帧内的两个查询 没有公告,或来自逐字段实时区域的公告,或过时计数与新计数一起被读出
FR8 针对核心导出 hooks 的 CLI hook 发现测试 DEC-2 中提及的每个公共 hook;从组件入口点导出的 hook combobox hook 在没有 hook 文档的情况下被导出,或 astryx hook <name> 声称其不存在

决策日志

DEC-1 — 调用方渲染字段和列表;Astryx 拥有语义和按键

Reference: spec:AST-075/DEC-1 Decider: cixzhang, 2026-10-15

已经渲染了撰写器、搜索字段或对话框字段的产品,无法在不替换该字段并将其列表移入层中的情况下采用 typeahead,因此它只能手工接线 combobox 模式,而每一份副本都在 FR1–FR7 所修复的细节上各不相同。将字段和列表留给调用方,由 Astryx 拥有语义,每个此类界面都满足同一个经过测试的契约。

已拒绝:要求产品的字段必须是 typeahead 自身的输入——textarea 或 contenteditable 撰写器无法充当该输入,并且文档流中的列表不是层。

DEC-2 — 契约以可组合的 hooks 形式交付,基于 useCombobox 构建

Reference: spec:AST-075/DEC-2 Decider: cixzhang, 2026-10-15

产品通过组合 hooks 在自有字段之上构建 combobox,方式与 Astryx 自身构建 combobox 相同:useCombobox 负责活动选项、展开状态和按键,从 Selector 的选项类型泛化为任意选项列表以及调用方渲染的字段;输入法守卫 useTypeahead 已经适用;useAnnounce 负责结果计数。Astryx 自身的 combobox 组合相同的 hooks,因此本规范覆盖的每个界面都由同一个经过测试的实现支撑,并且每个 hook 都有对应的 hook 文档(FR8)。泛化 useCombobox 使其已发布的选项和返回字段对现有调用方保持工作不变;新增输入均为可选补充。组件仍是常见场景的便捷路径;hooks 是所有其他字段的路径。

已拒绝:新组件,或接受调用方字段的 BaseTypeahead,后者将行为锁定在单个组件的标记内部。

DEC-3 — 隐藏列表仅在单行字段中因 ArrowDown 重新打开

Reference: spec:AST-075/DEC-3 Decider: cixzhang, 2026-10-15

在单行字段中,方向键没有光标移动的工作要做,因此 ArrowDown 会重新打开隐藏列表,这正是 Astryx 自有 typeahead 输入已有的键盘模型。在多行字段中,方向键在行间移动光标,这是正在撰写消息的人所需要的,因此在列表隐藏时方向键作用于字段。

已拒绝:列表隐藏时将每个按键都留给每个字段,这会让单行搜索字段除了输入之外没有键盘方式可以返回其列表。

未决问题

  • OQ2 — Home 和 End(human-design):在调用方渲染的字段中,要么继续移动光标,要么移动到第一个和最后一个选项,就像 component:BaseTypeahead 的 FR5 对其自身输入所做的那样。
  • OQ3 — 二维列表(human-api):选项网格(例如 emoji 选择器)是否属于本契约,还是属于单独的契约。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx