引言
在 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 数据应用和渲染到编辑器中。
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
下面做一个总结:
- setContents 方法本身没有什么逻辑,仅仅是调用了 modify 方法而已
- 在传入 modify 方法的匿名函数中调用了 Editor 对象的 applyDelta 方法
- applyDelta 方法对传入的 Delta 数据进行迭代,并依次插入/格式化/删除 Delta 数据所描述的编辑器内容
Scroll如何管理所有的Blot类型?
了解到最终内容的插入和格式化都是通过调用 Scroll 对象的方法实现的,Scroll 对象到底是何方神圣?在编辑器的操作中发挥了什么作用?
Scroll 对象的创建
上一节的解析终止于 applyDelta 方法,该方法最终调用了 this.scroll.insertAt 将 Delta 内容插入到编辑器中。this.scroll = Parchment.create(this.root, { emitter: this.emitter, whitelist: this.options.formats });Scroll 对象是通过调用 Parchment 的 create 方法创建的。
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 格式都有类似的结构。<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 类中。
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 结构里。
加入我们
我们是DevUI团队,欢迎来这里和我们一起打造优雅高效的人机设计/研发体系。招聘邮箱:[email protected]。
文/DevUI Kagol
往期文章推荐