CommandPaletteList 组件契约¶
契约速览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | CommandPaletteList 带有 label、children、ref、xstyle、className、style 以及根 DOM props:CommandPalette 渲染的命名结果 listbox,或独立的结果列表。 |
| 行为 | 根是一个 listbox,名称来自调用方的 aria-label,否则来自 label,再否则使用翻译后的默认值(当前调用方的 aria-label 是 FR2 缺口);在 CommandPalette 内部,只有存在可选结果时它才是一个 listbox,并携带查询字段所控制的上下文列表 ID。 |
| 最终用户影响 | 屏幕阅读器用户可从查询字段到达命名结果列表;溢出的结果在列表内部滚动,而不是让命令面板变大。 |
| 构建方影响 | 构建方显式的 aria-label 本意是为列表命名;但目前组件的名称会替换它(FR2 缺口)。 |
| 兼容性/就绪状态 | 记录已发布行为;无公开变更。存在两个实现缺口,列在“当前状态影响”下;一个所有者问题仍然开放。 |
| 评审检查 | 拒绝第二个列表 ID 所有者、可被调用方替换的 listbox 角色、无法到达根的调用方 aria-label、原生或样式输入被丢弃,或将列表目标移出滚动根节点的情况。 |
| 治理规则 | architecture:public-component-api/INV5,INV6,INV8;architecture:component-theming-surface;WAI-ARIA 1.2 listbox。 |
本表是评审视图;下文正文为权威内容。
意图¶
CommandPaletteList 是命令面板的可滚动结果容器。在 CommandPalette 内部,它是查询字段所控制的 listbox。独立使用时,它在调用方提供的选项内容周围呈现一个命名的结果 listbox。
兼容性与迁移¶
- 已发布默认值保留:
yes - 兼容性类别:记录已发布行为;无公开变更
- 受控/非受控行为:不适用;列表不持有状态
- 迁移决策:无
使用方的迁移说明属于使用方文档和发布说明。
当前状态影响¶
- 独立列表没有键盘模型。 独立列表公开一个没有所属键盘模型的选项 listbox,因此键盘用户无法在其选项中移动;WAI-ARIA 1.2 将 listbox 的键盘交互交给其所有者(AR3、OQ1)。
- 列表会替换调用方的名称(FR2)。 使用方 props 在组件的可访问名称之前展开,因此构建方显式的
aria-label永远不能为列表命名,而architecture:public-component-apiINV5 允许这样做。
所有权边界¶
拥有
- listbox 根节点及其可访问名称:来自调用方的
aria-label,否则来自label,再否则使用翻译后的默认值(FR2);在 CommandPalette 内部,当不存在可选结果时,二者一并移除。 - 将 CommandPalette 上下文列表 ID 应用到根节点。
- 根节点上的原生透传、
ref和样式输入组合。 - 溢出子元素的块轴滚动,以及间距刻度 padding 和间隙。
不拥有 / 非目标
- 列表 ID 生成、查询字段聚焦、活动后代、方向键导航、悬停高亮、Enter 选择、搜索,以及结果与空状态之间的选择 — 由
component:CommandPalette所有。 - 聚合 List 结构条目及其
command-palette-list目标映射 — 由component:CommandPalette所有。 - 选项语义、状态和激活;分组语义和标题 — 由 CommandPaletteItem 和 CommandPaletteGroup 所有。
- 独立复合键盘模型;其方向仍为 OQ1。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 可访问名称 | 调用方 aria-label;调用方 label;翻译后的默认值 |
为结果 listbox 宣布的名称。 | 所有使用场景 | @astryx.commandPalette.list.label(英文为 "Commands") |
component:CommandPaletteList |
稳定 | 空的 label 会使 listbox 没有名称;调用方应提供真实名称。 |
| 列表标识 | 上下文列表 id;调用方 id |
CommandPalette 查询字段所引用的 DOM id。 | CommandPalette 内部;独立使用 | CommandPalette 内部使用上下文 id;独立使用时使用调用方 id |
component:CommandPalette |
稳定 | 在 CommandPalette 内部,调用方 id 会被上下文 id 替换。 |
行为与布局契约¶
| ID | 不变式 | 依据 |
|---|---|---|
| FR1 | 原生 props 和 ref 传递到 listbox 根节点,消费方的 className 和 style 与列表目标和基础样式合并。在 CommandPalette 内部,根节点 id 为上下文列表 id;独立使用时保留调用方的 id。 |
当前源代码和测试 |
| FR2 | 独立使用时,以及在 CommandPalette 内部且至少存在一个可选结果时,根节点暴露 role=listbox,调用方的 role 不会替换它:在 CommandPalette 内部是因为复合语义由组件拥有并替换透传,正如 component:CommandPaletteInput AR3 所记录;独立使用时则依据本记录自身的规则,由调用方显式提供的 aria-label 命名,否则由 label 命名,否则使用翻译后的默认值(architecture:public-component-api INV5)。实现缺口:组件的名称会替换调用方的 aria-label(当前状态影响)。否则适用 AR4。 |
当前源代码和测试 |
| FR3 | 在 CommandPalette 内部,查询字段的 aria-controls 引用 listbox id。 |
当前源代码和测试 |
| FR4 | 根节点将子元素按单列布局,使用间距尺度的内边距和间隔,在 flex 父容器中增长,将高度上限设为父容器高度,并让溢出的子元素在自身内部滚动。 | 当前源代码 |
允许的变化¶
- AV1 — 子元素。 条目、分组和空状态的数量、顺序和内容可以变化,而不会改变根节点,除非 AR4 另有说明。
- AV2 — 布局。 消费方的
xstyle、class 和 style 可以调整根节点,而不会替换其 role、id 或目标。
代表性状态¶
| 状态 | 必需的不变式 | 允许的变化 |
|---|---|---|
| 独立结果 | listbox 由调用方的 aria-label 命名,否则由 label 命名,否则使用翻译后的默认值(FR2 中关于 aria-label 的缺口)。 |
条目数量和分组。 |
| CommandPalette 内部 | 根节点 id 等于查询字段的 aria-controls 值。 |
结果数量和分组。 |
| 溢出结果 | 结果在列表内部滚动,而不是超出容器继续增长。 | 容器和条目高度。 |
| 空结果面板 | 在 CommandPalette 内部且没有可选择结果时,根元素没有 role 或名称。 | 空消息或等待中的消息。 |
转换与优先级顺序¶
- ORD1 — 根属性。 先使用消费者的原生 props,然后是组件自有的 id 和
listboxrole;除非调用者提供自己的aria-label,否则可访问名称会生效(FR2;目前它会替换调用者的aria-label)。 - ORD2 — 样式。 先是列表目标,然后是带有
xstyle的基础样式,接着是消费者的 class,最后是消费者的 style。
性能与资源¶
- PR1 — 渲染之外不执行额外工作。 列表不添加 state、effect、listener 或 observer;它仅在渲染期间读取 translation 和 CommandPalette context。
可访问性契约¶
- AR1 — 名称。 listbox 将调用者显式提供的
aria-label,否则使用label,再否则使用翻译后的默认值,作为其可访问名称(FR2 缺口)。 - AR2 — 关系。 在 CommandPalette 内部,查询字段通过其 id 控制 listbox;CommandPalette 在其 combobox 模型下拥有焦点和键盘导航。
- AR3 — 独立缺口。 独立列表暴露一个包含选项但没有所属键盘模型的 listbox(当前状态影响;OQ1)。
- AR4 — 空内容。 在 CommandPalette 内部,当不存在可选择结果时,根元素没有 role 也没有可访问名称,因此屏幕阅读器会将空消息或等待中的消息作为纯文本内容,并且不会遇到空的弹出框;WAI-ARIA 1.2 要求 listbox 拥有选项。独立列表仍然是 listbox,其选项由调用者提供。
设计关系¶
| 结构或状态 | 设计需求 | 呈现权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| List | 在一个可滚动列中呈现结果选项,并使用间距尺度的 padding 和 gap。 | 当前源码与公开文档 | 支持性 | FR1、FR4 |
族系与系统关系¶
component:CommandPalette负责 list-id 生成、键盘导航、悬停高亮、聚合结构以及command-palette-list目标映射;该组件应用 id 并绘制 List。architecture:public-component-api负责原生透传、样式组合和 refs。architecture:component-theming-surface负责目标限定和聚合 List 结构映射。architecture:component-test-sufficiency负责下方验证映射背后的证据规则。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1 | CommandPaletteList.test.tsx |
带有 ref、class 和 style 的独立根元素 | 断开 ref,或丢弃消费者的 class 或列表目标,会导致聚焦的 DOM 断言失败。 |
audit:CommandPaletteList/api |
| FR2、AR1、AR4 | CommandPaletteList.test.tsx |
默认 label 和调用者提供的 label;有结果和无结果的 CommandPalette | 移除 role 或名称,或在空的 CommandPalette 表面上保留它们,会导致 role 和名称断言失败。缺口:没有测试覆盖调用者提供的 role 或 aria-label。 |
audit:CommandPaletteList/a11y |
| FR3、AR2 | CommandPaletteList.test.tsx、CommandPalette.test.tsx |
内联 CommandPalette | 丢弃 context id 会破坏查询字段关系断言。 | audit:CommandPaletteList/a11y |
| FR4 | themingTargets.test.ts;已验证 RTL 不适用 |
独立列表 | 丢失目标会导致目标清单失败。 | audit:CommandPaletteList/theming |
| AR3 | 源码审查 | 独立列表 | 缺口:不存在可测试的独立键盘模型(OQ1)。 | audit:CommandPaletteList/accessibility |
| PR1 | 源码审查 | 所有状态 | 缺口:如果列表添加 state、effect、listener 或 observer,没有自动化检查会失败。 | audit:CommandPaletteList/behavior |
从源码中读取,目前尚无聚焦测试:
- FR4:单列布局、间距、高度上限和内部滚动。
- PR1:没有 state、Effect、listener 或 observer。
决策日志¶
未记录任何组件本地决策。
开放问题¶
- OQ1 — CommandPaletteList 应暴露哪种独立键盘契约?
(
human-api) 独立列表暴露一个包含选项的 listbox,但不拥有键盘模型。需要决定:是由公共复合属主提供该模型,还是独立组合承担不同角色,抑或独立使用仍保持仅指针的呈现。
内容边界¶
本文件不重复消费方 prop 表格/示例、实现步骤或家族/系统规则。它链接到各自的属主。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx