本教程详细介绍了如何通过定制Quill.js的链接和标题模块来自动生成文章目录（TOC）。通过修改链接行为以支持页面内跳转，并为标题标签自动分配唯一ID，开发者可以构建一个功能完善、用户友好的富文本编辑器，从而提升长篇文章的可读性和导航性。
引言：Quill.js与目录生成的需求
Quill.js是一款功能强大的富文本编辑器，提供了丰富的API和高度可定制性，使其能够满足各种复杂的编辑需求。然而，在处理长篇文章时，自动生成目录（Table of Contents, TOC）是一个常见的需求，它能显著提升文章的可读性和导航性。Quill.js本身并未原生提供自动生成TOC的功能，主要原因在于两个核心限制：
- 链接默认行为： Quill.js的链接模块默认会将所有链接设置为 target="_blank"，即在新标签页中打开。这对于外部链接是理想的，但对于页面内的锚点链接（例如目录项）来说，则需要保持在当前页面内跳转。
- 标题标签缺乏ID： HTML中的锚点链接需要目标元素具有唯一的 id 属性。Quill.js在生成标题（如 <h1>, <h2> 等）时，并不会自动为其添加 id 属性，这使得直接创建锚点链接变得困难。
为了克服这些限制并实现Quill.js的动态目录生成，我们需要对Quill.js的链接和标题模块进行定制。
定制链接模块：支持页面内跳转
Quill.js的链接模块（formats/link）负责处理所有链接的创建和格式化。为了让目录项能够实现在当前页面内跳转，我们需要修改其默认行为，使其能够识别内部锚点链接（以 # 开头的 href）并移除 target="_blank" 属性。
以下是定制链接模块的示例代码：
var Link = Quill.import('formats/link');
class MyLink extends Link {
static create(value) {
let node = Link.create(value);
value = Link.sanitize(value); // 清理链接值
node.setAttribute('href', value);
// 如果链接以 '#' 开头，则移除 target 属性，实现页面内跳转
if (value.startsWith("#")) {
node.removeAttribute('target');
} else {
// 否则，保持默认的在新标签页打开
node.setAttribute("target", "_blank");
}
return node;
}
format(name, value) {
super.format(name, value);
if (name !== this.statics.blotName || !value) {
return;
}
// 在格式化时也应用相同的逻辑
if (value.startsWith("#")) {
this.domNode.removeAttribute("target");
} else {
this.domNode.setAttribute("target", "_blank");
}
}
}
// 注册定制后的链接模块
Quill.register(MyLink);通过这段代码，我们创建了一个名为 MyLink 的新链接类，它继承自Quill的默认 Link 类。在 create 方法中，我们检查链接的 href 值。如果它以 # 开头，我们就会移除 target 属性，从而允许浏览器执行页面内跳转。format 方法也做了类似的处理，确保在链接被修改或更新时，其 target 属性也能正确调整。
定制标题模块：自动生成唯一ID
为了让标题能够作为锚点链接的目标，每个标题元素都需要一个唯一的 id 属性。Quill.js的标题模块（formats/header）默认不会添加这些ID。我们需要扩展这个模块，使其在创建标题时自动分配一个唯一的ID。
首先，我们需要一个生成唯一ID的辅助函数：
var ids = []; // 用于存储已生成的ID，确保唯一性
function getRandomId(domNode) {
let _id = Math.random().toString(16).slice(2, 9); // 生成一个随机的短字符串作为ID
// 可以在这里添加循环检查ids数组，确保生成的ID是唯一的，避免冲突
// 例如：while (ids.includes(_id)) { _id = Math.random().toString(16).slice(2, 9); }
ids.push(_id);
return _id;
}接下来，我们创建 MyHeader 类来定制标题模块：
var Header = Quill.import('formats/header');
class MyHeader extends Header {
constructor(domNode) {
super(domNode);
// 在标题DOM节点创建时，为其设置一个唯一的ID
domNode.setAttribute('id', getRandomId(domNode));
this.cache = {}; // 可用于存储其他自定义属性
}
static create(value) {
// 调用父类的create方法创建DOM节点
const node = super.create(value);
return node;
}
static formats(domNode) {
// 允许Quill获取自定义的id属性
return {
id: domNode.getAttribute("id")
};
}
}
// 注册定制后的标题模块
Quill.register("formats/header", MyHeader);
MyHeader.blotName = "header"; // 确保blotName正确设置这段代码通过 MyHeader 类扩展了Quill的标题模块。在 MyHeader 的 constructor 中，我们调用 super(domNode) 完成父类初始化后，立即使用 domNode.setAttribute('id', getRandomId(domNode)) 为标题元素设置一个唯一的 id。这样，每当用户在Quill编辑器中创建或修改标题时，它都会自动获得一个可用于锚点链接的ID。
动态生成与插入目录
完成链接和标题模块的定制后，Quill编辑器中的标题将自动带有唯一的ID，并且内部锚点链接也能正常工作。现在，我们需要实现一个机制来遍历编辑器内容，提取所有标题信息，并据此生成目录。
这个过程通常在编辑器内容发生变化后（例如 editor.on('text-change', ...)）或者在页面加载时执行。
- 获取编辑器内容： 可以通过 quill.getContents() 获取Delta对象，或者直接通过 quill.root.innerHTML 获取HTML内容。对于生成目录，直接操作DOM通常更简单。
- 识别标题标签： 遍历Quill编辑器内容中的所有HTML元素，筛选出 h1、h2、h3 等标题标签。
- 提取信息： 对于每个标题标签，获取其文本内容 (innerText) 和其自动生成的 id 属性。
- 构建目录列表： 使用这些信息动态创建 <ul> 或 <ol> 列表，其中每个列表项包含一个 <a> 标签，其 href 指向标题的 id（例如 href="#[header_id]"），链接文本为标题的文本内容。
- 插入目录： 将生成的目录列表插入到页面中预定义的目录容器元素内。
以下是一个简化的JavaScript函数，演示如何从Quill编辑器内容中提取标题并生成目录：
function generateTableOfContents(quillEditorInstance, tocContainerId) {
const editorContent = quillEditorInstance.root; // 获取编辑器的DOM根元素
const headers = editorContent.querySelectorAll('h1, h2, h3, h4, h5, h6'); // 选择所有标题标签
let tocHtml = '<ul>';
headers.forEach(header => {
const id = header.getAttribute('id');
const text = header.innerText;
const tagName = header.tagName.toLowerCase(); // 获取标题标签名，如h1, h2
// 可以根据标签名添加缩进或样式，例如：
let className = `toc-level-${tagName.replace('h', '')}`;
tocHtml += `<li class="${className}"><a href="#${id}">${text}</a></li>`;
});
tocHtml += '</ul>';
const tocContainer = document.getElementById(tocContainerId);
if (tocContainer) {
tocContainer.innerHTML = tocHtml;
}
}
// 示例用法：
// const quill = new Quill('#editor', { /* options */ });
// quill.on('text-change', () => {
// generateTableOfContents(quill, 'table-of-contents-container');
// });
// 首次加载时也生成一次
// generateTableOfContents(quill, 'table-of-contents-container');在HTML中，你需要一个用于显示目录的容器：
<div id="table-of-contents-container">
<!-- 动态生成的目录将插入到这里 -->
</div>
<div id="editor">
<!-- Quill 编辑器将在此处初始化 -->
</div>注意事项与最佳实践
- ID唯一性： getRandomId 函数生成的是随机ID。在大型应用中，应考虑更健壮的ID生成策略，例如结合时间戳、用户ID或内容哈希，以确保在极端情况下ID的全局唯一性。
- 目录更新机制： 目录应在编辑器内容发生变化时实时更新。通过监听Quill的 text-change 事件，可以在每次内容修改后重新调用 generateTableOfContents 函数。
-
用户体验优化：
- 平滑滚动： 可以使用CSS scroll-behavior: smooth; 或JavaScript实现点击目录项时的平滑滚动效果。
- 高亮当前章节： 随着用户滚动页面，可以根据当前视口中的标题，高亮显示目录中对应的项，提升用户体验。
- 目录层级： 根据 h1 到 h6 的不同级别，在目录中添加视觉上的缩进，清晰展示文章结构。
- 性能考虑： 对于包含大量标题的超长文章，频繁地重新生成整个目录可能会影响性能。可以考虑优化更新逻辑，例如只在必要时（如添加/删除标题）才完全重建目录，或采用虚拟DOM等技术。
- 服务端渲染： 如果文章内容需要在服务器端渲染，确保在服务器端也能正确地为标题生成ID，并构建目录。
总结
通过定制Quill.js的链接和标题模块，我们成功克服了其在自动生成目录方面的原生限制。定制后的链接模块确保了锚点链接的页面内跳转，而定制后的标题模块则为每个标题自动赋予了唯一的ID。结合动态生成目录的JavaScript逻辑，我们可以为Quill.js编辑器创建出功能完善、导航友好的文章目录，极大地提升了长篇文章的可读性和用户体验。这种方法充分展示了Quill.js高度可定制的强大能力，允许开发者根据具体需求进行深度扩展。
