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 calledreturn 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: 0format: ['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 valuescript: 'super',  // must be exactly 'super', 'sub' will not sufficelink: 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 listprefix: /^-$/,            // ...following a '-' characteroffset: 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 hyphenthis.quill.deleteText(range.index - 1, 1);// apply bullet formatting to the linethis.quill.formatLine(range.index, 1, 'list', 'bullet');// restore selectionthis.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 anythingcustom: {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 insteadthis.quill.format('list', false, Quill.sources.USER);} else {// Otherwise propogate to Quill's defaultreturn 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();