跳转至

Kbd 组件契约

契约概览

领域 契约
公共契约 无变更。Kbd 接受一个 keys 字符串和基础 props。
行为 Kbd 按 + 拆分 keys,为每个键绘制一个隐藏的键徽章,并使用平台感知字形,同时用朗读键名为整个快捷键命名一次。
最终用户影响 有视力的用户看到熟悉的键字形;屏幕阅读器用户将快捷键作为词语听到。这些词语在所有区域设置中均为英文。
构建者影响 无。
兼容性/就绪状态 记录已发布行为;无 API、默认值或 DOM 变更。kbd 目标位于非绘制快捷键组上;列在“当前状态影响”下。
评审检查 拒绝暴露给辅助技术的徽章、替换计算所得 role 或 aria-label 的调用方提供的值、为重复键生成重复的 React key,或忽略平台的 mod。
管理规则 architecture:component-theming-surface; architecture:internationalization INV1, INV1a; architecture:public-component-api INV5; spec:AST-102 FR4。

此表是评审投影;以下正文为权威依据。

意图

Kbd 将一个键盘快捷键呈现为一个或多个绘制的键徽章。它负责解析快捷键字符串、每个键的平台感知字形、快捷键的无障碍名称,以及 kbd 目标。消费者用法位于 Kbd.doc.mjs。

兼容性与迁移

  • 已发布的默认值保持不变:yes
  • 兼容性类别:记录已发布行为;无公共 prop、默认值、导出或 DOM 变更
  • 受控/非受控行为:不适用
  • 迁移决策:无

消费者迁移说明应包含在消费者文档和发布说明中。

所有权边界

拥有

  • 快捷键组、其当前 kbd 目标,以及根据所提供的快捷键字符串渲染出的已绘制键徽章。
  • 键解析、别名、平台感知字形和朗读名称。

不拥有 / 非目标

  • 与快捷键关联的操作或快捷键的发现方式——由产品调用点拥有。
  • 单个键徽章是否应获得公共目标——开放(OQ1)。
  • 监听或处理快捷键——不提供;Kbd 仅用于显示。
  • 组上的调用方 DOM props、ref、className、style 和 xstyle——已发布并记录在案,此处除 FR4 的 role 和 label 优先级外不作约定。

公共概念

概念 封闭值或状态 含义 按变体/方向/状态可用性 默认值 所有者 稳定性 无效值行为
键 以 + 分隔的键名;mod、命名键、别名、任何其他文本 要显示的快捷键。 始终可用。 必需 component:Kbd 稳定 未知键按输入原样以大写显示。

行为与布局契约

ID 不变量 依据
FR1 当前渲染包含一个快捷键组,并且为每个解析出的键段绘制一个键徽章。keys 按 + 拆分;每个段被修剪并转换为小写,esc 读作 escape,return 读作 enter,重复键会获得自己的徽章。每个徽章至少为 --spacing-5 大小,并且 MUST 随设定的文本尺寸增长,使其字形永不裁剪(spec:AST-102 FR4)。 当前源代码、文档和测试;spec:AST-102 FR4
FR2 快捷键组带有当前的 kbd 目标;单个按键徽章目前不带有公开目标(OQ1)。 当前源代码、文档和测试
FR3 每个徽章显示一个字形:在 Apple 平台上,mod 为 ⌘;在其他平台以及水合之前,为目录中 Control 的短文本(英语为 "Ctrl")。ctrl、alt 和 shift 遵循同一规则:在 Apple 平台上为 ⌃、⌥、⇧;在其他平台以及水合之前为目录中的短文本(英语为 "Ctrl"、"Alt"、"Shift")。meta 在 Apple 平台上显示 ⌘;在其他平台以及水合之前显示目录中 Windows 键的短文本(英语为 "Win")。朗读名称不变;escape 显示目录中 Escape 的短文本("Esc");enter、backspace、tab 和方向键显示其符号;plus 显示 "+";任何其他键显示为大写形式。 architecture:internationalization INV1a;当前源代码和测试
FR4 该组具有 role="img",并且 aria-label 由每个按键的朗读名称构建,这些名称取自 Astryx 目录(mod 在 Apple 平台上为 "Command",在其他平台以及水合之前为 "Control";未知按键以大写形式朗读),并通过目录中的快捷键消息成对连接(英语为 " + ",例如 "Command + K");每个徽章均为 aria-hidden。调用方的 role 和 aria-label 绝不会替换计算出的 role 和 aria-label;调用方的其他 ARIA 属性(如 aria-labelledby 和 aria-hidden)仍会传递到该组。 architecture:internationalization INV1、INV1a;当前源代码和测试

允许的变化

  • AV1 — 快捷键内容。 平台特定的按键文本以及调用方提供的快捷键组合可以变化,但这不会改变此处记录的由两部分组成的结构。

代表性状态

状态 必需不变量 允许的变化
单个按键 一个徽章;该名称是按键的朗读名称。 按键。
Mod + 按键 按平台显示 ⌘ 或 Ctrl;名称为 "Command" 或 "Control" + 按键。 平台。
重复按键 每次出现对应一个徽章。 —

转换与优先级顺序

  • ORD1 — 按键解析。 按 + 拆分 → 去除首尾空白 → 转为小写 → 别名 → 字形和朗读名称。

性能与资源

  • PR1 — 无监听器。 Kbd 不附加任何事件监听器。

无障碍契约

  • AR1 — 单一名称。 该快捷键是一张由按键朗读名称命名的图像,除非调用方的 aria-labelledby 为其命名;字形徽章处于隐藏状态(FR4)。
  • AR2 — 本地化。 可见的短文本和朗读名称通过目录跟随提供方的区域设置(FR3、FR4)。

设计关系

结构或状态 设计要求 表现依据 层级角色 组件契约
快捷键 组合完整的快捷键并承载其可访问名称。 当前源代码和公开文档 辅助 FR1、FR2、FR4
按键徽章 为所提供组合中的每个按键绘制一个可见徽章。 当前源代码和公开文档 主要 FR1–FR3

主题结构

{
  "Shortcut": {"target": "kbd"},
  "Key badge": {
    "none": {
      "reason": "unsettled: No current public target reaches this part"
    }
  }
}

none 处置记录了当前的可达性,而目标对外暴露仍未确定。它并不决定按键徽章应继续保持没有公开目标。

家族与系统关系

  • architecture:component-theming-surface 负责结构资格验证、目标映射,以及事实可达性与预期公开主题化 API 之间的差异。
  • architecture:internationalization 负责基于目录的 Astryx 文本;FR3 和 FR4 的短文本、朗读名称和连接消息均取自该处。

验证映射

合约 验证 代表性状态 变更或失败预期 审计章节
FR1 Kbd.test.tsx 单键、多键、空白、别名和重复按键用例 单个和多个按键;带空格和混合大小写的输入;重复别名 缺少或多余的徽标、未修剪或大小写错误的按键,或丢失的别名都会导致测试失败。KbdAudit.a11y.chromium.spec.ts 的更大文本用例以固定文本大小测量每个徽标是否增长超过 --spacing-5。 audit:Kbd/anatomy
FR2 Kbd.test.tsx 主题类用例 根目标和子徽标 缺少根 kbd 目标会导致测试失败。证据缺口:没有测试断言徽标不携带目标。 audit:Kbd/theming
FR3, FR4 Kbd.test.tsx 字形、平台、可访问名称、覆盖和本地化用例(“本地化可见按键文本和朗读的快捷键组合”) Mac 和非 Mac;特殊键和未知键 mod、ctrl、alt、shift、enter、escape、plus 或未知键的字形错误、暴露的徽标、调用方的 role 或 aria-label 替换了计算出的角色/标签,或文本跳过目录,均会导致测试失败。证据缺口:没有测试断言 backspace、tab 或方向键字形,也没有断言水合前的 “Ctrl” 文本和 “Control” 名称。 audit:Kbd/accessibility
FR3 修饰键 Kbd.test.tsx 修饰键用例:Apple 符号、Windows 和 Linux 目录文本、在 Mac 上的服务器渲染、本地化的短文本;使用 Windows 用户代理的真实浏览器渲染 Apple(MacIntel);非 Apple(Win32、Linux x86_64);水合前 在非 Apple 平台或水合前,ctrl、alt 或 shift 显示符号;在非 Apple 平台或水合前,meta 显示目录中 Windows 键文本以外的任何内容;朗读名称发生变化;或修饰键文本跳过目录——这些都会导致测试失败。 audit:Kbd/accessibility
主题化解剖结构映射 scripts/check-knowledge.mjs 规范解剖结构和目标 缺失、多余、带前缀、过期或由别名支持的映射都会导致仓库验证失败。 audit:Kbd/theming
ORD1, PR1, AR1, AR2 ORD1 由 FR1 和 FR3 行覆盖,AR1 和 AR2 由 FR3、FR4 行覆盖。证据缺口:没有测试断言不存在监听器。 — — audit:Kbd/behavior

当前状态影响

  • 目标位于非绘制组(FR2)。 kbd 目标位于快捷键组上,该组本身不绘制任何内容,这与 architecture:component-theming-surface INV4 相悖;按键徽标负责绘制。在 OQ1 决定之前,它保持按 architecture:public-component-api INV21a 发布时的原样。

决策日志

无组件级决策。

开放问题

  • OQ1 — 每个 Key 徽标是否应获得一个稳定的公共主题化目标?(human-api)当前缺少可达性并不能决定答案。

内容边界

本文件不重复消费端属性表/示例、当前审计结果、实现步骤或系统规则。它链接到这些内容的拥有者。

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