使用quill搭建文本编辑器

发表于 分类于 Disqus： 本文字数： 8.5k 阅读时长 ≈ 14 分钟

官网：https://quilljs.com

quill可以是一个文本编辑器JS库或是文本编辑器构建库。它提供了结构化数据方式用脱离语言的方式描述编辑器内容，同时预置了内置插件，支持自定义插件，有助于在此基础上进行和业务相关编辑器开发。

准备工作

关于contenteditable属性，selection对象和range对象的介绍，可以参考这篇文章。

配置

1
2
3
const editor = new Quill("#container");
// 或是直接传入DOM对象
const editor = new Quill(document.body);

quill通常使用上面的方式初始化。在初始化时，支持用丰富的配置项定义生成的编辑器。下面是一个例子。

1
2
3
4
5
6
7
8
9
10
const options = {
    debug: 'info',
    modules: {
        toolbar: '#toolbar'
    },
    placeholder: 'Tell a story...',
    readOnly: false,
    them: 'snow'
}
const editor = new Quill('#container', options);

Quill支持的配置项有：

  • bounds，Quill UI元素的限制范围，默认document.body
  • debug，是Quill.debug的快捷方式，用于打印调试信息，默认级别为warn
  • formats，Quill中允许出现的格式，默认为所有格式，它和toolbar是解耦的
  • modules，注册在Quill中的功能模块和与之对应的配置信息，Quill会有默认配置
  • placeholder，提示信息
  • readOnly，是否可写
  • scrollContainer，编辑器滚动条的父级，默认为编辑器本身
  • strict，版本更新配置，默认为true
  • theme，整体外观，默认为snow，bubble可选

支持的文本格式

分为行内，块级，嵌入式三大类。

  • 行内：加粗/背景色/字体颜色/字体/行内代码/斜体/下划线/删除线/链接/字体大小/上、下标
  • 块级：引用/标题/行首缩进/有序、无序列表/对齐/文本方向/代码块
  • 嵌入式：音频/视频/公式

API

按照由浅入深，分为修改内容，修改格式，选取，编辑器本身，事件，数据模型操作，拓展几大类。涉及到内容修改的都会返回代表更改的delta。

修改内容

涉及到修改时，最后一个参数都可以选择user，api，silent。user类型下，disabled时会没有效果。

  • deleteText，输入起始点和长度，删除特定范围的内容，返回delta类型数据。如quill.deleteText(6, 4)
  • getContents，获取delta格式的编辑器内容，如quill.getContents()
  • getLength，获取文本长度，quill默认会有一个空行，所以默认返回1
  • getText，获取文本内容，跳过非文本如音视频元素，如quill.getText(0, 10)
  • insertEmbed，输入位置，类型，值，插入嵌入式内容，如quill.insertEmbed(10, 'image', 'https://quilljs.com/images/cloud.png')
  • insertText，插入文本，可带格式。如下
    1
    2
    3
    4
    5
    6
    quill.insertText(0, 'Hello', 'bold', true);

    quill.insertText(5, 'Quill', {
      'color': '#ffff00',
      'italic': true
    });
  • setContent，输入delta，重设编辑器内容，需以\n结尾。如下：
    1
    2
    3
    4
    5
    quill.setContents([
      { insert: 'Hello ' },
      { insert: 'World!', attributes: { bold: true } },
      { insert: '\n' }
    ]);
  • setText，设置文本，返回代表改变的delta
  • updateContent，输入delta，更新内容，返回代表更新的delta

修改格式

  • format，设置用户当前所选的文本格式，如quill.format('color', 'red');
  • formatLine，设置给定选择当前整行样式，使用类似format的方法设置样式，也支持直接传入格式对象。类似quill.formatLine(1, 2, { 'align': 'right'})
  • formatText，设置给定范围内文本格式，类似formatLine
  • getFormat，获取给定范围内的格式，没有输入时，返回当前选择的格式
  • removeFormat，移除范围内样式

选取

  • getBounds(index, length = 0)，返回的top、width、height、left相对于编辑器容器而言
  • getSelection(focus = false)，返回用户的选取范围，由index、length组成
  • setSelection(index, length = 0)，设置选区范围，会自动focus，输入null会自动blur

编辑器本身

  • blur，失焦
  • disable，禁用
  • enable(enabled = false)，启用
  • focus，聚焦
  • hasFocus，是否聚焦
  • update，同步用户改动，协同工作时常用

事件

事件通过on方法绑定在quill对象上。

  • text-change，quill内的内容改变时触发，回调函数可以获取delta、oldContent，source。通常来自’user’，source为’silent’时，该事件不会触发。
  • selection-change，回调函数可以获取range，oldRange，source
  • editor-change，上述两个事件触发时触发，即使source为silent

除了on方法，还有once用于绑定一次和off方法解绑。

数据模型操作

  • find，寻找DOM节点对应的quill或Blot对象
  • getIndex，返回文档开头到给定Blot的偏移量
  • getLeafBlot，返回给定位置的Blot
  • getLine，返回给定位置整行的Blot
  • getLines，返回给定范围的Blot

拓展

  • debug，设置调试信息级别，info | log | warn | error
  • import，导出quill相关库，输入相对于quill的路径
    1
    2
    3
    4
    5
    var Parchment = Quill.import('parchment');
    var Delta = Quill.import('delta');

    var Toolbar = Quill.import('modules/toolbar');
    var Link = Quill.import('formats/link');
  • register，注册module到quill中，有下面几种用法
    1
    2
    3
    Quill.register(format: Attributor | BlotDefinintion, supressWarning: Boolean = false)
    Quill.register(path: String, def: any, supressWarning: Boolean = false)
    Quill.register(defs: { [String]: any }, supressWarning: Boolean = false)
  • addContainer，新增容器并返回
  • enable/disable，启用、禁用编辑器

delta

delta是quill中最重要的概念。据介绍所说，quill是“第一个”使用delta（结构化数据）这个概念的。不同于其他大多数文本编辑器需要反复执行修改编辑器中的HTML文档。quill维护一个delta数组，使用JSON数据的方式描述了文档的内容。

使用delta一词，并没有问题，因为可以理解成文档本身是由空内容 + delta一点点得到的。delta主要有两个特性：

  • 权威性，delta和对应的生成结果是一一对应的，没有歧义
  • 压缩性，delta中描述的操作是经过压缩后的

delta中的操作可以分为增、删、修改格式，分别对应insert，delete和retain操作。对文本编辑器的一次改动（真实世界中的改动行为）只可能涉及上述三种行为的一种（Quill并不允许Ctrl多处选中）。其中retain的意义类似于光标的移动，它使得这三种操作并不需要使用index描述，便于Quill做优化和压缩。

delta的操作实际上是对parchment进行的，它类似于vdom，使用JS的数据结构对文本编辑器中可能出现的各元素进行了抽象，称作Blot。Blot有scroll，inline、block、text，break几种。父Blot下必须包含至少一个子Blot，而所有的Blot都包含在一个scroll Blot下。文本编辑器中特定格式的文本块都用特定的Blot表示，每个这样的Blot都必须继承自上面的一种Blot类型。就像通过下面的方式继承了Blot，就可以使对应的行内元素得到对应的编辑器样式元素对应起来，并使用在后面的编辑器里。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
let Inline = Quill.import('blots/inline');

class BoldBlot extends Inline { }
BoldBlot.blotName = 'bold';
BoldBlot.tagName = 'strong';

class ItalicBlot extends Inline { }
ItalicBlot.blotName = 'italic';
ItalicBlot.tagName = 'em';

Quill.register(BoldBlot);
Quill.register(ItalicBlot);

// in your editor

quill.insertText(0, 'Test', { bold: true });
quill.formatText(0, 4, 'italic', true);

类似地，我们定义一个Link Blot。它相比bold，italic不同的是，它需要一个string而不是boolean初始化。因此需要定义create和format两个函数。其中create在构造Blot时使用，value即输入的href，formats将用户的format字段和真实DOM的字段相关联。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
class LinkBlot extends Inline {
  static create(value) {
    let node = super.create();
    // Sanitize url value if desired
    node.setAttribute('href', value);
    // Okay to set other non-format related attributes
    // These are invisible to Parchment so must be static
    node.setAttribute('target', '_blank');
    return node;
  }

  static formats(node) {
    // We will only be called with a node already
    // determined to be a Link blot, so we do
    // not need to check ourselves
    return node.getAttribute('href');
  }
}
LinkBlot.blotName = 'link';
LinkBlot.tagName = 'a';

Quill.register(LinkBlot);

定义引用这样的块级元素时，对应地继承Block Blot即可。和inline Blot不同的是，Block Blot无法嵌套，在对已有的块级元素应用时会替换而不是嵌套绑定在元素上。以Header元素为例，可以指定tagName为一个数组，可以在format时使用1、2的方式指定具体哪种tag。

1
2
3
4
5
6
7
8
9
class HeaderBlot extends Block {
  static formats(node) {
    return HeaderBlot.tagName.indexOf(node.tagName) + 1;
  }
}
HeaderBlot.blotName = 'header';
// Medium only supports two header sizes, so we will only demonstrate two,
// but we could easily just add more tags into this array
HeaderBlot.tagName = ['H1', 'H2'];

类似的，可以在插入embed Blot，这种类型效果是插入在元素中间的新的tag。如Image。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
let BlockEmbed = Quill.import('blots/block/embed');

class ImageBlot extends BlockEmbed {
  static create(value) {
    let node = super.create();
    node.setAttribute('alt', value.alt);
    node.setAttribute('src', value.url);
    return node;
  }

  static value(node) {
    return {
      alt: node.getAttribute('alt'),
      url: node.getAttribute('src')
    };
  }
}
ImageBlot.blotName = 'image';
ImageBlot.tagName = 'img';

// 使用时
let range = quill.getSelection(true);
quill.insertText(range.index, '\n', Quill.sources.USER);
quill.insertEmbed(range.index + 1, 'image', {
    alt: 'Quill Cloud',
    url: 'https://quilljs.com/0.20/assets/images/cloud.png'
}, Quill.sources.USER);
quill.setSelection(range.index + 2, Quill.sources.SILENT);

modules

quill中的module位于quill的应用层。可以通过定制modules，利用quill的功能；或是更改quill内置module，修改quill本身的行为和功能。clipboard、keyboard、history三个module是quill默认加载的。用户完全可以根据业务需求定义自己的module。官网给了简单的例子展示了module的大致骨架：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
Quill.register('modules/counter', function(quill, options) {
  var container = document.querySelector(options.container);
  quill.on('text-change', function() {
    var text = quill.getText();
    if (options.unit === 'word') {
      container.innerText = text.split(/\s+/).length + ' words';
    } else {
      container.innerText = text.length + ' characters';
    }
  });
});

var quill = new Quill('#editor', {
  modules: {
    counter: {
      container: '#counter',
      unit: 'word'
    }
  }
});

只需要定义一个可以接收quill对象的函数即可，在函数内部利用quill事件监听即可完成应用层的建设。

Toolbar和ClipBoard

Toolbar和Clipboard是Quill内置的两个module，对你构建自己的文本编辑器有很大的借鉴意义。

Toolbar用来定制工具栏上的按钮，是自定义编辑器（尤其是业务相关的编辑器）逃不开的一部分。它有几个基本配置：

  • container，放置工具栏的DOM容器
  • handler，点击ToolBar图标时注册的函数，传入Blot的value，通过调用Quill的API完成功能。也可以通过下面方式注册。
1
2
3
// Handlers can also be added post initialization
var toolbar = quill.getModule('toolbar');
toolbar.addHandler('image', showImageUI);

在遇到从别的文本编辑器拷贝内容过来的情况时，需要修改ClipBoard Module中addMatcher的定义。这个方法向ClipBoard中注册了新的Matcher匹配拷贝过来的HTML文本，将之转换为对应的Blot。如：

1
2
3
4
5
6
7
8
quill.clipboard.addMatcher(Node.TEXT_NODE, function(node, delta) {
  return new Delta().insert(node.data);
});

// Interpret a <b> tag as bold
quill.clipboard.addMatcher('.custom-class', function(node, delta) {
  return delta.compose(new Delta().retain(delta.length(), { bold: true }));
});

或者在configuration中，注入新定义的matcher即可。

1
2
3
4
5
6
7
8
9
10
var quill = new Quill('#editor', {
  modules: {
    clipboard: {
      matchers: [
        ['B', customMatcherA],
        [Node.TEXT_NODE, customMatcherB]
      ]
    }
  }
});

参考