键盘快捷键
以键帽或文本的形式显示执行某个命令的按键，使用用户所用键盘的修饰键符号和名称，朗读时则读出按键的名称。
- 类别
- 信息传达
- 令牌
comp.keyboard-shortcut- 层级
- 基础
- Web
tanrei-keyboard-shortcutschedule - SwiftUI
TanreiKeyboardShortcutradio_button_unchecked - Jetpack Compose
TanreiKeyboardShortcutradio_button_unchecked - Flutter
TanreiKeyboardShortcutradio_button_unchecked - React Native
KeyboardShortcutradio_button_unchecked
生成自 docs/status/status.json, specs/keyboard-shortcut.spec.json
键盘快捷键显示执行某个命令的按键：可以画成键帽，也可以画成命令名称旁边的纯文本，有 small 和 medium 两种尺寸。按键用中立的名称书写，例如 mod、shift、k，并按用户所用键盘的惯例绘制：Apple 的符号（⇧⌘K），或标准名称（Ctrl+Shift+K）。产品可以为某个区域指定惯例，也可以交给平台决定。由连续几个组合键构成的快捷键（Ctrl+K Ctrl+C）是一个序列。
键帽、由两个组合键构成的序列，以及纯文本形式，按你正在使用的键盘显示
它画出的按键只供眼睛看：辅助技术读到的是产品提供的 label，也就是用你自己的话说出的快捷键；没有 label 时，读到的是 aria-keyshortcuts 的写法（Meta+Shift+K）。Tanrei 没有任何语言的按键名称。它只显示按键，别无其他：它不接受焦点和输入，也不会让这些按键生效。按键由你的产品来绑定。
有三个组件通过各自的 shortcut 属性用它来绘制快捷键：菜单把它画在菜单项所在行的末尾，plain 工具提示把它画在文本之后，搜索把它作为搜索栏或触发器里的提示。在这些地方请使用这些属性，而不要放置你自己的元素：宿主组件会用自己的文本样式绘制按键，并把它们作为该控件的键盘快捷键提供给辅助技术。
keys 中每个字符串是一个组合键，按顺序依次按下。组合键是用 + 连接起来的按键名称，名称不区分大小写。
- 修饰键：
mod（在 Apple 平台上是 Command，在其他平台上是 Control）、ctrl、alt、shift。 - 有名称的按键：
enter、escape、tab、backspace、delete、space、arrow-up、arrow-down、arrow-left、arrow-right、home、end、page-up、page-down、caps-lock、f1到f24，以及表示 + 键的plus。 - 其他任何单个字符就是该字符对应的按键：
k、/、,。
在 Web 上，keys 属性（attribute）中的组合键用空格分隔（keys="mod+k mod+c"），而 JavaScript 属性（property）是一个数组。SwiftUI、Compose、Flutter 和 React Native 尚未实现这个组件。在实现之前，这些平台的菜单把快捷键写在菜单项的后置文本里，如菜单页面所示。
<!-- small 可以放在一行正文里，而不会把这一行撑高。 -->
<p>按 <tanrei-keyboard-shortcut keys="mod+k" label="Command 或 Control 加 K" size="small"></tanrei-keyboard-shortcut> 搜索。</p>
<!-- 先后按下的两个组合键。 -->
<tanrei-keyboard-shortcut keys="mod+k mod+c" label="Command 或 Control 加 K，然后 Command 或 Control 加 C"></tanrei-keyboard-shortcut>
<!-- 纯文本形式，用你的产品的语言朗读。 -->
<tanrei-keyboard-shortcut keys="mod+shift+k" variant="plain" label="Befehl Umschalt K"></tanrei-keyboard-shortcut>
<!-- 为某一种键盘书写的区域，与用户的平台无关。 -->
<section data-tanrei-keyboard-convention="standard">
<tanrei-keyboard-shortcut keys="mod+s" label="Control S"></tanrei-keyboard-shortcut>
</section>
<script type="module">
import '@tanrei/web/components/keyboard-shortcut';
// 这个元素只显示按键。按键要由你自己绑定，并在它们所属的控件上声明。
const shown = document.querySelector('tanrei-keyboard-shortcut');
searchButton.setAttribute('aria-keyshortcuts', shown.ariaKeyShortcuts); // "Meta+K" 或 "Control+K"
</script>import { KeyboardShortcut } from '@tanrei/react';
<p>按 <KeyboardShortcut keys={['mod+k']} label="Command 或 Control 加 K" size="small" /> 搜索。</p>
<KeyboardShortcut keys={['mod+k', 'mod+c']} label="Command 或 Control 加 K，然后 Command 或 Control 加 C" />
<KeyboardShortcut keys={['mod+shift+k']} variant="plain" label="Befehl Umschalt K" />
// 为某一种键盘书写的区域，与用户的平台无关。
<section data-tanrei-keyboard-convention="standard">
<KeyboardShortcut keys={['mod+s']} label="Control S" />
</section>同样的按键，分别按 Apple 键盘和标准键盘显示；句子中的 small；有名称的按键；禁用
按
构成
构成
keycap-apple 之上。| 部件 | 说明 |
|---|---|
1 container | One key's cap, in the keycap form: a small rounded square that widens with its legend, with a faint fill and, in the default system, no edge. A layer that wants keys with an edge, or with a deeper edge at the bottom, gives the edge its widths. The plain form draws no cap. |
2 label | A key's legend: a modifier's symbol or name (⌘, Ctrl), a named key's symbol or name (↩, Enter), or a character (K). It is text, drawn in the component's text style. |
3 separator · 可选 | The + between two keys of a chord where the keyboard's convention writes one (Ctrl+K). Apple platforms write none (⌘K). |
4 chord | The keys pressed together: the modifiers, in the convention's order, then one other key. |
5 sequence · 可选 | Chords pressed one after the other (Ctrl+K, then Ctrl+C), a wider gap apart. Most shortcuts are one chord. |
尺寸
尺寸
| 长度 | 令牌 | 值（px） |
|---|---|---|
container padding-inline | tanrei.comp.keyboard-shortcut.container.padding-inline.medium | 6 |
container height | tanrei.comp.keyboard-shortcut.container.height.medium | 24 |
keycap-apple 之上。属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
keys | strings | | The shortcut: one chord per string, pressed in order. A chord is key names joined by + ("mod+shift+k"). Modifiers: mod (Command on Apple platforms, Control elsewhere), ctrl, alt, shift. Named keys: enter, escape, tab, backspace, delete, space, arrow-up, arrow-down, arrow-left, arrow-right, home, end, page-up, page-down, caps-lock, f1 to f24, plus. Any other single character is that character's key. Names ignore case. |
variant | keycap | plain | "keycap" | How the keys are drawn: keycap puts each key in its own cap; plain writes the shortcut as a line of text, as a menu or a tooltip writes it. A design system may add values. |
size | small | medium | "medium" | Small (20 caps, 12 text) sits in a line of body text or a menu row without making it taller; medium (24 caps, 14 text) sits beside larger text or on its own. A design system may add values. |
convention | auto | apple | standard | "auto" | Whose keyboard the keys are written for. apple: the symbols of macOS, iOS, iPadOS and visionOS (⌃ ⌥ ⇧ ⌘, no separator). standard: the names of Windows, Linux, ChromeOS and Android (Ctrl, Alt, Shift, joined by +). auto: the convention an ancestor sets, else the one of the platform the app runs on. |
label | string | "" | What assistive technology reads in place of the drawn keys: the shortcut in the product's language ("Shift Command K", "Befehl Umschalt K"). The product's: Tanrei has no names for keys. Empty exposes the shortcut in the form of the platform's keyboard shortcut property (KBS-12), which is a standard's notation and not a sentence, and is reported (KBS-11). |
disabled | boolean | false | Fades the legends, for the shortcut of a command that is unavailable. The keys still show; the shortcut takes no input either way. |
状态
行为
以 EARS 形式写成的需求。每个平台的实现都按这些 ID 逐条测试。需求原文取自规格文件，原样以英文呈现。
| ID | 需求 |
|---|---|
KBS-1 | THE keyboard shortcut SHALL read keys as a sequence of chords pressed one after the other, each chord being the key names of one string joined by + and compared without case: mod, ctrl, alt and shift as modifiers, the named keys enter, escape, tab, backspace, delete, space, arrow-up, arrow-down, arrow-left, arrow-right, home, end, page-up, page-down, caps-lock, f1 to f24 and plus, and any other single character as that character's key. |
KBS-2 | WHILE convention is auto THE keyboard shortcut SHALL use the convention its nearest ancestor sets, and without one SHALL use apple on macOS, iOS, iPadOS and visionOS and standard on every other platform; it SHALL NOT choose the convention by the design system, because the keys follow the keyboard a person presses, not the look of the product. |
KBS-3 | WHILE the convention is apple THE keyboard shortcut SHALL write mod as ⌘, ctrl as ⌃, alt as ⌥ and shift as ⇧, in the order ⌃ ⌥ ⇧ ⌘ whatever order keys gives, followed by the chord's other key, with no separator; and SHALL write enter as ↩, escape as ⎋, tab as ⇥, backspace as ⌫, delete as ⌦, space as Space, the arrows as ↑ ↓ ← →, home as ↖, end as ↘, page-up as ⇞, page-down as ⇟, caps-lock as ⇪, a function key as F1 to F24 and plus as +. |
KBS-4 | WHILE the convention is standard THE keyboard shortcut SHALL write mod and ctrl as Ctrl, alt as Alt and shift as Shift, in the order Ctrl, Alt, Shift whatever order keys gives, followed by the chord's other key, each joined to the next by +; and SHALL write enter as Enter, escape as Esc, tab as Tab, backspace as Backspace, delete as Delete, space as Space, the arrows as ↑ ↓ ← →, home as Home, end as End, page-up as PgUp, page-down as PgDn, caps-lock as Caps Lock, a function key as F1 to F24 and plus as +. |
KBS-5 | THE keyboard shortcut SHALL write a letter key as its capital letter in both conventions and any other character key as given, and SHALL NOT add shift for a capital letter: shift is drawn only where keys names it, so mod+k and mod+K both draw ⌘K and mod+shift+k draws ⇧⌘K. |
KBS-6 | WHILE variant is keycap THE keyboard shortcut SHALL draw each key of a chord in its own cap: at least its size's container height tall and at least as wide as it is tall, its legend centered with its size's container padding on each side, corners of its size's container shape eased by sys.shape.corner-smoothing, filled with comp.keyboard-shortcut.container.color, and edged in comp.keyboard-shortcut.outline.color, comp.keyboard-shortcut.outline.width on its top and sides and comp.keyboard-shortcut.outline.bottom-width at its bottom, both inside the cap's size, a width of 0 (both, in the default system) drawing no edge on those sides, so that the cap is its fill alone; the legend SHALL be in its size's label typescale and comp.keyboard-shortcut.keycap.label.color, and two caps of one chord SHALL be its size's chord gap apart, or, where the convention has a separator, the separator in the legend's style and color with the chord gap on each side of it. |
KBS-7 | WHILE variant is plain THE keyboard shortcut SHALL write each chord as one run of text in its size's label typescale and comp.keyboard-shortcut.plain.label.color, the Apple symbols with no separator (⌥⌘⎋) and the standard names joined by + with no spaces (Ctrl+Alt+Delete), and SHALL draw no cap, fill or edge. |
KBS-8 | WHILE keys holds more than one chord THE keyboard shortcut SHALL draw the chords in order, its size's sequence gap apart, in both forms, and SHALL draw nothing else between them. |
KBS-9 | WHILE disabled is true THE keyboard shortcut SHALL draw its legends and separators from the disabled component tokens of its variant, SHALL keep its caps' fill and edges at rest, and SHALL NOT expose a disabled state of its own: it is not a control, and the command it belongs to exposes whether it is available. |
KBS-10 | THE keyboard shortcut SHALL hide its caps, legends and separators from assistive technology and SHALL expose in their place one text, read where the shortcut sits: label where it is not empty, which is the shortcut in the product's own words ("Shift Command K"), and otherwise the text KBS-11 gives. It SHALL NOT expose the symbols themselves, which a screen reader reads by the names of their characters. |
KBS-11 | WHILE label is empty THE keyboard shortcut SHALL have no names for keys of its own and SHALL NOT spell its keys out in the words of any language: it SHALL expose as its text the shortcut in the form of the platform's keyboard shortcut property (KBS-12) — Meta+Shift+K; Control+K Control+C — which is a standard's notation for keys, the same in every language, and in debug builds SHALL report once that the shortcut has no words. The legends it draws (KBS-3 to KBS-5) are the engravings of the two keyboard conventions, what the keys themselves carry, and are not words of Tanrei's; a keyboard engraved otherwise is a convention of its own, and a proposal of its own. |
KBS-12 | THE keyboard shortcut SHALL give a component that hosts it the shortcut in the form of the platform's keyboard shortcut property, which the web writes as aria-keyshortcuts does: each chord's modifiers then its key joined by +, with mod as Meta under apple and Control under standard, ctrl as Control, alt as Alt and shift as Shift, and the chords separated by spaces (Meta+Shift+K; Control+K Control+C). |
KBS-13 | WHERE a component draws the keyboard shortcut in one of its own parts THE keyboard shortcut SHALL draw its legends and separators in that part's text style and color from the host's tokens instead of its own label typescale and label color, SHALL keep its own caps, sizes and gaps, and SHALL expose nothing to assistive technology, because the host exposes the shortcut as its own (a menu item's keyboard shortcut). |
KBS-14 | THE keyboard shortcut SHALL NOT listen for, register or perform the keys it shows, SHALL NOT take focus, and SHALL NOT take pointer, touch or keyboard input of its own: it shows the keys, and the product makes them work. |
KBS-15 | THE keyboard shortcut SHALL lay itself out inline with the text around it, align the baseline of its legends with that text's baseline, never break a line inside a chord, and break a sequence only between chords; WHILE the text size is enlarged THE keyboard shortcut SHALL grow its caps with their legends, keeping container height as a minimum. |
KBS-16 | WHERE the layout direction is right-to-left THE keyboard shortcut SHALL keep the keys of a chord and the chords of a sequence in left-to-right order, isolated from the surrounding direction, as keyboards and the platforms' own menus write them. |
KBS-17 | WHERE the font of its text style has no glyph for a symbol it writes (⌘, ⌥, ⎋) THE keyboard shortcut SHALL draw that symbol from the platform's system font at the same size and baseline, and SHALL NOT draw a missing-glyph box. |
KBS-18 | IF keys is empty THE keyboard shortcut SHALL draw nothing and expose nothing; IF a chord is empty, holds no key other than modifiers, holds more than one key other than modifiers, names a key twice once the convention has written it (ctrl+mod under standard), or names an unknown key of more than one character THE keyboard shortcut SHALL draw what it can (each key once, an unknown name as given, in order) and in debug builds SHALL report the chord. |
KBS-19 | THE keyboard shortcut SHALL take its layout direction from where it is used — the direction of the nearest ancestor that sets one, and the platform's own where none does — and SHALL have no direction setting of its own; WHEN that direction changes while the keyboard shortcut is shown THE keyboard shortcut SHALL draw itself for the new direction at once, without a motion of its own, keeping what it shows and its state. |
各平台名称对照
对等并不意味着 API 完全相同。同一份契约，由各平台以自己的惯用方式表达。
| 规格 | Web | SwiftUI | Jetpack Compose | Flutter | React Native |
|---|---|---|---|---|---|
| 组件 | tanrei-keyboard-shortcut | TanreiKeyboardShortcut | TanreiKeyboardShortcut | TanreiKeyboardShortcut | KeyboardShortcut |
keys · 属性 | keys | keys | keys | keys | keys |
variant · 属性 | variant | variant | variant | variant | variant |
size · 属性 | size | size | size | size | size |
convention · 属性 | convention | convention | convention | convention | convention |
label · 属性 | label | label | contentDescription | semanticLabel | accessibilityLabel |
disabled · 属性 | disabled | disabled | enabled | enabled | disabled |
| 备注 | The keys attribute holds the chords separated by spaces (keys="mod+k mod+c"); the property is an array. The shadow root draws a <kbd> per chord holding a <kbd> per key, as HTML nests keys that are pressed together, all aria-hidden, beside one visually hidden text (KBS-10). Under auto the convention is the nearest ancestor's data-tanrei-keyboard-convention attribute (apple or standard), read when the element connects and when that attribute changes, else apple where navigator.userAgentData.platform or navigator.platform names macOS, iOS or iPadOS. The read-only ariaKeyShortcuts property is KBS-12's form, which the menu sets on its item. The small caps line up with text through vertical-align: baseline on an inline-flex host (KBS-15). Words: the element has no names for keys; without label its text for assistive technology is ariaKeyShortcuts. | TanreiKeyboardShortcut(_ keys: [String], …), with an initializer that takes SwiftUI's own KeyboardShortcut (its key and modifiers, .command as mod), so a product that already registers a shortcut shows the same one. auto reads the \.tanreiKeyboardConvention environment value, else apple. disabled follows SwiftUI's .disabled(_:) environment. The shortcut's text is the view's accessibilityLabel, on an element that combines its children. | TanreiKeyboardShortcut(keys: List<String>, …). Compose idiom is the inverse flag enabled. auto reads LocalTanreiKeyboardConvention, else standard (Android and ChromeOS write Ctrl). The shortcut's text is the contentDescription of semantics merged over the drawn keys, which are cleared. | TanreiKeyboardShortcut(keys: [...]), with a .fromActivator(SingleActivator) constructor so a product that binds Shortcuts shows the same keys (meta on Apple targets and control elsewhere read as mod). A widget that takes no press has no onPressed to null, so the flag is the inverse enabled, as in Compose. auto reads the TanreiKeyboardConvention inherited widget, else apple where defaultTargetPlatform is macOS or iOS. The drawn keys are excluded from semantics under one Semantics(label:). | <KeyboardShortcut keys={['mod+k']} />. auto reads the KeyboardConventionProvider context, else apple where Platform.OS is ios (and macos under React Native macOS). The drawn keys are one accessible element with accessibilityRole="text" and the shortcut's accessibilityLabel. |
令牌
| 令牌 | 引用 | 解析值（浅色） |
|---|---|---|
--tanrei-comp-keyboard-shortcut-chord-gap-medium | sys.space.space50 | 4px |
--tanrei-comp-keyboard-shortcut-chord-gap-small | sys.space.space25 | 2px |
--tanrei-comp-keyboard-shortcut-container-color | sys.color.surface-container-highest | |
--tanrei-comp-keyboard-shortcut-container-height-medium | — | 24px |
--tanrei-comp-keyboard-shortcut-container-height-small | — | 20px |
--tanrei-comp-keyboard-shortcut-container-padding-inline-medium | sys.space.space75 | 6px |
--tanrei-comp-keyboard-shortcut-container-padding-inline-small | sys.space.space50 | 4px |
--tanrei-comp-keyboard-shortcut-container-shape-medium | sys.shape.corner.small | 6px |
--tanrei-comp-keyboard-shortcut-container-shape-small | sys.shape.corner.extra-small | 3px |
--tanrei-comp-keyboard-shortcut-keycap-disabled-label-color | — | |
--tanrei-comp-keyboard-shortcut-keycap-label-color | sys.color.on-surface-variant | |
--tanrei-comp-keyboard-shortcut-outline-bottom-width | sys.space.space0 | 0px |
--tanrei-comp-keyboard-shortcut-outline-color | sys.color.outline-variant | |
--tanrei-comp-keyboard-shortcut-outline-width | sys.space.space0 | 0px |
--tanrei-comp-keyboard-shortcut-plain-disabled-label-color | — | |
--tanrei-comp-keyboard-shortcut-plain-label-color | sys.color.on-surface-variant | |
--tanrei-comp-keyboard-shortcut-sequence-gap-medium | sys.space.space150 | 12px |
--tanrei-comp-keyboard-shortcut-sequence-gap-small | sys.space.space100 | 8px |
--tanrei-comp-keyboard-shortcut-label-typescale-medium | sys.typescale.label | 500 14px/1.4286 |
--tanrei-comp-keyboard-shortcut-label-typescale-small | sys.typescale.label-small | 500 12px/1.3333 |
测试样例
作为基准的渲染结果。所有平台都以相同的 ID 为每个样例截取快照，以便相互比较。
variant: keycap (10)
keycap-apple
keys: ["mod+shift+k"] convention: apple label: Shift Command K keycap-standard
keys: ["mod+shift+k"] convention: standard label: Control Shift K small-apple
keys: ["mod+c"] size: small convention: apple label: Command C small-standard
keys: ["mod+c"] size: small convention: standard label: Control C reordered-apple
keys: ["mod+alt+escape"] convention: apple label: Option Command Escape named-keys-standard
keys: ["ctrl+alt+delete"] convention: standard label: Control Alt Delete single-key
keys: ["f2"] convention: standard label: F2 sequence-standard
keys: ["mod+k","mod+c"] convention: standard label: Control K, then Control C plus-key-standard
keys: ["mod+plus"] convention: standard label: Control Plus disabled-keycap
keys: ["mod+shift+k"] convention: apple label: Shift Command K disabled: true variant: plain (4)
plain-apple
keys: ["mod+shift+k"] variant: plain convention: apple label: Shift Command K plain-standard
keys: ["mod+shift+k"] variant: plain convention: standard label: Control Shift K sequence-plain-apple
keys: ["mod+k","mod+c"] variant: plain convention: apple label: Command K, then Command C disabled-plain
keys: ["mod+shift+k"] variant: plain convention: standard label: Control Shift K disabled: true 生成自 specs/keyboard-shortcut.spec.json, tokens/comp/keyboard-shortcut.tokens.json, design/tokens/
凡是你的产品要告诉用户哪些按键执行某个命令的地方，都使用键盘快捷键：帮助文字的句子里、快捷键列表里、空状态里、命令面板中命令名称的旁边。
在菜单项、plain 工具提示或搜索中，则改为设置该组件的 shortcut 属性。不要把键帽用于用户要输入的文本，例如一条命令或一个文件名：键帽表示要按下的一个键。
| 选项 | 绘制的内容 | 用途 |
|---|---|---|
keycap（默认） |
每个按键各有一个键帽；在标准惯例下，键帽之间有一个 +。 | 帮助和文档，按键本身就是主题的地方。 |
plain |
把快捷键写成一段连续的文本：⌥⌘⎋，或 Ctrl+Alt+Delete。没有键帽、填充和边线。 | 命令名称旁边，一排键帽会与名称争抢注意力的地方：这也是菜单的写法。 |
medium（默认） |
24 的键帽，14 的文字。 | 单独使用，或放在较大的文字旁边。 |
small |
20 的键帽，12 的文字。 | 一行正文或紧凑的行里，不会把这一行撑高。 |
在默认系统中，键帽是一块淡淡的填充，没有边线，键帽上的字符使用不显眼的文本颜色。设计系统可以给键帽加上边线（底边更粗），也可以添加变体和尺寸。
- 主修饰键写
mod，不要写ctrl：它在 Apple 键盘上是 Command，在其他键盘上是 Control。只有在每种键盘上都是 Control 的快捷键，才写ctrl。 - 顺序任意。 组件按键盘自身的顺序书写修饰键：Apple 是 ⌃ ⌥ ⇧ ⌘，标准名称是 Ctrl、Alt、Shift。
- 字母画成大写，并且不会添加 Shift：
mod+k和mod+K都画成 ⌘K。只有在你写明时才绘制 Shift。 - 每个组合键只有一个按键，修饰键除外。没有按键或有两个按键的组合键会尽量画出来，并会在调试构建中报告。
- 序列是若干个组合键：先
mod+k，再mod+c。它们之间隔开一段间距，中间不画任何东西。 - 有名称的按键也随键盘变化。
enter在 Apple 键盘上是 ↩，在标准键盘上是 Enter；escape是 ⎋ 或 Esc；backspace是 ⌫ 或 Backspace；page-down是 ⇟ 或 PgDn。方向键在两种键盘上都是 ↑ ↓ ← →。
convention 说明按键是按谁的键盘书写的。让它保持 auto：组件会使用祖先元素设置的惯例；没有设置时，使用平台的惯例——在 macOS、iOS、iPadOS 和 visionOS 上是 Apple 的符号，在其他所有地方是标准名称。
当你的产品比平台更了解情况时，为某个区域设置惯例：让用户自行选择的设置项、并排展示两种键盘的文档、连接到另一个系统的远程会话。在 Web 上，这就是任意祖先元素上的 data-tanrei-keyboard-convention 属性（apple 或 standard）；其中的菜单、工具提示和搜索也会遵循它。只有在例外情况下，才在单个快捷键上设置 convention。
惯例从不来自设计系统。按键遵循的是用户按下的键盘，而不是产品的外观。
- 显示真正有效的快捷键。在你的产品里绑定这些按键，并让两者保持一致。
- 给每个会被朗读的快捷键一个
label：用你的产品的话说出的快捷键（“Shift Command K”）。没有它，屏幕阅读器读到的是Meta+Shift+K这种写法。 - 在
convention="auto"下，画出的按键跟随用户的键盘，而你写下的label做不到。请像本页的示例那样，写一个在两种键盘上都成立的标签（“Command 或 Control，Shift，K”），或者在知道是哪种键盘之后再设置标签。 - 对当前不可用的命令，在该命令旁边给它的快捷键设置
disabled。按键仍然显示，只是变淡。 - 让快捷键保持在一行之内。组合键从不断开；序列可以在组合键之间换行。
- 不要自己书写这些符号（在文本里写 ⌘K）。它们在另一种键盘上是错的，而且屏幕阅读器可能会按字符名称来读一个符号。
- 不要让快捷键成为通向某个命令的唯一途径。它是一条捷径，对应的命令用指针和焦点也应当能到达。
- 不要在菜单项或工具提示里放置你自己的键盘快捷键元素。请使用宿主组件的
shortcut属性。 - 不要按品牌或主题来选择惯例。
- 角色
none- 标注
- The keyboard shortcut has no role of its own: it is text, read where it sits. Its symbols are hidden; what is read is label, the shortcut in the product's words ("Shift Command K"), or, without one, the notation of KBS-12 (Meta+Shift+K), so a screen reader never says "place of interest sign" for ⌘. Hosted in another component (a menu item), it is hidden entirely, and the host exposes the shortcut as its keyboard shortcut property.
- 最小目标
- 即使外观尺寸更小，点击区域也满足最小目标尺寸。 minimum 32px · pointer 44px · spacing 8px · touch 48px
键盘操作
| 按键 | 动作 |
|---|
备注
- Not interactive: it takes no focus and no input (KBS-14), so there is no target to size. minimumTarget holds trivially.
- Showing a shortcut does not make it work, and does not tell assistive technology that it works. A control that really answers the keys exposes that itself (aria-keyshortcuts on the web, the platform's keyboard shortcut on the others); a host such as the menu does it with the form KBS-12 gives.
- The keyboard shortcut has no names for keys in any language: a shortcut that should be read as words is given them in label. A table of key names a product sets once, and names taken from the platform, are not built.
- Contrast: the legend's color on the cap's fill is text on a surface and is held to 4.5:1 in the default system (7:1 in its high-contrast schemes); there it is sys.color.on-surface-variant on sys.color.surface-container-highest, 7.52:1 light and 6.09:1 dark at standard contrast. The cap's fill is decorative and is not held to a ratio against what is behind it: the legend alone carries the meaning, and a cap that cannot be told from its background is still a readable legend.
生成自 specs/keyboard-shortcut.spec.json, tokens/sys/measure.tokens.json
- 键帽、键帽上的字符和分隔符对辅助技术隐藏。在快捷键所在的位置，代替它们被读出的是一段文本：
label。这样 ⇧⌘K 读作“Shift Command K”，而从不读出符号的字符名称。没有label时，读出的是用aria-keyshortcuts的写法表示的快捷键——Meta+Shift+K，序列则是Control+K Control+C——这种写法出自标准，在每种语言里都一样；组件会在开发时报告一次。 - 组件没有按键的名称：它不会用任何语言拼写出修饰键、方向键或标点符号键。屏幕阅读器可能会跳过逗号这样单独的一个字符，这是要写
label的又一个理由。 - 它没有角色，不接受焦点和输入，也不是一个目标：它是文本。
- 在宿主组件（菜单项、plain 工具提示、搜索）之内，它自己不提供任何语义。宿主组件把快捷键作为其控件的键盘快捷键提供给辅助技术：在 Web 上是
aria-keyshortcuts。 disabled让键帽上的字符变淡，但不提供任何状态。快捷键所属的命令会说明它是否可用。- 在从右到左的布局中，按键保持从左到右的顺序，并与周围的文本在方向上隔离，这与键盘和各平台自己的菜单的写法一致。
- 它位于周围文本的基线上，并随文本放大而变大；键帽的高度是一个最小值。
- 产品字体中缺少的符号（⌘、⎋）会用同样大小的系统字体绘制，从不显示为表示缺字的方框。
- 在默认系统中，键帽上的字符满足文本的对比度要求。键帽的填充是装饰：含义只由字符承载。
- 调试构建会报告：空的组合键、只有修饰键的组合键、有两个按键的组合键、书写出来后同一个按键出现两次的情况（标准惯例下的
ctrl+mod）、未知的按键名称，以及未知的惯例。
已知的平台差距：
- SwiftUI、Compose、Flutter 和 React Native 尚未实现键盘快捷键。
- Web：如果一个禁用的快捷键单独放置，不在本身已表明为禁用的命令之内，自动化的对比度检查很可能会报告它：它的字符是变淡的，而这个元素自己不提供禁用状态。
- 让按键生效：组件只负责显示它们。
- 在按键所属的控件上，把它们声明为该控件的键盘快捷键。在 Web 上，用这个元素的只读属性
ariaKeyShortcuts来设置aria-keyshortcuts，前者给出的正是后者所需的格式。 - 凡是快捷键会被朗读的地方，都传入
label，也就是用你的产品的话说出的快捷键。Tanrei 不自带任何文字，也没有按键的名称。 - 让每个命令不用快捷键也能到达。