資料展示
快捷鍵鍵帽
鍵帽樣式的快捷鍵標示 React 元件：可組合多鍵、mod 依平台顯示 ⌘ 或 Ctrl，開啟監聽時使用者實際按下對應鍵，鍵帽會下沉並回彈，整組按齊時外框閃一下。
把快捷鍵說明畫成一顆顆實體鍵帽。傳 keys 陣列組合多鍵（例如 ['mod', 'K']），mod 在 mac 顯示 ⌘、其他平台顯示 Ctrl；開啟 listen 後，使用者在鍵盤上實際按下對應鍵時，該顆鍵帽會下沉、放開時以彈簧回彈，整組組合鍵按齊時外框閃一下 ring。元件只觀察按鍵、不攔截，頁面原本的快捷鍵照常運作。
把這個效果裝進你的專案
在專案資料夾執行指令，CLI 會加入原始碼與依賴套件，再依下方使用範例引用元件。
npx webberui@latest add keycap-shortcutPlayground
即時調整 props、程式碼片段同步更新——直接試出你要的樣子再複製。
80
編輯中的呼叫預設屬性
<KeycapShortcut/>
完整範例包含預覽的排版與資料。先安裝元件，再把範例檔貼入你的專案。
安裝
npx webberui@latest add https://webberui.com/r/keycap-shortcut.json或在 components.json 設定 registries 後，改用 @webberui/keycap-shortcut 安裝。
使用
import { KeycapShortcut } from "@/components/ui/keycap-shortcut";
// 組合鍵：mac 顯示 ⌘ K，其他平台顯示 Ctrl K
<KeycapShortcut keys={["mod", "K"]} listen />
// 單鍵，嵌在文字裡
<p>
按 <KeycapShortcut>Esc</KeycapShortcut> 關閉
</p>
// 加上分隔字元、較大尺寸
<KeycapShortcut keys={["shift", "mod", "P"]} separator="+" size="md" />Props
| Prop | 型別 | 預設值 | 說明 |
|---|---|---|---|
children | React.ReactNode | — | 單鍵文字（例如「Esc」、「K」）；與 keys 擇一，keys 優先 |
keys | string[] | — | 組合鍵陣列，例如 ['mod', 'K']；mod 依平台顯示 ⌘ 或 Ctrl |
listen | boolean | false | 是否監聽實際按鍵；開啟時按下對應鍵，鍵帽會下沉並回彈 |
size | "sm" | "md" | "sm" | 鍵帽尺寸（高度 24px／28px） |
separator | React.ReactNode | — | 組合鍵之間的分隔字元（例如 "+"）；預設不顯示分隔 |
platform | "auto" | "mac" | "other" | "auto" | 顯示平台；auto 會在掛載後偵測，SSR 首次渲染一律以 other 顯示 |
pressDuration | number | 80 | 鍵帽下沉的時長（毫秒），同時寫入 --wb-keycap-shortcut-duration |
className | string | — | 併入最外層容器的 className |
另外具名匯出 resolveKeycap(token, isMac)：回傳 ResolvedKeycap（顯示文字、螢幕閱讀器全名、aria-keyshortcuts 鍵名與比對識別字），方便在自訂 UI 裡重用同一套鍵名對照。
ResolvedKeycap
| 欄位 | 型別 | 預設值 | 說明 |
|---|---|---|---|
label | string | — | 鍵帽上顯示的文字或符號 |
srLabel | string | — | 符號鍵帽給螢幕閱讀器的全名；純文字鍵帽為 undefined |
aria | string | — | aria-keyshortcuts 使用的鍵名（例如 Meta、Control、ArrowUp） |
match | string[] | — | 監聽時可比對的鍵識別字 |
細節
- 鍵名對照：
mod→ ⌘／Ctrl、alt→ ⌥／Alt、shift→ ⇧、enter→ ↵、esc→ Esc、tab→ Tab、space→ 空白鍵、arrowup等 → ↑ ↓ ← →、backspace→ ⌫；其餘鍵名原樣轉大寫。 - 監聽只在
listen為true時掛上 window 的 keydown／keyup，以e.key（不分大小寫）比對，並以e.code補上字母與數字——mac 按住 ⌥ 時e.key會變成特殊符號，仍能對到正確鍵帽。每顆鍵帽各自判斷自己的鍵是否被按著。 - 不呼叫
preventDefault：元件只觀察、不攔截，瀏覽器與頁面原本的快捷鍵照常觸發。 - mac 按住 ⌘ 時其他鍵不會發 keyup，因此放開 ⌘ 時會重置所有按下狀態；視窗失去焦點（blur）時同樣重置。
- IME 組字中（
isComposing或keyCode229）的 keydown 直接略過。 - 節奏外露成 CSS 變數：
--wb-keycap-shortcut-duration（由pressDuration寫入）與--wb-keycap-shortcut-ease（預設cubic-bezier(0.23,1,0.32,1)），可在全域覆寫。放開時以 stiffness 600、damping 20 的彈簧回彈。
可及性
- 最外層加上
aria-keyshortcuts（例如Meta+K或Control+K，依平台），輔助科技可讀到完整快捷鍵 - 每顆鍵帽是語意化的
kbd元素；符號鍵帽（⌘、⇧、↵、方向鍵等）的符號對輔助科技隱藏，改以 sr-only 全名（例如「Command」、「Shift」）朗讀 - 監聽狀態的變化只影響外觀，不改變任何 aria 屬性，螢幕閱讀器不會被按鍵動畫打擾
- 使用者系統開啟「減少動態效果」時，按下只改變背景色，不位移、不回彈