본문으로 건너뛰기

키보드 단축키 사용법 (syn.$k)

개요​

syn.$k는 특정 노드에서 발생하는 키보드 이벤트(keydown/keyup)를 키 코드 단위로 등록/해제할 수 있는 단축키 기능을 제공합니다. 폼 입력 필드나 특정 컨테이너에서 커스텀 단축키(예: Ctrl 조합, 방향키 이동 등)를 구현할 때 사용합니다.

로드 방법​

syn.js가 로드되면 전역에 syn.$k(별칭: $keyboard)로 즉시 사용할 수 있습니다.

빠른 시작​

syn.$k.setElement('myInput');
syn.$k.addKeyCode('keydown', syn.$k.keyCodes.enter, (evt) => {
    console.log('엔터 입력됨');
});

주요 시나리오​

단축키 등록 대상 노드 지정​

setElement(el)로 키 이벤트를 수신할 노드를 지정합니다. 지정된 노드에는 내부적으로 keydown/keyup 리스너가 한 번만 등록되고, 이후 addKeyCode/removeKeyCode 호출은 이 노드를 기준으로 동작합니다.

syn.$k.setElement('myInput');

단축키 콜백 등록/해제​

addKeyCode(keyType, keyCode, func)로 keydown/keyup 이벤트에 대한 콜백을, keyCodes 테이블의 키 이름으로 지정합니다. 콜백이 false를 반환하면 기본 동작이 취소(preventDefault/stopPropagation)됩니다.

syn.$k.addKeyCode('keydown', syn.$k.keyCodes.a, (evt) => {
    console.log('A 키 눌림');
    return false;
});

syn.$k.removeKeyCode('keydown', syn.$k.keyCodes.a);

KeyboardEvent.code 값을 keyCode 숫자로 변환​

브라우저 표준 KeyboardEvent.code(예: 'KeyA', 'Enter') 값을 keyCodes 테이블에서 사용하는 숫자 코드로 변환할 때 getKeyCode(code)를 사용합니다.

const code = syn.$k.getKeyCode('KeyA'); // 65

실전 예제 페이지​

/sample/syn/keyboard.html 예제에서 다음 항목을 실습할 수 있습니다.

  • keyCodes, keyNames, targetEL, elements 속성 확인
  • setElement(), addKeyCode(), removeKeyCode(), getKeyCode() 메서드 실습

주의 사항​

  • addKeyCode/removeKeyCode는 반드시 setElement로 대상 노드를 지정한 뒤에 호출해야 합니다. 대상이 없으면 등록/삭제가 조용히 무시됩니다.
  • addKeyCode의 keyCode 인자는 숫자 키코드이므로 syn.$k.keyCodes.a처럼 keyCodes 테이블을 통해 조회해서 전달합니다.
  • keyCodes, keyNames는 Object.freeze로 동결되어 있어 런타임에 변경할 수 없습니다.

관련 모듈​

  • API 상세는 아래 API 참조 섹션을 확인하세요.

API 참조​

모듈 정보​

항목내용
전역 별칭syn.$k (원본: context.$keyboard)
소스 위치2.Modules/wwwroot/wwwroot/js/syn.js (약 2153~2349번째 줄)
예제 페이지/sample/syn/keyboard.html
의존 모듈syn.$l(library, getElement/addEvent/random)

속성​

syn.$k.keyCodes​

  • 타입: Readonly<Record<string, number>>
  • 설명: 'backspace', 'enter', 'a', 'f1' 등 키 이름 문자열과 브라우저 keyCode 숫자값의 매핑 테이블입니다. Object.freeze로 동결되어 있습니다.

syn.$k.keyNames​

  • 타입: Readonly<Record<string, string>>
  • 설명: KeyboardEvent.code 값(예: 'KeyA', 'ArrowLeft', 'Digit1')과 keyCodes에서 사용하는 키 이름 문자열의 매핑 테이블입니다. Object.freeze로 동결되어 있습니다.

syn.$k.targetEL​

  • 타입: HTMLElement | null
  • 설명: setElement()로 마지막으로 지정된 대상 노드입니다. 초기값은 null입니다.

syn.$k.elements​

  • 타입: Record<string, { keydown: object, keyup: object }>
  • 설명: setElement()로 이벤트가 등록된 노드의 eventID를 키로 하여, 각 노드별 keydown/keyup 콜백 맵을 저장하는 내부 상태입니다. 초기값은 빈 객체입니다.

메서드​

syn.$k.setElement(el)​

  • 설명: 지정한 노드를 키보드 단축키 수신 대상으로 설정합니다. 최초 호출 시 해당 노드에 keydown/keyup 리스너를 등록하고, this.elements에 콜백 저장소를 생성합니다. 이후 addKeyCode/removeKeyCode는 이 노드를 기준으로 동작합니다.
  • 매개변수
    이름타입필수설명
    el`string \HTMLElement`Y
  • 반환값: this — 메서드 체이닝을 위해 $keyboard 자기 자신을 반환합니다. 유효한 노드가 아니면 대상 갱신 없이 그대로 반환합니다.
  • 예시 
    syn.$k.setElement('myInput');

syn.$k.addKeyCode(keyType, keyCode, func)​

  • 설명: 현재 targetEL에 등록된 콜백 맵에 keyType('keydown' 또는 'keyup')과 keyCode(숫자)에 대응하는 콜백 함수를 저장합니다. 콜백이 false를 반환하면 preventDefault/stopPropagation이 호출됩니다.
  • 매개변수
    이름타입필수설명
    keyType`'keydown' \'keyup'`Y
    keyCodenumberYkeyCodes 테이블에서 조회한 키코드 숫자값.
    funcfunctionY키 입력 시 실행할 콜백. (evt) => ...
  • 반환값: this
  • 예시 
    syn.$k.setElement('myInput');
    syn.$k.addKeyCode('keydown', syn.$k.keyCodes.a, (evt) => {
        alert(evt.keyCode);
    });

syn.$k.removeKeyCode(keyType, keyCode)​

  • 설명: 현재 targetEL에 등록된 keyType/keyCode 조합의 콜백을 삭제합니다.
  • 매개변수
    이름타입필수설명
    keyType`'keydown' \'keyup'`Y
    keyCodenumberY삭제할 키코드 숫자값.
  • 반환값: this
  • 예시 
    syn.$k.removeKeyCode('keydown', syn.$k.keyCodes.a);

syn.$k.getKeyCode(code)​

  • 설명: 브라우저 표준 KeyboardEvent.code 값(예: 'KeyA')을 keyNames 테이블로 키 이름을 찾은 뒤, 다시 keyCodes 테이블에서 대응하는 숫자 코드로 변환합니다.
  • 매개변수
    이름타입필수설명
    codestringYKeyboardEvent.code 값(예: 'KeyA', 'Enter', 'ArrowLeft').
  • 반환값: number | null — 매핑되는 값이 없으면 null.
  • 예시 
    const code = syn.$k.getKeyCode('KeyA'); // 65