现代富文本编辑器Quill的内容渲染机制

DevUI是一支兼具设计视角和工程视角的团队，服务于华为云 DevCloud平台和华为内部数个中后台系统，服务于设计师和前端工程师。
官方网站： devui.design
Ng组件库： ng-devui（欢迎Star）

引言

在 Web 开发领域，富文本编辑器（ Rich Text Editor ）是一个使用场景很是广，又很是复杂的组件。

要从0开始作一款好用、功能强大的富文本编辑器并不容易，基于现有的开源库进行开发能节省很多成本。

Quill 是一个很不错的选择。

本文主要介绍Quill内容渲染相关的基本原理，主要包括：

1. Quill描述编辑器内容的方式
2. Quill将Delta渲染到DOM的基本原理
3. Scroll类管理全部子Blot的基本原理

Quill如何描述编辑器内容？

Quill简介

Quill 是一款API驱动、易于扩展和跨平台的现代 Web 富文本编辑器。目前在 Github 的 star 数已经超过25k。

Quill 使用起来也很是方便，简单几行代码就能够建立一个基本的编辑器：

1 <script>
2   var quill = new Quill('#editor', {
3     theme: 'snow'
4   });
5 </script>

​

Quill如何描述格式化的文本

当咱们在编辑器里面插入一些格式化的内容时，传统的作法是直接往编辑器里面插入相应的 DOM，经过比较 DOM 树来记录内容的改变。

直接操做 DOM 的方式有不少不便，好比很难知道编辑器里面某些字符或者内容究竟是什么格式，特别是对于自定义的富文本格式。

Quill 在 DOM 之上作了一层抽象，使用一种很是简洁的数据结构来描述编辑器的内容及其变化：Delta。

Delta 是JSON的一个子集，只包含一个 ops 属性，它的值是一个对象数组，每一个数组项表明对编辑器的一个操做（以编辑器初始状态为空为基准）。

好比编辑器里面有"Hello World"：

​

用 Delta 进行描述以下：

1 {
2   "ops": [
3     { "insert": "Hello " },
4     { "insert": "World", "attributes": { "bold": true } },
5     { "insert": "\n" }
6   ]
7 }

意思很明显，在空的编辑器里面插入"Hello "，在上一个操做后面插入加粗的"World"，最后插入一个换行"\n"。

Quill如何描述内容的变化

Delta 很是简洁，但却极富表现力。

它只有3种动做和1种属性，却足以描述任何富文本内容和任意内容的变化。

3种动做：

• insert：插入
• retain：保留
• delete：删除

1种属性：

• attributes：格式属性

好比咱们把加粗的"World"改为红色的文字"World"，这个动做用 Delta 描述以下：

1 {
2   "ops": [
3     { "retain": 6 },
4     { "retain": 5, "attributes": { "color": "#ff0000" } }
5   ]
6 }

意思是：保留编辑器最前面的6个字符，即保留"Hello "不动，保留以后的5个字符"World"，并将这些字符设置为字体颜色为"#ff0000"。

若是要删除"World"，相信聪明的你也能猜到怎么用 Delta 描述，没错就是你猜到的：

1 {
2   "ops": [
3     { "retain": 6 },
4     { "delete": 5 }
5   ]
6 }

Quill如何描述富文本内容

最多见的富文本内容就是图片，Quill 怎么用 Delta 描述图片呢？

insert 属性除了能够是用于描述普通字符的字符串格式以外，还能够是描述富文本内容的对象格式，好比图片：

1 {
2   "ops": [
3     { "insert": { "image": "https://quilljs.com/assets/images/logo.svg" } },
4     { "insert": "\n" }
5   ]
6 }

好比公式：

1 { 
2   "ops": [ 
3     { "insert": { "formula": "e=mc^2" } }, 
4     { "insert": "\n" } 
5   ]
6 }

Quill 提供了极大的灵活性和可扩展性，能够自由定制富文本内容和格式，好比幻灯片、思惟导图，甚至是3D模型。

setContent如何将Delta数据渲染成DOM？

上一节咱们介绍了 Quill 如何使用 Delta 描述编辑器内容及其变化，咱们了解到 Delta 只是普通的 JSON 结构，只有3种动做和1种属性，却极富表现力。

那么 Quill 是如何应用 Delta 数据，并将其渲染到编辑器中的呢？

setContents 初探

Quill 中有一个 API 叫 setContents，能够将 Delta 数据渲染到编辑器中，本期将重点解析这个 API 的实现原理。

仍是用上一期的 Delta 数据做为例子：

1 const delta = {  "ops": [
2     { "insert": "Hello " },
3     { "insert": "World", "attributes": { "bold": true } },
4     { "insert": "\n" } ]
5 }

当使用 new Quill() 建立好 Quill 的实例以后，咱们就能够调用它的 API 啦。

1 const quill = new Quill('#editor', {
2   theme: 'snow'
3 });

咱们试着调用下 setContents 方法，传入刚才的 Delta 数据：

1 quill.setContents(delta);

编辑器中就出现了咱们预期的格式化文本：

​

setContents 源码

经过查看 setContents 的源码，发现就调用了 modify 方法，主要传入了一个函数：

 1 setContents(delta, source = Emitter.sources.API) {
 2   return modify.call( this, () => {
 3     delta = new Delta(delta);
 4     const length = this.getLength();
 5     const deleted = this.editor.deleteText(0, length);
 6     const applied = this.editor.applyDelta(delta);
 7     ... // 为了方便阅读，省略了非核心代码
 8     return deleted.compose(applied);
 9   }, source, );
10 }

使用 call 方法调用 modify 是为了改变其内部的 this 指向，这里指向的是当前的 Quill 实例，由于 modify 方法并非定义在 Quill 类中的，因此须要这么作。

咱们先不看 modify 方法，来看下传入 modify 方法的匿名函数。

该函数主要作了三件事：

1. 把编辑器里面原有的内容所有删除
2. 应用传入的 Delta 数据，将其渲染到编辑器中
3. 返回1和2组合以后的 Delta 数据

咱们重点看第2步，这里涉及到 Editor 类的 applyDelta 方法。

applyDelta 方法解析

根据名字大概能猜到该方法的目的是：把传入的 Delta 数据应用和渲染到编辑器中。

它的实现咱们大概也能够猜想就是：循环 Delta 里的 ops 数组，一个一个地应用到编辑器中。它的源码一共54行，大体以下：

 1 applyDelta(delta) {
 2   let consumeNextNewline = false;
 3   this.scroll.update();
 4   let scrollLength = this.scroll.length();
 5   this.scroll.batchStart();
 6   const normalizedDelta = normalizeDelta(delta);
 7 
 8   normalizedDelta.reduce((index, op) => {
 9     const length = op.retain || op.delete || op.insert.length || 1;
10     let attributes = op.attributes || {};    
11     // 1.插入文本
12     if (op.insert != null) {
13       if (typeof op.insert === 'string') {        
14         // 普通文本内容
15         let text = op.insert;        
16         ... // 为了阅读方便，省略非核心代码
17         this.scroll.insertAt(index, text);
18         ... // 为了阅读方便，省略非核心代码
19       } else if (typeof op.insert === 'object') {
20         // 富文本内容
21         const key = Object.keys(op.insert)[0];
22         // There should only be one key
23         if (key == null) return index;
24         this.scroll.insertAt(index, key, op.insert[key]);
25       }
26       scrollLength += length;
27     }    
28     // 2.对文本进行格式化
29     Object.keys(attributes).forEach(name => {
30       this.scroll.formatAt(index, length, name, attributes[name]);
31     });
32     return index + length;
33   }, 0);
34 ... // 为了阅读方便，省略非核心代码  this.scroll.batchEnd();
35   this.scroll.optimize();
36   return this.update(normalizedDelta);
37 }

和咱们猜想的同样，该方法就是用 Delta 的 reduce 方法对传入的 Delta 数据进行迭代，将插入内容和删除内容的逻辑分开了，插入内容的迭代里主要作了两件事：

1. 插入普通文本或富文本内容：insertAt
2. 格式化该文本：formatAt

至此，将 Delta 数据应用和渲染到编辑器中的逻辑，咱们已经解析完毕。
下面作一个总结：

1. setContents 方法自己没有什么逻辑，仅仅是调用了 modify 方法而已
2. 在传入 modify 方法的匿名函数中调用了 Editor 对象的 applyDelta 方法
3. applyDelta 方法对传入的 Delta 数据进行迭代，并依次插入/格式化/删除 Delta 数据所描述的编辑器内容

Scroll如何管理全部的Blot类型？

上一节咱们介绍了 Quill 将 Delta 数据应用和渲染到编辑器中的原理：经过迭代 Delta 中的 ops 数据，将 Delta 行一个一个渲染到编辑器中。

了解到最终内容的插入和格式化都是经过调用 Scroll 对象的方法实现的，Scroll 对象究竟是何方神圣？在编辑器的操做中发挥了什么做用？

Scroll 对象的建立‍

上一节的解析终止于 applyDelta 方法，该方法最终调用了 this.scroll.insertAt 将 Delta 内容插入到编辑器中。

applyDelta 方法定义在 Editor 类中，在 Quill 类的 setContents 方法中被调用，经过查看源码，发现 this.scroll 最初是在 Quill 的构造函数中被赋值的。

 

1 this.scroll = Parchment.create(this.root, {
2   emitter: this.emitter,
3   whitelist: this.options.formats
4 });

 

Scroll 对象是经过调用 Parchment 的 create 方法建立的。

前面两期咱们简单介绍了 Quill 的数据模型 Delta，那么 Parchment 又是什么呢？它跟 Quill 和 Delta 是什么关系？这些疑问咱们先不解答，留着后续详细讲解。

先来简单看下 create 方法是怎么建立 Scroll 对象的，create 方法最终是定义在 parchment 库源码中的 registry.ts 文件中的，就是一个普通的方法：

 1 export function create(input: Node | string | Scope, value?: any): Blot {
 2   // 传入的 input 就是编辑器主体 DOM 元素（.ql-editor），里面包含了编辑器里全部可编辑的实际内容   
 3   // match 是经过 query 方法查询到的 Blot 类，这里就是 Scroll 类  
 4   let match = query(input);
 5   if (match == null) {
 6     throw new ParchmentError(`Unable to create ${input} blot`);
 7   }  
 8   let BlotClass = <BlotConstructor>match;  
 9   let node = input instanceof Node || input['nodeType'] === Node.TEXT_NODE
10     ? input
11     : BlotClass.create(value);
12 
13   // 最后返回 Scroll 对象
14   return new BlotClass(<Node>node, value);
15 }

create 方法的入参是编辑器主体 DOM 元素 .ql-editor，经过调用同文件中的 query 普通方法，查询到 Blot 类是 Scroll 类，查询的大体逻辑就是在一个 map 表里查，最后经过 new Scroll() 返回 Scroll 对象实例，赋值给 this.scroll。

1 {
2   ql-cursor: ƒ Cursor(domNode, selection),  
3   ql-editor: ƒ Scroll(domNode, config), // 这个就是 Scroll 类
4   ql-formula: ƒ FormulaBlot(),
5   ql-syntax: ƒ SyntaxCodeBlock(),
6   ql-video: ƒ Video(),
7 } 

Scroll 类详解

Scroll 类是咱们解析的第一个 Blot 格式，后续咱们将遇到各类形式的 Blot 格式，而且会定义本身的 Blot 格式，用于在编辑器中插入自定义内容，这些 Blot 格式都有相似的结构。

能够简单理解为 Blot 格式是对 DOM 节点的抽象，而 Parchment 是对 HTML 文档的抽象，就像 DOM 节点是构成 HTML 文档的基本单元同样，Blot 是构成 Parchment 文档的基本单元。

好比：DOM 节点是<div>，对其进行封装变成 <div class="ql-editor">，并在其内部封装一些属性和方法，就变成 Scroll 类。

Scroll 类是全部 Blot 的根 Blot，它对应的 DOM 节点也是编辑器内容的最外层节点，全部编辑器内容都被包裹在它之下，能够认为 Scroll 统筹着其余 Blot 对象（实际 Scroll 的父类 ContainerBlot 才是幕后总 BOSS，负责总的调度）。

 

1 <div class="ql-editor" contenteditable="true">
2   <p>
3     Hello
4     <strong>World</strong>
5   </p>
6   ... // 其余编辑器内容
7 </div>

Scroll 类定义在 Quill 源码中的 blots/scroll.js 文件中，以前 applyDelta 方法中经过 this.scroll 调用的 insertAt / formatAt / deleteAt / update / batchStart / batchEnd / optimize 等方法都在 Scroll 类中。

如下是 Scroll 类的定义：

 1 class Scroll extends ScrollBlot {
 2   constructor(domNode, config) {
 3     super(domNode);
 4     ...  
 5   }    
 6 
 7   // 标识批量更新的开始，此时执行 update / optimize 都不会进行实际的更新   
 8   batchStart() {
 9     this.batch = true;  
10   }    
11 
12   // 标识批量更新的结束
13   batchEnd() {
14     this.batch = false;
15     this.optimize();  
16   }    
17 
18   // 在制定位置删除制定长度的内容  
19   // 好比：deleteAt(6, 5) 将删除 "World"  
20   // 在 Quill 的 API 中对应 deleteText(index, length, source) 方法  
21   deleteAt(index, length) {}   
22  
23   // 设置编辑器的可编辑状态  
24   enable(enabled = true) {
25     this.domNode.setAttribute('contenteditable', enabled);  
26   }    
27 
28   // 在制定位置用制定格式格式化制定长度的内容  
29   // 好比：formatAt(6, 5, 'bold', false) 将取消 "World" 的粗体格式  
30   // 在 Quill 的 API 中对应 formatText(index, length, name, value, source) 方法 formatAt(index, length,  format, value) {
31     if (this.whitelist != null && !this.whitelist[format]) return;
32     super.formatAt(index, length, format, value); this.optimize();  
33   }    
34 
35   // 在制定位置插入内容  
36   // 好比：insertAt(11, '\n你好，世界');  
37   // 在 Quill 的 API 中对应 insertText(index, text, name, value, source)  
38   // Quill 中的 insertText 实际上是 Scroll 的 insertAt 和 formatAt 的复合方法  
39   insertAt(index, value, def) {}    
40 
41   // 在某个 Blot 前面插入 Blot  
42   insertBefore(blot, ref) {}    
43 
44   // 弹出当前位置 Blot 路径最外面的叶子 Blot（会改变原数组）
45   leaf(index) { return this.path(index).pop() || [null, -1];  }    
46 
47   // 实际上调用的是父类 ContainerBlot 的 descendant 方法  
48   // 目的是获得当前位置所在的 Blot 对象
49   line(index) {
50     if (index === this.length()) {
51       return this.line(index - 1);
52     }
53     return this.descendant(isLine, index);
54   }    
55 
56   // 获取某一范围的 Blot 对象  
57   lines(index = 0, length = Number.MAX_VALUE) {}    
58 
59   // TODO
60   optimize(mutations = [], context = {}) {
61     if (this.batch === true) return;
62     super.optimize(mutations, context);
63     if (mutations.length > 0) {
64       this.emitter.emit(Emitter.events.SCROLL_OPTIMIZE, mutations, context);
65     }  
66   }    
67 
68   // 实际上调用的是父类 ContainerBlot 的 path 方法  
69   // 目的是获得当前位置的 Blot 路径，并排除 Scroll 本身  
70   // Blot 路径就和 DOM 节点路径是对应的  
71   // 好比：DOM 节点路径 div.ql-editor -> p -> strong，  
72   // 对应 Blot 路径就是 [[Scroll div.ql-editor, 0], [Block p, 0], [Bold strong, 6]]
73   path(index) {
74     return super.path(index).slice(1); // Exclude self  
75   }    
76 
77   // TODO
78   update(mutations) {
79     if (this.batch === true) return;
80     ...  
81   }
82 }
83 
84 Scroll.blotName = 'scroll';
85 Scroll.className = 'ql-editor';
86 Scroll.tagName = 'DIV';
87 Scroll.defaultChild = 'block';
88 Scroll.allowedChildren = [Block, BlockEmbed, Container];
89 
90 export default Scroll;

Scroll 类上定义的静态属性 blotName 和 tagName 是必须的，前者用于惟一标识该 Blot 格式，后者对应于一个具体的 DOM 标签，通常还会定义一个 className，若是该 Blot 是一个父级 Blot，通常还会定义 allowedChildren 用来限制容许的子级 Blot 白名单，不在白名单以内的子级 Blot 对应的 DOM 将没法插入父类 Blot 对应的 DOM 结构里。

Scroll 类中除了定义了插入 / 格式化 / 删除内容的方法以外，定义了一些很实用的用于获取当前位置 Blot 路径和 Blot 对象的方法，以及触发编辑器内容更新的事件。

相应方法的解析都在以上源码的注释里，其中 optimize 和 update 方法涉及 Quill 中的事件和状态变动相关逻辑，放在后续单独进行解析。

关于 Blot 格式的规格定义文档能够参阅如下文章：

https://github.com/quilljs/parchment#blots

我也是初次使用Quill进行富文本编辑器的开发，不免有理解不到位的地方，欢迎你们提意见和建议。

加入咱们

咱们是DevUI团队，欢迎来这里和咱们一块儿打造优雅高效的人机设计/研发体系。招聘邮箱：muyang2@huawei.com。

文/DevUI Kagol

 

往期文章推荐

《现代富文本编辑器Quill的模块化机制》

《Webpack入门——使用Webpack打包Angular项目的一个例子》

《前端开发的积木理论——像搭积木同样作前端开发》