本教程详细介绍了如何在quill.js富文本编辑器中实现自动生成目录（toc）功能。通过定制quill的链接模块以支持页面内锚点跳转，并修改标题模块自动为标题元素添加唯一id，解决了quill原生功能不足的问题，为构建动态、可导航的文章结构提供了专业解决方案。
Quill.js作为一款功能强大的富文本编辑器，其高度可定制性使其能够满足各种复杂需求。然而，在实现文章目录（Table of Contents, TOC）这样的高级功能时，Quill的默认行为存在一些限制。主要挑战在于：
- 链接行为不符: Quill默认的链接模块会将所有外部链接设置为target="_blank"，这对于页面内部的锚点跳转（如TOC）并不适用，因为我们需要链接在当前页面内跳转。
-
标题缺乏唯一ID: Quill生成的标题标签（如
,
等）默认不包含唯一的id属性，而id是创建锚点链接的基础。
为了克服这些限制并实现自动化的TOC功能，我们需要对Quill的链接和标题模块进行定制。
1. 定制链接模块以支持页面内锚点
Quill的Link模块需要被修改，以便当链接目标是页面内的锚点（即href以#开头）时，移除target="_blank"属性，确保链接在当前页面内跳转。
以下是定制Link模块的代码示例：
// 导入Quill的Link格式
var Link = Quill.import('formats/link');
/**
* 自定义链接模块，处理页面内锚点链接
*/
class MyLink extends Link {
/**
* 创建链接节点时调用
* @param {string} value - 链接的href值
* @returns {HTMLElement} 创建的链接DOM节点
*/
static create(value) {
let node = Link.create(value); // 调用父类的create方法创建节点
value = Link.sanitize(value); // 对链接值进行安全净化
node.setAttribute('href', value);
// 如果链接以 '#' 开头，表示是页面内锚点，移除 target 属性
if (value.startsWith("#")) {
node.removeAttribute('target');
} else {
// 否则，保持默认的 target="_blank" 行为
node.setAttribute("target", "_blank");
}
return node;
}
/**
* 格式化链接时调用
* @param {string} name - 格式名称 (通常是 blotName)
* @param {string} value - 格式值 (链接的href)
*/
format(name, value) {
super.format(name, value); // 调用父类的format方法
// 确保是链接格式且有值
if (name !== this.statics.blotName || !value) {
return;
}
// 再次检查链接是否为锚点，并相应设置 target 属性
if (value.startsWith("#")) {
this.domNode.removeAttribute("target");
} else {
this.domNode.setAttribute("target", "_blank");
}
}
}
// 注册自定义的链接模块
Quill.register(MyLink);这段代码通过继承Link模块并重写其create和format方法，实现了对链接行为的精确控制。当链接href以#开头时，target属性会被移除，从而实现页面内的平滑跳转。
2. 定制标题模块以自动添加唯一ID
为了能够创建锚点链接，每个标题标签都需要一个唯一的id属性。Quill的Header模块默认不提供此功能，因此我们需要对其进行扩展。
以下是定制Header模块的代码示例：
// 存储已生成的ID，用于确保唯一性（简单实现，生产环境可能需要更健壮的ID生成策略）
var ids = [];
/**
* 生成一个随机的唯一ID
* @returns {string} 唯一的ID字符串
*/
function getRandomId() {
let _id = Math.random().toString(16).slice(2, 9);
// 简单检查，如果ID已存在则重新生成，直到唯一
while (ids.includes(_id)) {
_id = Math.random().toString(16).slice(2, 9);
}
ids.push(_id);
return _id;
}
// 导入Quill的Header格式
let Header = Quill.import('formats/header');
/**
* 自定义标题模块，自动为标题添加唯一ID
*/
class MyHeader extends Header {
/**
* 构造函数在Quill创建标题DOM节点时调用
* @param {HTMLElement} domNode - 标题的DOM节点
*/
constructor(domNode) {
super(domNode); // 调用父类构造函数
// 为标题DOM节点设置一个唯一的ID
domNode.setAttribute('id', getRandomId());
this.cache = {}; // 可用于存储其他自定义属性
}
/**
* 静态方法 create，用于创建新的标题 blot
* (这里只是简单调用父类方法，实际ID在构造函数中设置)
* @returns {HTMLElement} 创建的标题DOM节点
*/
static create() {
const node = super.create();
return node;
}
/**
* 静态方法 formats，用于获取标题的格式信息
* @param {HTMLElement} domNode - 标题的DOM节点
* @returns {object} 包含ID属性的对象
*/
static formats(domNode) {
return {
id: domNode.getAttribute("id")
};
}
}
// 注册自定义的标题模块
Quill.register("formats/header", MyHeader);
// 明确指定 blotName，虽然通常Quill会从类名推断
MyHeader.blotName = "header";在这个定制的MyHeader模块中，我们重写了构造函数。每当Quill创建一个新的标题元素时（例如用户选择H1、H2等），MyHeader的构造函数就会被调用，并自动为该标题的DOM节点设置一个通过getRandomId()函数生成的唯一id。
注意事项： getRandomId函数中维护的ids数组是一个简单的全局变量，用于在当前会话中确保ID的唯一性。在生产环境中，特别是在多实例Quill编辑器或需要持久化内容并加载的场景中，可能需要更健壮的ID生成策略，例如基于内容哈希、UUID或结合时间戳的生成方式，以避免ID冲突。
3. 生成并插入目录（TOC）
完成了链接和标题模块的定制后，Quill编辑器中的所有标题都将拥有唯一的id属性，并且链接模块能够正确处理页面内锚点。接下来，你需要编写额外的JavaScript逻辑来实际生成和插入目录。
生成TOC的步骤概览：
- 监听内容变化: 可以在Quill编辑器内容变化时触发TOC的更新，或者在文章保存/渲染时生成。
- 遍历编辑器内容: 使用Quill的API（如editor.getContents()或editor.scroll.domNode.querySelectorAll('h1, h2, h3, h4, h5, h6')）来获取所有标题元素。
- 提取信息: 对于每个标题，提取其文本内容和自动生成的id属性。
-
构建TOC结构: 根据标题的层级（H1、H2等）构建一个嵌套的HTML列表（
- ,
- , ），其中标签的href指向标题的id。
<!-- 示例TOC结构 --> <ul> <li><a href="#unique-id-h1">一级标题文本</a> <ul> <li><a href="#unique-id-h2-1">二级标题文本1</a></li> <li><a href="#unique-id-h2-2">二级标题文本2</a></li> </ul> </li> <li><a href="#unique-id-h1-2">另一个一级标题文本</a></li> </ul> - 插入TOC: 将生成的TOC HTML结构插入到文章的开头、侧边栏或其他指定位置。这可以在Quill编辑器内部实现，也可以在渲染文章的页面上实现。
- , ），其中标签的href指向标题的id。
由于实际的TOC生成逻辑会根据你的应用场景（例如，是在Quill编辑器内部动态显示TOC，还是在文章发布后在前端页面上渲染TOC）而有所不同，这里不提供具体的TOC生成代码。但核心思想是利用定制后的Quill模块提供的id和链接能力。
总结
通过对Quill.js的链接和标题模块进行定制，我们成功解决了在富文本编辑器中实现自动目录功能的核心障碍。自定义链接模块确保了锚点链接的正确行为，而自定义标题模块则为每个标题提供了唯一的id属性。这些定制为后续的TOC生成逻辑奠定了基础，使得开发者能够根据自己的需求，灵活地构建动态、可导航的文章结构，极大地提升了用户体验和文章的可读性。Quill.js强大的模块化设计，使得这类高级功能的实现变得可行且高效。
