Keyboard Module

键盘模块为特定上下文中的键盘事件启用自定义行为。 Quill使用它来绑定格式化热键并防止不良的浏览器副作用。

Key Bindings

键盘处理程序绑定到特定键和键修饰符。 key是JavaScript事件键代码，但字母数字键和一些常用键允许使用字符串短序。

键修饰符包括：metaKey，ctrlKey，shiftKey 和 altKey。 此外，shortKey是一个平台特定的修饰符，相当于Mac上的metaKey 和Linux和Windows上的ctrlKey。

处理程序被调用时，this会被绑定到键盘实例，同时还会注入当前的光标对象。

  1. quill.keyboard.addBinding({
  2.   key: 'B',
  3.   shortKey: true
  4. }, function(range, context) {
  5.   this.quill.formatText(range, 'bold', true);
  6. });
  8. // addBinding may also be called with one parameter,
  9. // in the same form as in initialization
  10. quill.keyboard.addBinding({
  11.   key: 'B',
  12.   shortKey: true,
  13.   handler: function(range, context) {
  15.   }
  16. });

如果修饰键为false，则假定修饰符不活动。 您也可以传递null以表示修饰符的任何值。

  1. // Only b with no modifier will trigger
  2. quill.keyboard.addBinding({ key: 'B' }, handler);
  4. // Only shift+b will trigger
  5. quill.keyboard.addBinding({ key: 'B', shiftKey: true }, handler);
  7. // Either b or shift+b will trigger
  8. quill.keyboard.addBinding({ key: 'B', shiftKey: null }, handler);

多个处理程序可以绑定到相同的键和修饰符组合。 处理程序将按照绑定的顺序同步调用。 默认情况下，处理程序停止传播到下一个处理程序，除非它显式返回true。

  1. quill.keyboard.addBinding({ key: 'tab' }, function(range) {
  2.   // I will normally prevent handlers of the tab key
  3.   // Return true to let later handlers be called
  4.   return true;
  5. });

注意：由于Quill的默认处理程序是在初始化时添加的，因此阻止它们的唯一方法是在配置中添加你的处理程序。

Context

上下文允许仅在特定场景中调用处理程序的进一步规范。无论是否指定了上下文，都将提供上下文对象作为所有处理程序的第二个参数。

  1. // If the user hits backspace at the beginning of list or blockquote,
  2. // remove the format instead delete any text
  3. quill.keyboard.addBinding({ key: Keyboard.keys.BACKSPACE }, {
  4.   collapsed: true,
  5.   format: ['blockquote', 'list'],
  6.   offset: 0
  7. }, function(range, context) {
  8.   if (context.format.list) {
  9.     this.quill.format('list', false);
  10.   } else {
  11.     this.quill.format('blockquote', false);
  12.   }
  13. });

collapsed

如果为true，则仅在用户的选择被折叠时（即以光标形式）调用处理程序。 如果为false，则用户的选择长度必须为非零，例如当用户突出显示文本时。

empty

如果为true，则仅在用户选择空行时调用，对于非空行调用false。 注意将empty设置为true意味着collapsed也为true且offset为0 - 否则用户的选择将不在空行上。

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

format

当一个Array，如果任何指定的格式处于活动状态，将调用处理程序。 当一个Object时，必须满足所有指定的格式条件。 在任何一种情况下，context参数的format属性都是所有当前活动格式的Object，与quill.getFormat()返回的格式相同。

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

offset

只有当用户选择从行首开始offset字符时才会调用处理程序。 请注意，这是在应用可打印键之前。 这与其他上下文规范结合使用非常有用。

prefix

正则表达式必须与用户选择的开始位置之前的文本匹配。 文本将不符合交叉格式边界。 提供的context.prefix值将是整个前一个文本，而不仅仅是正则表达式匹配。

  1. // When the user types space...
  2. quill.keyboard.addBinding({ key: ' ' }, {
  3.   collapsed: true,
  4.   format: { list: false },  // ...on an line that's not already a list
  5.   prefix: /^-$/,            // ...following a '-' character
  6.   offset: 1,                // ...at the 1st position of the line,
  7.                             // otherwise handler would trigger if the user
  8.                             // typed hyphen+space mid sentence
  9. }, function(range, context) {
  10.   // the space character is consumed by this handler
  11.   // so we only need to delete the hyphen
  12.   this.quill.deleteText(range.index - 1, 1);
  13.   // apply bullet formatting to the line
  14.   this.quill.formatLine(range.index, 1, 'list', 'bullet');
  15.   // restore selection
  16.   this.quill.setSelection(range.index - 1);
  18.   // console.log(context.prefix) would print '-'
  19. });

suffix

与上文的prefix相同，但紧跟用户选择结束位置后的匹配文本除外。

Configuration

默认情况下，Quill附带了几个有用的键绑定，例如使用制表符缩进列表。 您可以在启动时添加自己的。

某些绑定对于防止危险的浏览器默认值（例如enter和backspace键）至关重要。您无法删除这些绑定以恢复到本机浏览器行为。但是，由于配置中指定的绑定将在Quill的默认值之前运行，因此您可以处理特殊情况并以其他方式传播到Quill。

使用quill.keyboard.addBinding添加绑定将不会在Quill之前运行，因为该点将添加默认绑定。

每个绑定配置必须包含key和handler选项，并且可以选择包含任何context选项。

  1. var bindings = {
  2.   // This will overwrite the default binding also named 'tab'
  3.   tab: {
  4.     key: 9,
  5.     handler: function() {
  6.       // Handle tab
  7.     }
  8.   },
  10.   // There is no default binding named 'custom'
  11.   // so this will be added without overwriting anything
  12.   custom: {
  13.     key: 'B',
  14.     shiftKey: true,
  15.     handler: function(range, context) {
  16.       // Handle shift+b
  17.     }
  18.   },
  20.   list: {
  21.     key: 'backspace',
  22.     format: ['list'],
  23.     handler: function(range, context) {
  24.       if (context.offset === 0) {
  25.         // When backspace on the first character of a list,
  26.         // remove the list instead
  27.         this.quill.format('list', false, Quill.sources.USER);
  28.       } else {
  29.         // Otherwise propogate to Quill's default
  30.         return true;
  31.       }
  32.     }
  33.   }
  34. };
  36. var quill = new Quill('#editor', {
  37.   modules: {
  38.     keyboard: {
  39.       bindings: bindings
  40.     }
  41.   }
  42. });

Performance

与DOM事件一样，Quill键绑定是对每个匹配的阻塞调用，因此对于非常常见的键绑定而言，拥有一个非常昂贵的处理程序是一个坏主意。 应用与附加到常见阻塞DOM事件（如scroll或mousemove）时相同的性能最佳实践。