اختصار لوحة المفاتيح
يعرض المفاتيح التي تنفّذ أمرًا، في صورة مفاتيح أو نص، برموز المفاتيح المعدِّلة وأسمائها في لوحة المفاتيح التي يستخدمها الشخص، وينطقها بأسمائها.
- الفئة
- التواصل
- الرموز
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
يعرض اختصار لوحة المفاتيح المفاتيح التي تنفّذ أمرًا: مرسومة أغطية مفاتيح (keycaps)، أو نصًّا بسيطًا بجانب اسم الأمر، بحجم صغير أو متوسط. تُكتب المفاتيح بأسماء محايدة، هي mod و shift و k، وتُرسم بعُرف لوحة المفاتيح التي يستخدمها الشخص: رموز Apple (⇧⌘K) أو الأسماء القياسية (Ctrl+Shift+K). يستطيع المنتج أن يعيّن العُرف لمنطقة، أو أن يتركه للمنصة. والاختصار المكوَّن من عدة تآلفات مفاتيح (chords) متتالية (Ctrl+K Ctrl+C) تسلسل واحد.
أغطية مفاتيح، وتسلسل من تآلفين، والهيئة البسيطة، للوحة المفاتيح التي تستخدمها
مفاتيحه مرسومة للنظر فقط: التقنيات المساعدة تقرأ القيمة label التي يعطيها المنتج، وهي الاختصار بكلماتك أنت، ومن دونها تقرأ صيغة aria-keyshortcuts (Meta+Shift+K). وليست عند Tanrei أسماء للمفاتيح بأي لغة. وهو يعرض المفاتيح ولا شيء غير ذلك: لا يأخذ تركيزًا ولا إدخالًا، ولا يجعل المفاتيح تعمل. منتجك هو الذي يربطها.
ثلاثة مكوّنات ترسم به اختصارًا، من خاصية shortcut خاصة بكل منها: قائمة الخيارات في نهاية صف العنصر، والتلميح البسيط بعد نصه، والبحث تلميحًا في شريطه أو في مُشغِّله. استخدم تلك الخصائص هناك، لا عنصرًا من عندك: المكوّن المضيف يرسم المفاتيح بنمط نصه هو ويعرضها على أنها اختصار لوحة المفاتيح لعنصر التحكم.
تحمل الخاصية keys تآلفًا واحدًا في كل سلسلة نصية، تُضغط بالترتيب. التآلف أسماء مفاتيح موصولة بالعلامة +، والأسماء لا تفرّق بين الأحرف الكبيرة والصغيرة.
- المفاتيح المعدِّلة:
mod(وهو Command على منصات Apple و 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و/و,.
على الويب تحمل خاصية HTML (attribute) المسمّاة keys التآلفات مفصولة بمسافات (keys="mod+k mod+c")، أما خاصية العنصر في JavaScript فمصفوفة. لم تنفّذ 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 وللوحة قياسية؛ الحجم الصغير داخل جملة؛ مفاتيح مسمّاة؛ معطَّل
اضغط
البنية
البنية
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. يُختبر تنفيذ كل منصة مقابل هذه المعرّفات. يُعرض نص المتطلبات كما ورد في ملف المواصفة، بالإنجليزية.
| المعرّف | المتطلب |
|---|---|
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. |
مطابقة الأسماء بين المنصات
التكافؤ لا يعني واجهات برمجية متطابقة. تعبّر كل منصة عن العقد نفسه بأسلوبها.
| المواصفة | 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 |
نماذج الاختبار
عروض مرجعية. تلتقط كل المنصات لقطة لكل نموذج بالمعرّف نفسه حتى يمكن مقارنة النتائج.
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/
استخدم اختصار لوحة المفاتيح حيثما أخبر منتجك الشخص بالمفاتيح التي تنفّذ أمرًا: في جملة مساعدة، في قائمة اختصارات، في حالة فارغة، بجانب اسم أمر في لوحة أوامر.
في عنصر قائمة خيارات أو تلميح بسيط أو بحث، أعطِ ذلك المكوّن خاصيته shortcut بدلًا من ذلك. ولا تستخدم غطاء المفتاح لنص يكتبه الشخص، كأمر أو اسم ملف: الغطاء يعني مفتاحًا يُضغط.
| الاختيار | ما يرسمه | يُستخدم لـ |
|---|---|---|
keycap (الافتراضي) |
كل مفتاح في غطائه، مع علامة + بين الأغطية في العُرف القياسي. | المساعدة والتوثيق، حيث المفاتيح هي الموضوع. |
plain |
الاختصار في صورة نص متصل واحد: ⌥⌘⎋ أو Ctrl+Alt+Delete. بلا غطاء ولا تعبئة ولا حافة. |
بجانب اسم أمر، حيث ينافسه صف من الأغطية: كما تكتبه قائمة الخيارات. |
medium (الافتراضي) |
أغطية بمقاس 24 مع نص بمقاس 14. | وحده، أو بجانب نص أكبر. |
small |
أغطية بمقاس 20 مع نص بمقاس 12. | في سطر من نص المتن أو في صف كثيف، من دون أن يزيد ارتفاع السطر. |
في النظام الافتراضي الغطاء تعبئة باهتة بلا حافة، والمكتوب عليه بلون النص الهادئ. يستطيع نظام التصميم أن يعطي الأغطية حافة، قاعها أثقل، وأن يضيف طُرُزًا (variants) وأحجامًا.
- اكتب
modللمفتاح المعدِّل الرئيسي، لاctrl: هو Command على لوحة مفاتيح Apple و Control في غيرها. ولا تكتبctrlإلا لاختصار يكون Control على كل لوحة مفاتيح. - بأي ترتيب. يكتب المكوّن المفاتيح المعدِّلة بترتيب لوحة المفاتيح نفسها:
⌃ ⌥ ⇧ ⌘في لوحات Apple، و Ctrl ثم Alt ثم Shift في الأسماء القياسية. - الحرف يُرسم بصورته الكبيرة، ولا يضيف Shift:
mod+kوmod+Kكلاهما يرسم⌘K. ولا يُرسم Shift إلا حيث تسمّيه. - مفتاح واحد في كل تآلف، عدا مفاتيحه المعدِّلة. التآلف الذي بلا مفتاح، أو بمفتاحين، يُرسم على قدر المستطاع، وتبلّغ عنه بنيات التنقيح (debug).
- التسلسل عدة تآلفات:
mod+kثمmod+c. تُرسم وبينها فجوة، ولا شيء بينها. - المفاتيح المسمّاة تتبع لوحة المفاتيح أيضًا. المفتاح
enterهو↩على لوحة مفاتيح Apple و Enter على اللوحة القياسية؛ وescapeهو⎋أو Esc؛ وbackspaceهو⌫أو Backspace؛ وpage-downهو⇟أو PgDn. والأسهم↑ ↓ ← →في الاثنتين.
تقول الخاصية convention للوحة مفاتيح مَن كُتبت المفاتيح. اتركها على auto: فيستخدم المكوّن العُرف الذي يعيّنه عنصر سلف، وفي غيابه عُرف المنصة: عُرف Apple على macOS و iOS و iPadOS و visionOS، والأسماء القياسية في كل مكان آخر.
عيِّنه لمنطقة حين يعرف منتجك أكثر من المنصة: إعداد يتيح للشخص أن يختار، توثيق يعرض اللوحتين جنبًا إلى جنب، جلسة عن بُعد إلى نظام آخر. على الويب هو خاصية HTML 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. - ليس له دور، ولا يأخذ تركيزًا ولا إدخالًا، وليس هدفًا: هو نص.
- داخل مكوّن مضيف (عنصر قائمة خيارات، تلميح بسيط، بحث) لا يعرض هو شيئًا. المكوّن المضيف يعرض الاختصار على أنه اختصار لوحة المفاتيح لعنصر تحكمه:
aria-keyshortcutsعلى الويب. - القيمة
disabledتبهّت المكتوب على الأغطية ولا تعرض حالة. الأمر الذي يخصه الاختصار هو الذي يقول هل هو متاح. - تبقى المفاتيح بترتيب من اليسار إلى اليمين في التخطيط من اليمين إلى اليسار، معزولة عن النص المحيط بها، كما تكتبها لوحات المفاتيح وقوائم المنصات نفسها.
- يقع على خط الأساس للنص المحيط به ويكبر مع النص المكبَّر؛ وارتفاع الغطاء حد أدنى.
- الرمز الذي ينقص خط المنتج (
⌘أو⎋) يُرسم من خط النظام بالمقاس نفسه، ولا يُرسم أبدًا مربعَ محرف مفقود. - في النظام الافتراضي يستوفي المكتوب على الغطاء تباين النص. تعبئة الغطاء زينة: المكتوب وحده يحمل المعنى.
- تبلّغ بنيات التنقيح (debug) عن التآلف الفارغ، والتآلف المكوَّن من مفاتيح معدِّلة فقط، والتآلف بمفتاحين، والمفتاح المسمّى مرتين بعد كتابته (
ctrl+modفي العُرف القياسي)، واسم المفتاح غير المعروف، والعُرف غير المعروف.
فجوات معروفة في المنصات:
- لم تنفّذ SwiftUI و Compose و Flutter و React Native اختصار لوحة المفاتيح.
- الويب: الاختصار المعطَّل الذي يقف وحده، خارج أمر معروض هو نفسه على أنه معطَّل، يُرجَّح أن يبلّغ عنه فحص تباين آلي: المكتوب عليه باهت، والعنصر لا يعرض حالة تعطيل خاصة به.
- اجعل المفاتيح تعمل: المكوّن يعرضها فقط.
- على عنصر التحكم الذي تخصه المفاتيح، اعرضها على أنها اختصار لوحة المفاتيح له. على الويب عيِّن
aria-keyshortcutsمن الخاصيةariaKeyShortcutsللعنصر، وهي للقراءة فقط وتعطي الصيغة التي تأخذها تلك السمة. - مرِّر
label، وهي الاختصار بكلمات منتجك، حيثما يُقرأ الاختصار بصوت مسموع. لا يتضمن Tanrei أي كلمة ولا أي اسم لمفتاح. - أبقِ كل أمر قابلًا للوصول إليه من دون اختصاره.