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

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的绑定之前运行，因为默认的绑定将在它之前被添加。

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
    }
  }
});

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()

示例

quill.history.cutoff();

undo

撤销上一个改变

方法

undo()

示例

quill.history.undo();

redo

如果上一个变化是撤销，那么重做这个撤销。否则什么也不做。

方法

redo()

示例

quill.history.redo();