Keyboard Module

키보드 모듈은 특정 컨텍스트에서 키보드 이벤트에 대한 사용자 지정 동작을 활성화 합니다. Quill은 이를 사용하여 단축키 포맷(ex: ctrl + B)을 바인딩하고 바람직하지 않은 브라우저 side effects를 방지합니다.

Key Bindings

키보드 핸들러는 특정 키 및 수정자에 바인딩 됩니다. key는 Javascript event key code지만, 영숫자 키와 일부 공통 키에는 문자열 단축어가 허용됩니다.

Key modifiers는 metaKey, ctrlKey, shiftKey, altKey,를 포함합니다. 또한 shortKey는 Mac에서는 metaKey, 리눅스 및 윈도우에서는 ctrlKey에 대항하는 플랫폼별 한정자입니다.

핸들러는 키보드 인스턴스에 바인딩된this를 호출하고 현재 선택 범위를 넘깁니다.

quill.keyboard.addBinding({
  key: "B",
  shortKey: true,
}, function(range, context) {
  this.quill.formatText(range, 'bold', true)
})
// addBinding은 초기화와 동일한 형식으로 
//하나의 매개 변수를 사용하여 호출할 수도 있습니다.

quill.keyboard.addBinding({
  key: 'B',
  shortKey: true,
  handler: function(range, context) {

  }
});

만약 modifier key가 false라면 활성 상태가 아님을 의미한다고 가정합니다 null을 전달하여 수식어에 대한 임의의 값을 의미할 수도 있습니다.

// Only b with no modifier will trigger
quill.keyboard.addBinding({key: "B"}, handler)

// Only shift + b will trigger
quill.keyboard.addBinding({key: "B", shiftKey: true}, handler);

// Either b or shift+b will trigger
quill.keyboard.addBinding({key: "B", shiftKey: null}, handler)
;```

여러 핸들러를 동일한 키 및 modifier 조합에 바인딩 할 수 있습니다. 핸들러는 바인딩된 순서대로 동기적으로 호출됩니다. 기본적으로 핸들러는 true를 명시적으로 반환하지 않는 한 다음 핸들러로 전파를 중지합니다.

quill.keyboard.addBinding({key: 'tab'}, function(range) {
  // 일반적으로 탭 키의 핸들러를 차단합니다.
  //true를 반환하여 나중에 핸들러를 호출할 수 있도록 합니다.
  return true
})

참고: Quill의 기본 핸들러는 초기화 시 추가되므로 이를 방지할 수 있는 유일한 방법은 [configuration](https://quilljs.com/docs/modules/keyboard/#configuration)에 사용자의 핸들러를 추가하는 것입니다.


### Context
Context를 사용하면 특정 시나리오에서만 핸들러를 호출할 수 있습니다. 컨택스트가 지정되었는지 여부에 관계없이 컨텍스트 객체가 모든 핸들러에 대한 두 번째 매개변수로 제공됩니다.

```js
// 사용자가 list 혹은 blackquote의 시작부분에서 백스페이스를 누를 경우
// format을 제거하여 텍스트를 삭제합니다.

quill.keyboard.addBinding({ key: Keyboard.keys.BACKSPACE }, {
  collapsed: true,
  format: ['blockquote', 'list'],
  offset: 0
}, function(range, context) {
  if (context.format.list) {
    this.quill.format('list', false);
  } else {
    this.quill.format('blockquote', false);
  }
});

collapsed

true인 경우 핸들러는 사용자의 선택사항이 collapsed된 상황에서만 호출됩니다(즉, 드래그되지 않은 상태). false일 경우, 사용자가 텍스트를 강조 표시한 경우와 같이 사용자의 선택 길이는 0이 아니여야 합니다.

empty

true인 경우, 사용자 선택이 빈 행에 있는 경우에만 호출되고 비어 있지 않은 행에 대해서는 false입니다. empty가 true일 경우 collasped도 true이고 간격띄우기 값이 0임을 의미합니다. 즉, 사용자 선택이 빈 줄(empty line)에 있지 않습니다.

// If the user hits enter on an empty list, remove the list instead
quill.keyboard.addBinding({ key: Keyboard.keys.ENTER }, {
  empty: true,    // implies collapsed: true and offset: 0
  format: ['list']
}, function(range, context) {
  this.quill.format('list', false);
});

format

배열에서 지정된 format 중 하나라도 활성 상태인 경우 핸들러가 호출됩니다. 객체일 경우 지정된 모든 format 조건이 충족되어야 합니다. 두 경우 모두 컨텍스트 매개 변수의 format 속성은 quill.getFormat()에서 반환되는 것과 동일한 현재 활성 형식의 객체가 됩니다.

var context = {
  format: {
    list: true,       // must be on a list, but can be any value
    script: 'super',  // must be exactly 'super', 'sub' will not suffice
    link: false       // cannot be in any link
  }
};

offset

핸들러는 사용자가 선택한 항목이 줄의 처음부터 간격띄우기 문자를 시작할 때만 호출됩니다. 인쇄 가능한 키가 적용되기 전입니다. 이 기능은 다른 컨텍스트 사양과 함께 사용할 때 유용합니다.

prefix

사용자의 선택 시작 위치 바로 앞에 있는 텍스트와 일치해야 하는 정규식입니다. 텍스트가 교차 형식 경계와 일치하지 않습니다. 제공된 context.prefix 값은 정규식 일치가 아니라 바로 앞의 전체 텍스트입니다.

// When the user types space...
quill.keyboard.addBinding({ key: ' ' }, {
  collapsed: true,
  format: { list: false },  // ...on an line that's not already a list
  prefix: /^-$/,            // ...following a '-' character
  offset: 1,                // ...at the 1st position of the line,
                            // otherwise handler would trigger if the user
                            // typed hyphen+space mid sentence
}, function(range, context) {
  // the space character is consumed by this handler
  // so we only need to delete the hyphen
  this.quill.deleteText(range.index - 1, 1);
  // apply bullet formatting to the line
  this.quill.formatLine(range.index, 1, 'list', 'bullet');
  // restore selection
  this.quill.setSelection(range.index - 1);

  // console.log(context.prefix) would print '-'
});

suffix

사용자의 선택 종료 위치 바로 뒤에 일치하는 텍스트를 제외하고 prefix와 동일합니다.

Configuration

기본적으로 Quill에는 탭이 있는 목록 들여쓰기와 같은 몇 가지 유용한 키 바인딩이 제공됩니다. 초기화 시 당신만의 키 바인딩을 추가할 수 있습니다.

일부 바인딩은 엔터 및 백스페이스 키와 같은 위험한 브라우저 기본값을 방지하는 데 필수적입니다. 이러한 바인딩을 제거하여 기본 브라우저 동작으로 되돌릴 수 없습니다. 그러나 구성(configuraiton)에 지정된 바인딩은 Quill의 기본값보다 먼저 실행되므로 특수한 경우를 처리하고 그렇지 않으면 Quill의 기본값으로 전파할 수 있습니다.

quill.keyboard.addBinding로 바인딩을 추가하면 기본 바인딩이 해당 지점에 추가되기 때문에 Quill보다 먼저 실행되지 않습니다. 각 바인딩 구성에는 키 및 핸들러 옵션이 포함되어야 하며 선택적으로 컨텍스트 옵션을 포함할 수 있습니다.

var bindings = {
  // This will overwrite the default binding also named 'tab'
  tab: {
    key: 9,
    handler: function() {
      // Handle tab
    }
  },

  // There is no default binding named 'custom'
  // so this will be added without overwriting anything
  custom: {
    key: 'B',
    shiftKey: true,
    handler: function(range, context) {
      // Handle shift+b
    }
  },

  list: {
    key: 'backspace',
    format: ['list'],
    handler: function(range, context) {
      if (context.offset === 0) {
        // When backspace on the first character of a list,
        // remove the list instead
        this.quill.format('list', false, Quill.sources.USER);
      } else {
        // Otherwise propogate to Quill's default
        return true;
      }
    }
  }
};

var quill = new Quill('#editor', {
  modules: {
    keyboard: {
      bindings: bindings
    }
  }
});

Performance

DOM이벤트와 마찬가지로 Quill 키 바인딩은 모든 모든 일치에서 호출을 차단하므로 매우 일반적인 키 바인딩에 매우 비싼 핸들러를 사용하는 것은 좋지 않습니다. scroll과 mousemove 같은 일반적인 차단 DOM이벤트에 연결할 때와 동일한 성능 모범 사례를 적용합니다.