단축키

단축키를 사용하면 플레이어는 빠른 저장, 대화 건너뛰기, 미니게임 조작과 같은 동작을 키보드에서 직접 실행할 수 있습니다. window.addEventListener("keydown", ...) 호출을 직접 관리하는 대신, 범위, 시퀀스, 홀드 키, 충돌 감지 기능을 갖춘 타입 지정 명령 시스템으로 키보드 입력을 변환해 주는 라이브러리인 TanStack Hotkeys를 사용하는 것을 권장합니다.

사용법앵커 링크 복사

useHotkey 훅으로 단축키를 등록합니다:

import { useHotkey } from "@tanstack/react-hotkeys";

useHotkey("Mod+S", () => {
    quickSave();
});

Mod 수식자는 macOS에서는 자동으로 Meta(Cmd)로, Windows/Linux에서는 Control로 해석되므로, 동일한 코드가 모든 플랫폼에서 동작합니다.

범위 지정 및 조건부 활성화앵커 링크 복사

useHotkey는 훅이므로 컴포넌트가 마운트될 때 단축키를 등록하고 언마운트될 때 자동으로 정리합니다 — 수동으로 사용하는 window.addEventListener와 달리 리스너를 직접 제거할 필요가 없습니다.

target 옵션을 사용하면 단축키를 특정 요소로 제한할 수 있고, enabled 옵션을 사용하면 미니게임이 실행 중일 때와 같이 게임 상태에 따라 단축키를 켜거나 끌 수 있습니다:

const panelRef = useRef<HTMLDivElement>(null);

useHotkey("Escape", () => closePanel(), { target: panelRef });
useHotkey("ArrowUp", () => setDirection(0, -1), { enabled: !gameOver });

더 알아보기앵커 링크 복사

TanStack Hotkeys는 키 시퀀스(예: "G 다음 D"), 홀드 키, 충돌 감지, 개발자 도구 패널도 지원합니다. 전체 기능 목록은 공식 문서를 참고하세요.