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-surfaceINV4 相悖;按键徽标负责绘制。在 OQ1 决定之前,它保持按architecture:public-component-apiINV21a 发布时的原样。
决策日志¶
无组件级决策。
开放问题¶
- OQ1 — 每个 Key 徽标是否应获得一个稳定的公共主题化目标?(
human-api)当前缺少可达性并不能决定答案。
内容边界¶
本文件不重复消费端属性表/示例、当前审计结果、实现步骤或系统规则。它链接到这些内容的拥有者。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx