🪵 7. 편리한 게임 환경을 위한 단축키 적용기: custom hook을 통한 재사용

단축키 시스템 설계 및 구현

게임의 사용자 경험을 향상시키기 위해 단축키 시스템을 도입하였습니다. 이를 통해 사용자가 보다 효율적으로 게임을 플레이할 수 있도록 했습니다.

단축키 상수화

단축키 시스템은 크게 세 가지 부분으로 구성되어 있습니다. 첫째, 모든 단축키는 SHORTCUT_KEYS 상수에서 중앙 관리됩니다. 각 단축키는 주 키(key), 대체 키(alternativeKeys), 그리고 설명(description)을 포함하며, 게임 설정과 게임플레이 관련 기능들을 제어합니다.

export const SHORTCUT_KEYS = {
  // 설정 관련
  DROPDOWN_TOTAL_ROUNDS: {
    key: '1',
    alternativeKeys: ['1', '!'],
    description: '라운드 수 설정',
  },
  DROPDOWN_MAX_PLAYERS: {
    key: '2',
    alternativeKeys: ['2', '@'],
    description: '플레이어 수 설정',
  },
  DROPDOWN_DRAW_TIME: {
    key: '3',
    alternativeKeys: ['3', '#'],
    description: '제한시간 설정',
  },
  // 게임 관련
  CHAT: {
    key: 'Enter',
    alternativeKeys: null,
    description: '채팅',
  },
  GAME_START: {
    key: 's',
    alternativeKeys: ['s', 'S', 'ㄴ'],
    description: '게임 시작',
  },
  GAME_INVITE: {
    key: 'i',
    alternativeKeys: ['i', 'I', 'ㅑ'],
    description: '초대하기',
  },
} as const;

단축키 custom hook

둘째, useShortcuts라는 커스텀 훅을 통해 단축키 로직을 구현하였습니다. 이 훅은 여러 단축키를 배열 형태로 관리하며, 각 단축키 설정에는 키 식별자, 실행할 동작, 비활성화 상태, 그리고 입력 요소 포커스 상태에서의 동작 여부를 지정할 수 있습니다. 특히 입력 요소(input, textarea, select)에서의 특별 처리를 포함하며, canAllowInInput 옵션을 통해 입력 중에도 특정 단축키가 동작할 수 있도록 설계되었습니다.

import { useCallback, useEffect } from 'react';
import { SHORTCUT_KEYS } from '@/constants/shortcutKeys';

interface ShortcutConfig {
  key: keyof typeof SHORTCUT_KEYS | null;
  action: () => void;
  disabled?: boolean;
  canAllowInInput?: boolean;
}

export const useShortcuts = (configs: ShortcutConfig[]) => {
  const handleKeyDown = useCallback(
    (e: KeyboardEvent) => {
      const isInputElement =
        e.target instanceof HTMLInputElement ||
        e.target instanceof HTMLTextAreaElement ||
        e.target instanceof HTMLSelectElement;

      configs.forEach(({ key, action, disabled, canAllowInInput }) => {
        if (!key || disabled || (isInputElement && !canAllowInInput)) return;

        const shortcut = SHORTCUT_KEYS[key];
        const pressedKey = e.key.toLowerCase();
        const isMainKey = pressedKey === shortcut.key.toLowerCase();
        const isAlternativeKey = shortcut.alternativeKeys?.some((key) => key.toLowerCase() === pressedKey);

        if (!isMainKey && !isAlternativeKey) return;

        if (pressedKey !== 'enter' || !isInputElement) {
          e.preventDefault();
        }

        action();
      });
    },
    [configs],
  );

  useEffect(() => {
    window.addEventListener('keydown', handleKeyDown);
    return () => window.removeEventListener('keydown', handleKeyDown);
  }, [handleKeyDown]);
};

사용 예시

실제 구현에서는 채팅 기능을 예시로 들 수 있습니다. Enter 키를 통해 채팅창의 포커스를 제어하는데, 포커스된 요소가 없을 때는 입력창에 포커스를, 입력창이 비어있는 상태에서 Enter를 누르면 포커스를 해제하는 방식으로 구현되었습니다. 이러한 방식은 게임 진행 중 채팅 기능을 자연스럽게 사용할 수 있도록 돕습니다.

  useShortcuts([
    {
      key: 'CHAT',
      action: () => {
        // 현재 포커스된 요소가 없거나, 포커스된 요소가 body라면 input을 포커싱
        const isNoFocusedElement = !document.activeElement || document.activeElement === document.body;

        if (isNoFocusedElement) {
          inputRef.current?.focus();
        } else if (inputMessage.trim() === '') {
          inputRef.current?.blur();
        }
      },
      disabled: !inputRef.current,
      canAllowInInput: true,
    },
  ]);