Hotkey
Analysez, libellez, annoncez et faites correspondre des raccourcis clavier, avec ⌘ sur les plateformes Apple et Ctrl partout ailleurs.
- Apple
- ⇧⌘K
- Windows and Linux
- Shift+Ctrl+K
- Screen readers
- Shift Command K
- parseHotkey
- [["shift","mod","k"]]
Click outside the field and press Shift Command Kmatched 0×
pnpm dlx shadcn@latest add https://hextaui.com/r/hotkey.jsonAjoute l’utilitaire et tout ce dont il dépend à votre projet.
Copiez et collez le code suivant dans votre projet.
lib/hotkey.ts Mettez à jour les chemins d’import selon la configuration de votre projet.
Écrivez chaque raccourci une seule fois, sous forme de chaîne, et utilisez la même chaîne pour l’afficher, l’annoncer et le faire correspondre. mod signifie ⌘ sur les plateformes Apple et Ctrl partout ailleurs. C’est presque toujours ce que vous voulez, car Ctrl+K sur Mac et ⌘K sur Windows paraissent tous deux incongrus.
Les touches sont séparées par + et insensibles à la casse. Les touches nommées utilisent la valeur KeyboardEvent.key en minuscules, comme enter, tab, pageup ou f5. Utilisez space pour la barre d’espace.
parseHotkey retourne un tableau par accord, avec les alias résolus et les modificateurs triés dans l’ordre d’Apple : Control, Option, Shift, Command. Chaque libellé construit à partir de lui se lit dans l’ordre auquel on s’attend.
Les plateformes Apple utilisent des symboles sans séparateur, comme les menus les affichent. Windows et Linux utilisent des mots reliés par +. Les symboles sont difficiles à lire à voix haute : spokenKey donne donc le nom qu’un lecteur d’écran doit annoncer à la place. <Kbd keys> affiche le symbole et place le nom prononcé dans un texte masqué visuellement.
useIsApple() détermine la plateforme. Il retourne true sur le serveur et pendant l’hydratation, puis la vraie réponse : un visiteur sous Windows voit brièvement ⌘ avant Ctrl au lieu de provoquer une erreur d’hydratation.
Écouteur de raccourcis
matchesHotkey compare un événement keydown à un raccourci. Les modificateurs doivent correspondre exactement : mod+b ne se déclenche donc pas pour mod+shift+b.
- Les lettres et les chiffres correspondent aussi par touche physique :
alt+kfonctionne donc sur Mac, où Option+K produit˚. - Les lettres décalées correspondent :
shift+kcorrespond auKque produit Shift. - Il fait correspondre un seul accord. Pour des séquences comme
g i, suivez vous-même l’accord précédent. - Ignore les raccourcis sans modificateur lorsque le focus est dans un champ de texte : taper une lettre ne déclenche jamais une commande.
| Export | Description |
|---|---|
parseHotkey(hotkey) | string[][] : un tableau par accord, avec les alias résolus et les modificateurs triés. |
formatHotkey(hotkey, apple) | Le libellé d’un accord, comme ⇧⌘K ou Shift+Ctrl+K. |
keyLabel(key, apple) | Le libellé visible d’un nom de touche. |
spokenKey(key, apple) | Le nom qu’un lecteur d’écran doit annoncer pour une touche. |
matchesHotkey(event, hotkey) | Indique si un KeyboardEvent correspond à un accord, avec des modificateurs exacts. |
isApplePlatform() | Lit navigator.platform. true sur le serveur. |
useIsApple() | isApplePlatform sous forme de hook compatible avec l’hydratation. |
Kbd et Command.
- CommandUne liste d’actions recherchable, intégrée ou en palette ⌘K, avec pages, raccourcis et correspondances surlignées.
- KbdDes keycaps pour les raccourcis qui affichent les bons symboles sur chaque plateforme, se lisent correctement à voix haute et s’enfoncent comme de vraies touches.
- SidebarUne barre latérale d’application qui se réduit en icônes ou hors canevas, reste épinglée sous votre en-tête et devient une sheet balayable sur mobile.