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