quill.js官方文档(八)【Module之Keyboard，History】

╰+攻爆jí腚メ 2021-07-05 02:18 741阅读 0赞

## `Keyboard`模块 ##

键盘模块启用在特定上下文中键盘事件的自定义行为。Quill使用这个来绑定格式花快捷键并阻止不受欢迎的浏览器副作用。

### 键绑定 ###

键盘绑定程序绑定到一个特定的键和键修饰符。这里的`key`是指JavaScript事件的键代码，但是允许使用字母数字键和一些常用键的字符缩写。

键修饰符包括: `metaKey, ctrlKey, shiftKey` 和 `altKey`。 此外， `shortKey` 是一个平台特定的修饰符，在Mac中等于`metaKey`，在windows和linux中相当于`ctrlKey`。

处理程序将被绑定的键盘实例调用并传入当前的选区范围。

quill.keyboard.addBinding({ 
      key: 'B',
      shortKey: true
    }, function(range, context) { 
      this.quill.formatText(range, 'bold', true);
    });
    
    // addBinding may also be called with one parameter,
    // in the same form as in initialization
    quill.keyboard.addBinding({ 
      key: 'B',
      shortKey: true,
      handler: function(range, context) { 
    
      }
    });

如果修饰符键为`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);

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

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

注意，因为`Quill` 的默认处理程序在初始化的时候添加，所以，唯一禁止它们的方法是在配置中添加你自己的处理程序。

### Context ###

上下文允许进一步的定义，让处理函数只能在特定脚本中并调用。不管上下文是否被指定，所有处理程序将提供一个作为第二参数的上下文对象。

// If the user hits backspace at the beginning of list or blockquote,
    // remove the format instead delete any text
    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`，仅在用户的选择区是收缩状态时被调用，例如，在光标形式下。如果为`false`，用户的选择区必须为非零长度才调用，也就是当用户呈现高亮字段的时候。

#### `empty` ####

如果为`true`,仅当用户的选择区是一个空行时调用，`false`表示非空行调用。注意，设置`empty`为`true`意味着`collapsed`也为`true`并且偏移量为`0`——否者用户的选区将不会是空行。

// 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` ####

为数组时，定义的任何一个格式激活时都将调用处理程序。为对象时，所有定义的格式条件必须满足。任何情况下，上下文参数需为所有当前激活状态格式组成的对象，和通过`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` ####

只有用户的选区从一行开头开始偏移`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自带几个有用的快捷键，例如用`tab`缩进列表。你可以在你自己的初始化中添加。

一些快捷键绑定对防止浏览器默认的危险操作是有必要的，比如输入回车键和退格键。你不能移除这些绑定，还原成原生浏览器行为。但是，因为配置中定义的绑定将会在Quill默认的之前运行，所以你可以处理特殊情况并传递到`quill`的其它位置。

用`quill.keyboard.addBinding`添加一个绑定不会在Quill的绑定之前运行，因为默认的绑定将在它之前被添加。

### Peformance ###

与DOM事件一样，Quill的键绑定每次匹配都是阻塞调用，所以对非常常见的键绑定一个耗费大的处理程序是不好的。当你附加常见的类似于`scroll`或`mousemove`的阻塞DOM事件时，需要使用相同性能下的最好办法。

--------------------

## 历史记录(history)模块 ##

History模块负责处理Quill的撤销和重做，可配置的选项如下：

### 配置 ###

#### `delay` ####

*  Default: `1000`

把在`delay`毫秒数内的变化合并到单一变化中。

举个例子，将延迟设置为`0`，那么几乎每次输入字符都会被记录成一个变化，然后，撤销动作就会一次撤销一个字符。将延迟设置到`1000`,撤销动作就会撤销在上一个1000毫秒发生的所有变化。

#### `maxStack` ####

*  Default: `100`

History模块撤销/重做栈的最大大小。`delay`选项合并的变化计为一个单一变化。

#### `userOnly` ####

*  Default: `false`

默认情况下，所有的改变，不管是来自用户的输入还是以编程方式通过API改变，都被处理成一样，通过`History`模块都可以重做或撤销。如果 `userOnly`被设置成 `true`，只有用户的改变才能被重做或撤销。

### 示例 ###

var quill = new Quill('#editor', { 
      modules: { 
        history: { 
          delay: 2000,
          maxStack: 500,
          userOnly: true
        }
      },
      theme: 'snow'
    });

### API ###

#### `clear` ####

清空History栈。

**方法**

clear()

**示例**

quill.history.clear();

#### `cutoff` ####

正常情况下，在短时间一系列(通过`delay`设置)变化将被合并成一个单一变化，所以，触发撤销将撤销多个改变。使用`cutoff()`将重置合并窗口，在调用`cutoff()`之前或之后的变化不会被合并。

**方法**

cutoff()

**示例**