[TOC]
<!--
The Keyboard module enables custom behavior for keyboard events in particular contexts. Quill uses this to bind formatting hotkeys and prevent undesirable browser side effects.
-->
键盘模块启用在特定上下文中键盘事件的自定义行为。Quill使用这个来绑定格式花快捷键并阻止不受欢迎的浏览器副作用。
## 键绑定
<!--
Keyboard handlers are bound to a particular key and key modifiers. The `key` is the JavaScript event key code, but string shorthands are allowed for alphanumeric keys and some common keys.
Key modifiers include: `metaKey`, `ctrlKey`, `shiftKey` and `altKey`. In addition, `shortKey` is a platform specific modifier equivalent to `metaKey` on a Mac and `ctrlKey` on Linux and Windows.
Handlers will be called with `this` bound to the keyboard instance and be passed the current selection range.
-->
键盘绑定程序绑定到一个特定的键和键修饰符。这里的`key`是指JavaScript事件的键代码，但是允许使用字母数字键和一些常用键的字符缩写。
键修饰符包括: `metaKey`, `ctrlKey`, `shiftKey` 和 `altKey`。 此外， `shortKey` 是一个平台特定的修饰符，在Mac中等于`metaKey`，在windows和linux中相当于`ctrlKey`。
处理程序将被绑定的键盘实例调用并传入当前的选区范围。
```js
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) {
}
});
```
<!--
If a modifier key is `false`, it is assumed to mean that modifier is not active. You may also pass `null` to mean any value for the modifier.
-->
如果修饰符键为`false`，则假定这个修饰符不起作用。你也可以传入`null`表示任意一个修饰符值。
```js
// b且不带任何修饰符才触发
quill.keyboard.addBinding({ key: 'B' }, handler);
// 只有shift+b才触发
quill.keyboard.addBinding({ key: 'B', shiftKey: true }, handler);
// b或shift+b都触发
quill.keyboard.addBinding({ key: 'B', shiftKey: null }, handler);
```
<!--
Multiple handlers may be bound to the same key and modifier combination. Handlers will be called synchronously, in the order they were bound. By default, a handler stops propagating to the next handler, unless it explicitly returns `true`.
-->
多个处理程序可以绑定到同一个键和修饰符组合。处理程序将按照他们绑定的的顺序同步调用。默认的，除非显示的返回`true`，处理程序将停止传播到下一个处理程序。
```js
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;
});
```
<!--
Note: Since Quill's default handlers are added at initialization, the only way to prevent them is to add yours in the [configuration](#configuration).
-->
注意，因为Quill 的默认处理程序在初始化的时候添加，所以，唯一禁止它们的方法是在[配置](#configuration)中添加你自己的处理程序。
## 上下文
<!--
Contexts enable further specification for handlers to be called only in particular scenarios. Regardless if context is specified, a context object is provided as a second parameter for all handlers.
-->
上下文允许进一步的定义，让处理函数只能在特定脚本中并调用。不管上下文是否被指定，所有处理程序将提供一个作为第二参数的上下文对象。
```js
// 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
<!--
If `true`, handler is called only if the user's selection is collapsed, i.e. in cursor form. If `false`, the users's selection must be non-zero length, such as when the user has highlighted text.
-->
如果设置为`true`，仅在用户的选择区是收缩状态时被调用，例如，在光标形式下。如果为`false`，用户的选择区必须为非零长度才调用，也就是当用户呈现高亮字段的时候。
### empty
<!--
If `true`, called only if user's selection is on an empty line, `false` for a non-empty line. Note setting empty to be true implies collapsed is also true and offset is 0—otherwise the user's selection would not be on an empty line.
-->
如果为`true`,仅当用户的选择区是一个空行时调用，`false`表示非空行调用。注意，设置`empty`为`true`意味着`collapsed`也为`true`并且偏移量为0——否者用户的选区将不会是空行。
```js
// 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
<!--
When an Array, handler will be called if *any* of the specified formats are active. When an Object, *all* specified formats conditions must be met. In either case, the context parameter will be an Object of all current active formats, the same returned by `quill.getFormat()`.
-->
为数组时，定义的*任何*一个格式激活时都将调用处理程序。为对象时，*所有*定义的格式条件必须满足。任何情况下，上下文参数需为所有当前激活状态格式组成的对象，和通过`quill.getFormat()`返回的一样。
```js
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
<!--
Handler will be only called when the user's selection starts `offset` characters from the beginning of the line. Note this is before printable keys have been applied. This is useful in combination with other context specifications.
-->
只有用户的选区从一行开头开始偏移`offset`个字符，处理程序才会被调用。注意，这是可输出键应用之前调用的。可用于结合其它上下文规则。
### prefix
<!--
Regex that must match the text immediately preceding the user's selection's start position. The text will not match cross format boundaries. The supplied `context.prefix` value will be the entire immediately preceding text, not just the regex match.
-->
从用户选区开始之前的需要匹配连续文本的正则表达式。这个文本不会匹配交叉格式边界。输出`context.prefix`的值会是整个连续文本，不仅仅是正则表达式匹配的。
```js
// 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
The same as [`prefix`](#prefix) except matching text immediately following the user's selection's end position.
和 [`prefix`](#prefix) 一样，除了是匹配紧随用户选区结束位置后的文本。
## Configuration
<!--
By default, Quill comes with several useful key bindings, for example indenting lists with tabs. You can add your own upon initization.
Some bindings are essential to preventing dangerous browser defaults, such as the enter and backspace keys. You cannot remove these bindings to revert to native browser behaviors. However since bindings specified in the configuration will run before Quill's defaults, you can handle special cases and propagate to Quill's otherwise.
Adding a binding with `quill.keyboard.addBinding` will not run before Quill's because the defaults bindings will have been added by that point.
-->
默认情况下，Quill自带几个有用的快捷键，例如用tab缩进列表。你可以在你自己的初始化中添加。
一些快捷键绑定对防止浏览器默认的危险操作是有必要的，比如输入回车键和退格键。你不能移除这些绑定，还原成原生浏览器行为。但是，因为配置中定义的绑定将会在Quill默认的之前运行，所以你可以处理特殊情况并传递到quill的其它位置。
用`quill.keyboard.addBinding`添加一个绑定不会在Quill的绑定之前运行，因为默认的绑定将在它之前被添加。
```javascript
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',
context: {
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
<!--
Like DOM events, Quill key bindings are blocking calls on every match, so it is a bad idea to have a very expensive handler for a very common key binding. Apply the same performance best practices as you would when attaching to common blocking DOM events, like `scroll` or `mousemove`.
-->
与DOM事件一样，Quill的键绑定每次匹配都是阻塞调用，所以对非常常见的键绑定一个耗费大的处理程序是不好的。当你附加常见的类似于`scroll`或`mousemove`的阻塞DOM事件时，需要使用相同性能下的最好办法。
- 前言
- 快速开始(quick_start)
- 下载(download)
- 配置(configuration)
- 格式(formats)
- API
- 内容(contents)
- 格式化(formatting)
- 选区(selection)
- 编辑器(editor)
- 事件(events)
- 模型(model)
- 扩展(extension)
- 增量(Delta)
- 模块(modules)
- 工具栏(toolbar)
- 键盘(keyboard)
- 历史记录(history)
- 粘贴板(clipboard)
- 语法高亮(syntax)
- 主题(themes)
- 更多教程
- 为什么选择Quill？
- 如何定制Quill？
- 设计Delta格式(未翻译)
- 构建一个自定义模块
- 将Quill加入你的编译管线(未翻译)
- Cloning Medium with Parchment
- 和其它富文本编辑器的对比(未翻译)
- Designing the Delta Format
- 扩展模块
- vue-quill-editor
- quill-image-extend-module
- quill-image-resize-module
- quill-image-drop-module
- quill-better-table
- quilljs-table
- 更多模块