CommandPaletteGroup 组件契约¶
契约概览¶
| 区域 | 契约 |
|---|---|
| 公共契约 | 带有必填字符串 heading,以及 children、ref、xstyle、className、style 和根 DOM props 的 CommandPaletteGroup。 |
| 行为 | 一个由 heading 命名的命令结果 group,标题作为可视标签显示在它们上方。 |
| 最终用户影响 | 相关命令会出现在可见标题下方,屏幕阅读器用户移入该组时会听到该组的名称。 |
| 构建者影响 | 无。 |
| 兼容性/就绪状态 | 记录已发布的行为;无公开变更。 |
| 审查检查 | 拒绝未命名的组、被读取两次的标题,或与组目标合并的标题目标。 |
| 治理规则 | component:CommandPalette;architecture:public-component-api INV5;architecture:component-theming-surface。 |
此表是审查投影;以下正文为权威内容。
意图¶
CommandPaletteGroup 将相关命令结果归集到 CommandPalette 列表内的某个标题之下。消费者用法见 CommandPaletteGroup.doc.mjs。
兼容性与迁移¶
- 已发布的默认值保留:
yes - 兼容性类别:记录已发布行为;无公开变更
- 受控/非受控行为:不适用
- 迁移决策:无
消费者迁移说明应放在消费者文档和发布说明中。
当前状态影响¶
无。
所有权边界¶
拥有
- 组根节点、其 role 和名称,以及
command-palette-group目标(FR1、FR3)。 - 可视标题及其
command-palette-group-heading目标(FR2、FR3)。 - 根 ref、DOM props 和样式(FR4)。
不拥有 / 非目标
- 选项语义和激活——由
component:CommandPaletteItem拥有。 - 列表、搜索和键盘导航——由
component:CommandPalette和component:CommandPaletteList拥有。
公共概念¶
除消费者 props 外,没有组件局部概念。
行为与布局契约¶
| ID | 不变式 | 依据 |
|---|---|---|
| FR1 | 根节点具有 role="group",并通过 aria-label 由 heading 命名,除非调用者提供自己的 role 或 aria-label(FR4),并将其标题和子项按单列布局。 |
当前源码与测试 |
| FR2 | 标题在子项之前将 heading 作为辅助文本渲染,并对辅助技术隐藏,因此名称只被读取一次。 |
当前源码与测试 |
| FR3 | 根节点带有 command-palette-group,标题带有单独的 command-palette-group-heading 目标。 |
当前源码与测试 |
| FR4 | ref、DOM props、className、style 和 xstyle 到达根节点,调用者显式的 role 或 aria-label 也到达根节点(architecture:public-component-api INV5)。 |
当前源码 |
允许的变体¶
- AV1 — 内容。 标题文本和分组项可变。
- AV2 — 主题。 主题可分别对组和标题重新设置样式。
代表性状态¶
| 状态 | 必需不变式 | 允许的变体 |
|---|---|---|
| 分组结果 | 具有隐藏可视标题的命名组。 | 项。 |
转换与优先级顺序¶
- 无优先级规则。
性能与资源¶
- 无资源规则。
无障碍契约¶
- AR1 — 命名组。 组由
heading命名(FR1),除非调用者提供自己的aria-label(FR4)。 - AR2 — 单次读取。 可视标题对辅助技术隐藏,因此名称不会被重复(FR2)。
设计关系¶
| 解剖结构或状态 | 设计要求 | 呈现权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 组 | 将相关结果归集在一列中。 | 当前源码 | 辅助 | FR1, FR3 |
| 组标题 | 用辅助文本标记组。 | 当前源码 | 辅助 | FR2, FR3 |
由 component:CommandPalette 拥有的 CommandPalette 总体解剖图,将 Group 和 Group heading 部分映射到这些目标。
家族与系统关系¶
component:CommandPalette拥有总体解剖图和组合键盘模型;component:CommandPaletteItem拥有其中的选项。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变异或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1, AR1 | CommandPaletteGroup.test.tsx "has group role with aria-label" |
分组结果 | 缺少 role 或可访问名称将导致测试失败。 | audit:CommandPaletteGroup/accessibility |
| FR2, AR2 | CommandPaletteGroup.test.tsx 中的 heading、aria-hidden 和 decorative-heading 测试 |
分组结果 | 暴露给辅助技术的标题将导致测试失败。 | audit:CommandPaletteGroup/accessibility |
| FR3 | CommandPaletteGroup.test.tsx 的 heading-target 测试;themingTargets.test.ts |
分组结果 | 目标缺失或被合并将导致测试失败。 | audit:CommandPaletteGroup/theming |
| FR4 | 源码审查 | 调用方输入 | 差距:尚无测试覆盖 ref、DOM props、className、style、xstyle,或调用方传入的 role 或 aria-label。 |
audit:CommandPaletteGroup/api |
从源码读取,尚无针对性的测试:
- FR1:单列布局。
- FR4:根元素上的
ref、DOM props、className、style和xstyle。
决策日志¶
未记录任何组件局部的决策。
未决问题¶
无。
内容边界¶
本文件不重复使用者 prop 表格或示例,也不重复 CommandPalette 的搜索和键盘行为,而是链接到这些内容的所属文档。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx