针对调用方渲染字段的 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-086FR9)完成的,以便较新的数量替换尚未播报的数量。 - 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