본문으로 건너뛰기

useKeyDown

ref를 전달한 요소가 포커싱된 상태에서 keydown 이벤트 발생 시 keyDownCallbackMap으로 지정한 key에 트리거되어 콜백 함수를 호출합니다.

keyDownCallbackMap의 key는 KeyboardEvent.key가 반환하는 값이 들어가야 합니다.

만약 모든 KeyboardEvent.key에 대해 콜백 함수를 호출하고 싶다면 allKeyDownCallback 옵션을 이용할 수 있습니다.

  • 💡 allKeyDownCallback이 존재할 경우 keyDownCallbackMap으로 지정한 콜백 함수는 무시합니다.

enabled 옵션을 통해 원하는 조건에 keydown 이벤트를 바인딩할 수 있습니다.

targetRef가 할당되지 않으면 기본적으로 window에 이벤트가 바인딩됩니다.


Code​

🔗 실제 구현 코드 확인


Interface​

typescript
interface UseKeyDownProps {
  enabled?: boolean;
  keyDownCallbackMap?: Partial<KeyDownCallbackMap>;
  allKeyDownCallback?: (event: KeyboardEvent) => void;
}
typescript
// 함수 오버로딩
function useKeyDown({
  enabled,
  keyDownCallbackMap,
  allKeyDownCallback,
}: UseKeyDownProps): { ref: React.RefObject<Window | null> };

function useKeyDown<T extends HTMLElement>({
  enabled,
  keyDownCallbackMap,
  allKeyDownCallback,
}: UseKeyDownProps): { ref: React.RefObject<T | null> };

Options​

NameTypeDefaultDescription
enabledbooleantrue키보드 이벤트 리스너를 활성화할지 여부
keyDownCallbackMapPartial<KeyDownCallbackMap>{}특정 키와 해당 키가 눌렸을 때 호출될 콜백 함수들을 매핑한 객체
allKeyDownCallback(event: KeyboardEvent) => void-모든 키가 눌렸을 때 호출될 공통 콜백 함수. 설정 시 keyDownCallbackMap보다 우선 호출됨

Returns​

NameTypeDescription
refReact.RefObject<T | null>키보드 이벤트를 바인딩할 대상 요소에 연결하는 ref. 미할당 시 window에 바인딩됨

Remarks​

keyDownCallbackMap 타입 추론

자주 사용되는 KeyboardEvent.key 값들은 타입 추론이 지원됩니다. 지원되지 않는 키 값은 직접 문자열로 입력해야 합니다. 지원 목록은 KeyDownCallbackMap 인터페이스를 참고하세요.


Usage​

AllKeyDownCallback​

모든 키가 눌렸을 때 호출될 공통 콜백 함수입니다.

typescript
import { useKeyDown } from '@modern-kit/react';

const Example = () => {
  const { ref } = useKeyDown<HTMLButtonElement>({
    enabled: true, // default: true
    allKeyDownCallback: (event) => console.log('All Key', event.key)
  });

  return <button ref={ref}>버튼</button>;
};

KeyDownCallbackMap​

특정 키에 해당하는 콜백을 매핑하고, 해당 키가 눌렸을 때 호출될 콜백 함수들을 호출합니다.

typescript
import { useKeyDown } from '@modern-kit/react';

const Example = () => {
  const { ref } = useKeyDown<HTMLButtonElement>({
    enabled: true, // default: true
    keyDownCallbackMap: {
      Enter: (event) => console.log('Enter', event.key),
      Shift: (event) => console.log('Shift', event.key),
      ' ': (event) => console.log('Space', event.key),
    }
  });

  return (
    <input
      ref={ref}
      placeholder="포커스를 하고, Enter, Shift, Space 눌러보세요"
      style={{ width: '300px' }}
    />
  );
};

Example​


Remarks​

참고 자료