GitLab에서 키보드 단축키를 구현할 때는 Mousetrap을 사용합니다.

Mousetrap은 키보드 단축키 문자열(예: mod+shift+p 또는 p b)을 JavaScript 핸들러에 바인딩할 수 있는 API를 제공합니다:

// 이 방식은 사용하지 마세요. 아래 설명 참고
Mousetrap.bind('p b', togglePerformanceBar)

그러나 위와 같이 하드코딩된 키 시퀀스를 핸들러에 직접 연결하면, 사용자가 해당 키보드 단축키를 커스터마이징하거나 비활성화할 수 없습니다.

키보드 단축키를 커스터마이징할 수 있도록, 커맨드는 ~/behaviors/shortcuts/keybindings.js에 정의됩니다. keysFor 메서드는 제공된 커맨드에 맞는 올바른 키 시퀀스를 반환하는 역할을 합니다:

import { keysFor, TOGGLE_PERFORMANCE_BAR } from '~/behaviors/shortcuts/keybindings'

Mousetrap.bind(keysFor(TOGGLE_PERFORMANCE_BAR), togglePerformanceBar);

단축키 커스터마이징#

keybindings.js는 키보드 단축키 커스터마이징 내용을 localStorage에 JSON 문자열로 저장합니다. keysFor가 호출되면, 제공된 커맨드 객체의 id를 사용해 localStorage에 저장된 커스터마이징 내용을 조회하고, 커스텀 키바인딩이 있으면 해당 키바인딩을 반환하며, 커맨드가 커스터마이징되지 않은 경우에는 기본 키바인딩을 반환합니다. 현재 이 커스터마이징을 편집할 수 있는 UI는 없습니다.

새 단축키 추가#

키보드 단축키는 최종 사용자가 커스터마이징하거나 비활성화할 수 있으므로, 개발자는 GitLab에 다양한 키보드 단축키를 적극적으로 추가하는 것이 권장됩니다. 사용 빈도가 낮을 것으로 예상되는 단축키는 기본적으로 비활성화하는 것이 좋습니다.

새 단축키를 추가하려면, keybindings.js에 새 커맨드 객체를 정의하고 내보냅니다:

export const MAKE_COFFEE = {
  id: 'foodAndBeverage.makeCoffee',
  description: s__('KeyboardShortcuts|Make coffee'),
  defaultKeys: ['mod+shift+c'],
};

다음으로, 적절한 키바인딩 그룹 객체에 새 커맨드를 추가합니다:

const COFFEE_GROUP = {
  id: 'foodAndBeverage',
  name: s__('KeyboardShortcuts|Food and Beverage'),
  keybindings: [
    MAKE_ESPRESSO,
    MAKE_LATTE,
    MAKE_COFFEE
  ];
}

마지막으로, 애플리케이션 코드에서 keysFor 함수와 새 커맨드 객체를 import하고, Mousetrap을 사용해 단축키를 핸들러에 바인딩합니다:

import { keysFor, MAKE_COFFEE } from '~/behaviors/shortcuts/keybindings'

Mousetrap.bind(keysFor(MAKE_COFFEE), makeCoffee);

더 많은 예시는 keybindings.js에 있는 기존 커맨드 정의를 참고하세요.

단축키 비활성화#

단축키를 할당 해제(unassigned) 상태로 만들어 비활성화하려면, 단축키를 빈 배열 []에 할당합니다. 예를 들어, 기본적으로 비활성화된 새 단축키를 추가하려면 커맨드를 다음과 같이 정의합니다:

export const MAKE_MOCHA = {
  id: 'foodAndBeverage.makeMocha',
  description: s__('KeyboardShortcuts|Make a mocha'),
  defaultKeys: [],
};

단축키를 커스터마이징 불가능하게 만들기#

경우에 따라 키보드 단축키를 커스터마이징할 수 없도록 해야 할 때가 있습니다(이는 드문 경우여야 합니다).

이 경우, customizable: false를 지정해 단축키를 정의하면 해당 키바인딩의 커스터마이징이 비활성화됩니다:

export const MAKE_AMERICANO = {
  id: 'foodAndBeverage.makeAmericano',
  description: s__('KeyboardShortcuts|Make an Americano'),
  defaultKeys: ['mod+shift+a'],

  // 이 단축키의 커스터마이징을 비활성화합니다
  customizable: false
};

이 단축키는 항상 defaultKeys에 바인딩됩니다.

크로스 플랫폼 단축키 만들기#

모든 플랫폼과 브라우저에서 잘 동작하는 단축키를 만드는 것은 어렵습니다. 이것이 단축키를 커스터마이징하고 비활성화할 수 있는 기능이 중요한 이유 중 하나입니다.

키보드 단축키의 이식성을 높이는 중요한 방법 중 하나는 mod 단축키 문자열을 사용하는 것입니다. mod는 Mac에서는 Command 키로, 그 외 환경에서는 Control 키로 해석됩니다.

자세한 내용은 Mousetrap 문서를 참고하세요.