72Başlayın
HextaUI

useHeldKeys

Şu anda basılı tutulan tuşlar; tek bir pencere dinleyicisi kümesi üzerinden tüm abonelerle paylaşılır.

Hold down any keys
[]
"use client"

import { Kbd, KbdGroup } from "@/components/ui/kbd"
import { useHeldKeys } from "@/hooks/use-held-keys"

export function UseHeldKeysDemo() {
  const held = useHeldKeys(true)

  return (
    <div className="flex flex-col items-center gap-3">
      <div className="flex h-8 items-center">
        {held.size > 0 ? (
          <KbdGroup>
            {[...held].map((key) => (
              <Kbd key={key} keys={key} size="lg" />
            ))}
          </KbdGroup>
        ) : (
          <span className="text-sm text-muted-foreground">
            Hold down any keys
          </span>
        )}
      </div>
      <code className="font-mono text-xs text-muted-foreground">
        {JSON.stringify([...held])}
      </code>
    </div>
  )
}

Kurulum

pnpm dlx shadcn@latest add https://hextaui.com/r/use-held-keys.json

Hook'u ve bağımlı olduğu her şeyi projenize ekler.

Kullanım

import { useHeldKeys } from "@/hooks/use-held-keys"
const held = useHeldKeys(true)
const showShortcutHints = held.has("meta") || held.has("ctrl")

Tuşlara basılmasına değil basılı tutulmasına tepki veren her şey için kullanın: aşağı basılan tuş başlıkları, ⌘'yi basılı tutarken beliren kısayol ipuçları veya sürüklerken kopyalamak için Alt gibi bir aracı değiştiren değiştirici tuşlar.

Nasıl çalışır

Hook'u çağıran her bileşen tek bir depoyu paylaşır. İlk abone window üzerine pasif keydown ve keyup dinleyicileri ekler, aboneliği bırakan son abone onları kaldırır. Elli dinleyen tuş başlığı olan bir sayfada yine tek bir dinleyici çifti vardır.

Dinleyiciler yalnızca olayları okur. preventDefault asla çağırmazlar ve React'in kendi işleyicilerinden sonra window üzerinde dururlar; böylece bir alana yazmak asla gecikmez veya değişmez.

"meta" "ctrl" "alt" "shift"     modifiers, left and right alike
"a" … "z"  "0" … "9"            letters and digits, by physical key
"space" "enter" "escape" "tab"   named keys, lowercased
"arrowup" "arrowdown" "f1" …
  • Harfler ve rakamlar fiziksel tuş olan event.code'dan gelir; bu yüzden Mac'te Option+K basılı tutulduğunda da ˚ yerine k bildirilir.
  • Tuş tekrarı yok sayılır ve bir tuş basılıyken hiçbir şey yeniden işlenmez.
  • macOS, ⌘ basılıyken diğer tuşlar için keyup göndermez. ⌘ bırakıldığında depo yalnızca hâlâ basılı olan değiştirici tuşları tutar; böylece harfler takılı kalamaz.
  • Pencere odağı kaybedince veya sekme gizlenince her şey bırakılır. Uygulama değiştiren bir kısayol hiçbir şeyi basılı bırakmaz.

Örnekler

Basılan tuş başlıkları

<Kbd listen> bu hook üzerine kuruludur. Her tuş başlığı, tuşu basılı tutulurken basılır.

"use client"

import { Kbd, KbdGroup } from "@/components/ui/kbd"
import { useHeldKeys } from "@/hooks/use-held-keys"
import { useIsApple } from "@/lib/hotkey"

export function UseHeldKeysShortcut() {
  const held = useHeldKeys(true)
  const apple = useIsApple()
  const modifier = apple ? "meta" : "ctrl"
  const ready = held.has(modifier) && held.has("shift")

  return (
    <div className="flex flex-col items-center gap-3 text-sm">
      <KbdGroup>
        <Kbd keys="mod" listen />
        <Kbd keys="shift" listen />
        <Kbd keys="p" listen />
      </KbdGroup>
      <p className="text-muted-foreground">
        {ready ? "Now press P" : "Hold the modifiers to see the hint"}
      </p>
    </div>
  )
}

Bilmekte fayda var

  • Dinlemeyi durdurmak için false verin. Hook o zaman boş bir küme döndürür ve dinleyici eklemez; bu yüzden koşulsuz çağırmak ucuzdur.
  • Küme yalnızca bir tuş basıldığında veya bırakıldığında değiştirilir; böylece kimliği memo veya effect bağımlılığı olarak çalışır.
  • Bir eylemi tetikleyen kısayollar için bunun yerine bir keydown işleyicisinde Hotkey'den matchesHotkey kullanın. Tuşları basılı tutmak durum göstermek içindir, komut çalıştırmak için değil.
  • Sunucuda ve hydration öncesinde küme boştur.

API referansı

useHeldKeys(enabled)

PropTürVarsayılan
enabledDinlenip dinlenmeyeceği. false olduğunda hiçbir şey eklenmez.
boolean–
DöndürürAçıklama
ReadonlySet<string>Şu anda basılı tutulan tuşların adları.

Kullanıldığı yerler

listen prop'ları üzerinden Kbd ve KbdGroup.

İlgili