现代富文本编辑器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 使用起来也非常方便，简单几行代码就可以创建一个基本的编辑器：

Quill如何描述格式化的文本

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

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

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

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

比如编辑器里面有"HelloWorld"：

用 Delta 进行描述如下：

{
  "ops": [
    { "insert": "Hello " },
    { "insert": "World", "attributes": { "bold": true } },
    { "insert": "\n" }
  ]
}

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

Quill如何描述内容的变化

Delta 非常简洁，但却极富表现力。

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

3种动作：

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

1种属性：

• attributes：格式属性

比如我们把加粗的"World"改成红色的文字"World"，这个动作用 Delta 描述如下：

{
  "ops": [
    { "retain": 6 },
    { "retain": 5, "attributes": { "color": "#ff0000" } }
  ]
}

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

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

{
  "ops": [
    { "retain": 6 },
    { "delete": 5 }
  ]
}

Quill如何描述富文本内容

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

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

{
  "ops": [
    { "insert": { "image": "https://quilljs.com/assets/images/logo.svg" } },
    { "insert": "\n" }
  ]
}

比如公式：

{ 
  "ops": [ 
    { "insert": { "formula": "e=mc^2" } }, 
    { "insert": "\n" } 
  ]
}

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

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

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

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

setContents 初探

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

还是用上一期的 Delta 数据作为例子：

const delta = {  "ops": [
    { "insert": "Hello " },
    { "insert": "World", "attributes": { "bold": true } },
    { "insert": "\n" } ]
}

当使用 new Quill() 创建好 Quill 的实例之后，我们就可以调用它的 API 啦。

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

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

quill.setContents(delta);

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

setContents 源码

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

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

使用 call 方法调用 modify 是为了改变其内部的 this 指向，这里指向的是当前的 Quill 实例，因为 modify 方法并不是定义在 Quill 类中的，所以需要这么做。

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

该函数主要做了三件事：

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

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

applyDelta 方法解析

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

它的实现我们大概也可以猜测就是：循环 Delta 里的 ops 数组，一个一个地应用到编辑器中。

它的源码一共54行，大致如下：

applyDelta(delta) {
  let consumeNextNewline = false;
  this.scroll.update();
  let scrollLength = this.scroll.length();
  this.scroll.batchStart();
  const normalizedDelta = normalizeDelta(delta);

  normalizedDelta.reduce((index, op) => {
    const length = op.retain || op.delete || op.insert.length || 1;
    let attributes = op.attributes || {};    
    // 1.插入文本
    if (op.insert != null) {
      if (typeof op.insert === 'string') {        
        // 普通文本内容
        let text = op.insert;        
        ... // 为了阅读方便，省略非核心代码
        this.scroll.insertAt(index, text);
        ... // 为了阅读方便，省略非核心代码
      } else if (typeof op.insert === 'object') {
        // 富文本内容
        const key = Object.keys(op.insert)[0];
        // There should only be one key
        if (key == null) return index;
        this.scroll.insertAt(index, key, op.insert[key]);
      }
      scrollLength += length;
    }    
    // 2.对文本进行格式化
    Object.keys(attributes).forEach(name => {
      this.scroll.formatAt(index, length, name, attributes[name]);
    });
    return index + length;
  }, 0);
... // 为了阅读方便，省略非核心代码  this.scroll.batchEnd();
  this.scroll.optimize();
  return this.update(normalizedDelta);
}

和我们猜测的一样，该方法就是用 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 的构造函数中被赋值的。

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

Scroll 对象是通过调用 Parchment 的 create 方法创建的。

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

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

export function create(input: Node | string | Scope, value?: any): Blot {
  // 传入的 input 就是编辑器主体 DOM 元素（.ql-editor），里面包含了编辑器里所有可编辑的实际内容   
  // match 是通过 query 方法查询到的 Blot 类，这里就是 Scroll 类  
  let match = query(input);
  if (match == null) {
    throw new ParchmentError(`Unable to create ${input} blot`);
  }  
  let BlotClass = match;  
  let node = input instanceof Node || input['nodeType'] === Node.TEXT_NODE
    ? input
    : BlotClass.create(value);

  // 最后返回 Scroll 对象
  return new BlotClass(node, value);
}

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

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

Scroll 类详解

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

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

比如：DOM 节点是

，对其进行封装变成

，并在其内部封装一些属性和方法，就变成 Scroll 类。

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

  

    Hello
    World
  
  ... // 其他编辑器内容

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

以下是 Scroll 类的定义：

class Scroll extends ScrollBlot {
  constructor(domNode, config) {
    super(domNode);
    ...  
  }    

  // 标识批量更新的开始，此时执行 update / optimize 都不会进行实际的更新   
  batchStart() {
    this.batch = true;  
  }    

  // 标识批量更新的结束
  batchEnd() {
    this.batch = false;
    this.optimize();  
  }    

  // 在制定位置删除制定长度的内容  
  // 比如：deleteAt(6, 5) 将删除 "World"  
  // 在 Quill 的 API 中对应 deleteText(index, length, source) 方法  
  deleteAt(index, length) {}   
 
  // 设置编辑器的可编辑状态  
  enable(enabled = true) {
    this.domNode.setAttribute('contenteditable', enabled);  
  }    

  // 在制定位置用制定格式格式化制定长度的内容  
  // 比如：formatAt(6, 5, 'bold', false) 将取消 "World" 的粗体格式  
  // 在 Quill 的 API 中对应 formatText(index, length, name, value, source) 方法 formatAt(index, length,  format, value) {
    if (this.whitelist != null && !this.whitelist[format]) return;
    super.formatAt(index, length, format, value); this.optimize();  
  }    

  // 在制定位置插入内容  
  // 比如：insertAt(11, '\n你好，世界');  
  // 在 Quill 的 API 中对应 insertText(index, text, name, value, source)  
  // Quill 中的 insertText 其实是 Scroll 的 insertAt 和 formatAt 的复合方法  
  insertAt(index, value, def) {}    

  // 在某个 Blot 前面插入 Blot  
  insertBefore(blot, ref) {}    

  // 弹出当前位置 Blot 路径最外面的叶子 Blot（会改变原数组）
  leaf(index) { return this.path(index).pop() || [null, -1];  }    

  // 实际上调用的是父类 ContainerBlot 的 descendant 方法  
  // 目的是得到当前位置所在的 Blot 对象
  line(index) {
    if (index === this.length()) {
      return this.line(index - 1);
    }
    return this.descendant(isLine, index);
  }    

  // 获取某一范围的 Blot 对象  
  lines(index = 0, length = Number.MAX_VALUE) {}    

  // TODO
  optimize(mutations = [], context = {}) {
    if (this.batch === true) return;
    super.optimize(mutations, context);
    if (mutations.length > 0) {
      this.emitter.emit(Emitter.events.SCROLL_OPTIMIZE, mutations, context);
    }  
  }    

  // 实际上调用的是父类 ContainerBlot 的 path 方法  
  // 目的是得到当前位置的 Blot 路径，并排除 Scroll 自己  
  // Blot 路径就和 DOM 节点路径是对应的  
  // 比如：DOM 节点路径 div.ql-editor -> p -> strong，  
  // 对应 Blot 路径就是 [[Scroll div.ql-editor, 0], [Block p, 0], [Bold strong, 6]]
  path(index) {
    return super.path(index).slice(1); // Exclude self  
  }    

  // TODO
  update(mutations) {
    if (this.batch === true) return;
    ...  
  }
}

Scroll.blotName = 'scroll';
Scroll.className = 'ql-editor';
Scroll.tagName = 'DIV';
Scroll.defaultChild = 'block';
Scroll.allowedChildren = [Block, BlockEmbed, Container];

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团队，欢迎来这里和我们一起打造优雅高效的人机设计/研发体系。招聘邮箱：[email protected]。

文/DevUI Kagol

往期文章推荐

• 《现代富文本编辑器Quill的模块化机制》
• 《微前端在企业级应用中的实践(上)》
• 《前端快速建⽴Mock App》