搜外网>搜外问答>问答页面

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

引言

在 Web 开发领域,富文本编辑器( Rich Text Editor )是一个使用场景非常广,又非常复杂的组件。

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

Quill 是一个很不错的选择。

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

Quill描述编辑器内容的方式

Quill将Delta渲染到DOM的基本原理

Scroll类管理所有子Blot的基本原理

Quill如何描述编辑器内容?

Quill简介

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

Quill 使用起来也非常方便,简单几行代码就可以创建一个基本的编辑器:

<script>

  var quill = new Quill('#editor', {

    theme: 'snow'

  });</script>

Quill如何描述格式化的文本

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

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

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

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

比如编辑器里面有"Hello World":

用 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 方法的匿名函数。

该函数主要做了三件事:

把编辑器里面原有的内容全部删除

应用传入的 Delta 数据,将其渲染到编辑器中

返回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 数据进行迭代,将插入内容和删除内容的逻辑分开了,插入内容的迭代里主要做了两件事:

插入普通文本或富文本内容:insertAt

格式化该文本:formatAt

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

setContents 方法本身没有什么逻辑,仅仅是调用了 modify 方法而已

在传入 modify 方法的匿名函数中调用了 Editor 对象的 applyDelta 方法

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 = <BlotConstructor>match;  

  let node = input instanceof Node || input['nodeType'] === Node.TEXT_NODE

    ? input

    : BlotClass.create(value);

 

  // 最后返回 Scroll 对象

  return new BlotClass(<Node>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 节点是<div>,对其进行封装变成 <div class="ql-editor">,并在其内部封装一些属性和方法,就变成 Scroll 类。

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

 

<div class="ql-editor" contenteditable="true">

  <p>

    Hello

    <strong>World</strong>

  </p>

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

</div>

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 中的事件和状态变更相关逻辑,放在后续单独进行解析。

追加问题
    4 人参与回答
A 0湖北楚胜汽车.谢非
A 0湖北 · 环卫洒水车、垃圾车、压缩式垃圾车、扫路车、清扫车等专用车销售

你这个是啥啊

SEO培训招生中
161