qrcode

马上订阅,开启修仙之旅

Quill 富文本编辑器简介

什么是 Quill

Quill 是一个免费的,开源的 WYSIWYG (What You See Is What You Get)编辑器,专为现代网络而打造。凭借其模块化架构和富有表现力的 API,你可完全自定义以满足任何需求。

为什么需要 Quill

内容创建从一开始就是网络的核心。 <textarea> 为几乎任何 Web 应用程序提供原生和基础的解决方案。但在某些时候,你可能需要为输入的文本添加格式。这是富文本编辑器所擅长的地方。虽然有许多解决方案可供选择,但 Quill 带来了一些值得深思的现代的想法,它拥有以下特点:

API 驱动设计

富文本编辑器旨在帮助人们编写文本。令人惊讶的是,大多数富文本编辑器不知道用户编写了什么文本。这些编辑器通过和 Web 开发人员一样的方式来查看内容:DOM。由于 DOM 是一种树形结构,由不同的节点组成,而文本是由行、单词和字符组成,这导致了它们之间存在差异。

目前没有以字符为度量单位的 DOM API。由于这个限制,大多数富文本编辑器不能回答诸如:

“这个范围内有什么文字?” 或者 “光标处是粗体吗?”

这些简单问题。这使得在现有基础上,尝试打造丰富的编辑体验是一件非常困难和难受的事情。

Quill 专为编辑和字符设计的,并在这些以自然文本为中心的单元之上构建其API。要找出某些文字是否是粗体,Quill 不需要遍历 DOM 查找 <b> 或者 <strong> 节点或者一个 font-weight 样式属性,只需调用 getFormat(5, 1)。它的所有核心 API 调用都允许任意索引和长度进行访问或修改。其事件 API 还会以直观的 JSON 格式报告更改。而无需解析 HTML 或者比较 DOM 树差异。

自定义内容和格式

过去评估富文本编辑器就像比较所需格式的清单一样简单。衡量一个富文本编辑器好坏的指标就是它所能支持的格式。这仍然是一个重要的衡量标准,但下限接近无穷大。

文本不再只是用于打印。它被编辑后并在网络上(比纸张更丰富的画布)进行呈现。内容可以是实时的,交互式的,甚至是协作的。只有一些富文本编辑器能够支持简单的媒体,如图像和视频;但几乎都不能嵌入推文或交互式图表。然而,这是网络发展的方向:更丰富,更具互动性。支持内容创建的工具需要考虑这些应用场景。

Quill 公开了自己的文档模型,这是对 DOM 的强大抽象,允许扩展和自定义。Quill 可以支持的格式和内容是没有上限的。用户已经使用它来添加嵌入式幻灯片,交互式清单和 3D 模型。

跨平台

跨平台支持对许多 Javascript 库来说是很重要的,对于 Quill 来说,要实现跨平台,它在不同平台上就必须以相同的方式运行或工作。功能不仅是跨平台的考虑因素,同时也需要考虑用户和开发人员的体验。如果某些内容在 OSX 上的 Chrome 中生成特定标记,则会在 IE 上产生相同的标记。如果在 Windows 上的 Firefox 中保留了粗体样式,它将被保留在移动端的 Safari 浏览器上。

简单易用

所有这些优点都来源于易于使用的包。Quill 附带了合理的默认设置,你只需几行 Javascript 代码即可立即使用它:

1
2
3
4
var quill = new Quill('#editor', {
modules: { toolbar: true },
theme: 'snow'
});

如何下载 Quill

你可以通过 CDN、NPM 或克隆 `git@github.com:quilljs/quill.git` 项目的方式来下载 Quill。这里我们简单介绍一下 CDN 和 NPM 的方式:

CDN

1
2
3
4
5
6
7
8
9
10
11
<!-- Main Quill library -->
<script src="//cdn.quilljs.com/1.3.6/quill.js"></script>
<script src="//cdn.quilljs.com/1.3.6/quill.min.js"></script>

<!-- Theme included stylesheets -->
<link href="//cdn.quilljs.com/1.3.6/quill.snow.css" rel="stylesheet">
<link href="//cdn.quilljs.com/1.3.6/quill.bubble.css" rel="stylesheet">

<!-- Core build with no theme, formatting, non-essential modules -->
<link href="//cdn.quilljs.com/1.3.6/quill.core.css" rel="stylesheet">
<script src="//cdn.quilljs.com/1.3.6/quill.core.js"></script>

NPM

1
$ npm install quill@1.3.6 --save

以 CDN 的方式为例,在项目中,引入以下代码即可以快速集成 Quill 编辑器,具体代码如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
<!-- 引入quill样式文件 -->
<link href="https://cdn.quilljs.com/1.3.6/quill.snow.css" rel="stylesheet">

<!-- 创建编辑器容器 -->
<div id="editor">
<p>Hello World!</p>
<p>Some initial <strong>bold</strong> text</p>
<p><br></p>
</div>

<!-- 引入quill脚本文件 -->
<script src="https://cdn.quilljs.com/1.3.6/quill.js"></script>

<!-- 初始化Quill编辑器 -->
<script>
var quill = new Quill('#editor', {
theme: 'snow'
});
</script>

如何配置 Quill

Quill 允许通过多种方式来定制它以满足你的需求,下面我们来介绍一下 Quill 所支持的配置项。

容器

Quill 需要一个容器,用于挂载编辑器。你可以传入 CSS 选择器或者 DOM 元素:

  • CSS 选择器
1
var editor = new Quill('.editor');  // CSS选择器
  • DOM 元素
1
2
3
4
5
var container = document.getElementById('editor');
var editor = new Quill(container);
// 或
var container = $('.editor').get(0);
var editor = new Quill(container);

配置项

通过传入一个配置项对象来配置 Quill:

1
2
3
4
5
6
7
8
9
10
11
var options = {
debug: 'info',
modules: {
toolbar: '#toolbar'
},
placeholder: 'Compose an epic...',
readOnly: true,
theme: 'snow'
};

var editor = new Quill('#editor', options);

该配置对象对应的接口模型定义如下:

1
2
3
4
5
6
7
8
9
10
11
12
// quill/index.d.ts
export interface QuillOptionsStatic {
debug?: string | boolean;
modules?: StringMap;
placeholder?: string;
readOnly?: boolean;
theme?: string;
formats?: string[];
bounds?: HTMLElement | string;
scrollingContainer?: HTMLElement | string;
strict?: boolean;
}

下面我们介绍一下几个主要的选项:

bounds

  • Default:document.body

DOM 元素或者一个 DOM 元素所对应的 CSS 选择器,其中编辑器的 UI 元素(例如:tooltips)应该被包含其中。目前,只考虑左右边界。

debug

  • Default:warn

debug 的开关。注意:debug 是一个静态方法并且会影响同一个页面的其它编辑器实例。警告和错误信息是默认启用的。

formats

  • Default:All formats

在编辑器中允许的格式白名单。请参阅格式化以获取完整列表。

modules

包含的模块和相应的选项。请参阅模块以获取更多信息。

placeholder

  • Default:None

编辑器内容为空时显示的占位符。

readOnly

  • Default:false

是否以只读模式实例化编辑器。

scrollingContainer

  • Default:null

DOM 元素或者一个 DOM 元素所对应的 CSS 选择器,用于指定哪个容器拥有滚动条(例如:overflow-y: auto)当 Quill 设置为自适应高度时,需要修复滚动跳跃的问题,并且由另一个父容器负责滚动。

theme

使用的主题名称。内置的选项有 “bubble” 和 “snow” 。无效或者假值将加载默认的最小主题。注意:主题的特定样式仍然需要手动引入。请参阅主题了解更多信息。

格式化

Quill 支持多种格式化方式,即 UI 控件和 API 调用。默认情况下,所有格式都已启用并允许存在于 Quill 编辑器中,并且可以使用 formats 选项进行配置。这与在工具栏中添加控件是不一样的。比如,你可以配置 Quill 以允许将粗体内容粘贴到工具栏上没有包含粗体按钮的编辑器中。

Inline

  • 背景颜色(Background Color)- background
  • 粗体(Bold)- bold
  • 颜色(Color)- color
  • 字体(Font) - font
  • 内联代码(Inline Code)- code
  • 斜体(Italic)- italic
  • 链接(Link)- link
  • 大小(Size)- size
  • 删除线(Strikethrough)- strike
  • 上标/下标(Superscript/Subscript) - script
  • 下划线(Underline)- underline

Block

  • 引用(Blockquote)- blockquote
  • 标题(Header)- header
  • 缩进(Indent)- indent
  • 列表(List)- list
  • 对齐方式(Text Alignment)- align
  • 文字方向(Text Direction)- direction
  • 代码块(Code Block )- code-block

Embeds

  • 公式(Formula)- formula (requires KaTex
  • 图片(Image)- image
  • 视频(Video)- video

在 Quill 中允许通过模块来定制 Quill 的行为和功能,最后我们就来简单介绍一下如何使用和扩展模块。

如何使用或扩展模块

常用模块

Quill 官方提供了以下模块:

  • 工具栏
  • 键盘
  • 历史记录
  • 剪贴板
  • 语法高亮

模块用法简介

  1. 工具栏模块

工具栏模块允许用户方便地格式化 Quill 编辑器中输入的内容。

1
2
3
4
5
6
7
8
9
10
var quill = new Quill('#editor', {
modules: {
toolbar: {
container: '#toolbar',
handlers: {
bold: customBoldHandler
}
}
}
});

由于 container 属性很常用,也可以使用以下简写形式:

1
2
3
4
5
6
var quill = new Quill('#editor', {
modules: {
// 与 { toolbar: { container: '#toolbar' }} 等价
toolbar: '#toolbar'
}
});

浏览官方 Toobar 文档,了解工具栏模块详细的信息。

  1. 键盘模块

键盘模块用于为特定上下文中的键盘事件启用自定义行为。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
var bindings = {
// This will overwrite the default binding also named 'tab'
tab: {
key: 9,
handler: function() {
// Handle tab
}
}
}

var quill = new Quill('#editor', {
modules: {
keyboard: {
bindings: bindings
}
}
});

浏览官方 Keyboard 文档,了解键盘模块详细的信息。

  1. 历史模块

历史记录模块负责处理 Quill 的撤消和重做。

1
2
3
4
5
6
7
8
9
10
var quill = new Quill('#editor', {
modules: {
history: {
delay: 2000, // 在2000毫秒内的更改将被合并为单次更改
maxStack: 500, // 历史记录撤销/重做堆栈的大小
userOnly: true // 仅撤销或重做用户的更改。
}
},
theme: 'snow'
});
  1. 剪贴板模块

剪贴板模块用于处理 Quill 和外部应用程序之间的复制,剪切和粘贴。

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

语法高亮模块通过自动检测和应用语法突出显示来增强代码块格式。该模块依赖 highlight.js 库用作解析和格式化代码块。

1
2
3
4
5
6
7
8
9
10
11
hljs.configure({   // optionally configure hljs
languages: ['javascript', 'ruby', 'python']
});

var quill = new Quill('#editor', {
modules: {
syntax: true, // Include syntax module
toolbar: [['code-block']] // Include button in toolbar
},
theme: 'snow'
});

模块扩展

Quill 中的模块可以被扩展和重新注册,从而替换原始模块。甚至可以重新注册和替换所需的模块。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
var Clipboard = Quill.import('modules/clipboard');
var Delta = Quill.import('delta');

class PlainClipboard extends Clipboard {
convert(html = null) {
if (typeof html === 'string') {
this.container.innerHTML = html;
}
let text = this.container.innerText;
this.container.innerHTML = '';
return new Delta().insert(text);
}
}

Quill.register('modules/clipboard', PlainClipboard, true);

// Will be created with instance of PlainClipboard
var quill = new Quill('#editor');

总结

Quill 是一款功能强大的富文本编辑器,本文基于 Quill 的官方文档简单介绍了该编辑器相关的基础知识。对于一些普通的应用场景,Quill 可以开箱即用。若需要支持快捷键、剪贴板、语法高亮或其它特性,可以方便地引入官方模块或第三方模块。如果已有的模块不能满足实际需求,我们还可以灵活地扩展已有模块或自定义模块。

如果小伙伴们也对 Quill 感兴趣,建议在熟悉官方文档及相关 API 的基础上,在深入了解一下 DeltaParchment 的概念。


欢迎小伙伴们订阅前端修仙之路,及时阅读 Angular、RxJS、TypeScript 和 Node.js 最新文章。

qrcode