跳转至

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