[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&mdash;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事件時，需要使用相同性能下的最好辦法。