首页 > web前端 > js教程 > 正文

使用Quill.js实现动态目录(TOC)生成教程

心靈之曲
发布: 2025-10-14 10:33:01
原创
502人浏览过

使用quill.js实现动态目录(toc)生成教程

本教程详细介绍了如何通过定制Quill.js的链接和标题模块来自动生成文章目录(TOC)。通过修改链接行为以支持页面内跳转,并为标题标签自动分配唯一ID,开发者可以构建一个功能完善、用户友好的富文本编辑器,从而提升长篇文章的可读性和导航性。

引言:Quill.js与目录生成的需求

Quill.js是一款功能强大的富文本编辑器,提供了丰富的API和高度可定制性,使其能够满足各种复杂的编辑需求。然而,在处理长篇文章时,自动生成目录(Table of Contents, TOC)是一个常见的需求,它能显著提升文章的可读性和导航性。Quill.js本身并未原生提供自动生成TOC的功能,主要原因在于两个核心限制:

  1. 链接默认行为: Quill.js的链接模块默认会将所有链接设置为 target="_blank",即在新标签页中打开。这对于外部链接是理想的,但对于页面内的锚点链接(例如目录项)来说,则需要保持在当前页面内跳转。
  2. 标题标签缺乏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的辅助函数:

笔目鱼英文论文写作器
笔目鱼英文论文写作器

写高质量英文论文,就用笔目鱼

笔目鱼英文论文写作器 87
查看详情 笔目鱼英文论文写作器
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', ...))或者在页面加载时执行。

  1. 获取编辑器内容: 可以通过 quill.getContents() 获取Delta对象,或者直接通过 quill.root.innerHTML 获取HTML内容。对于生成目录,直接操作DOM通常更简单。
  2. 识别标题标签: 遍历Quill编辑器内容中的所有HTML元素,筛选出 h1、h2、h3 等标题标签。
  3. 提取信息: 对于每个标题标签,获取其文本内容 (innerText) 和其自动生成的 id 属性。
  4. 构建目录列表: 使用这些信息动态创建 <ul> 或 <ol> 列表,其中每个列表项包含一个 <a> 标签,其 href 指向标题的 id(例如 href="#[header_id]"),链接文本为标题的文本内容。
  5. 插入目录: 将生成的目录列表插入到页面中预定义的目录容器元素内。

以下是一个简化的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>
登录后复制

注意事项与最佳实践

  1. ID唯一性: getRandomId 函数生成的是随机ID。在大型应用中,应考虑更健壮的ID生成策略,例如结合时间戳、用户ID或内容哈希,以确保在极端情况下ID的全局唯一性。
  2. 目录更新机制: 目录应在编辑器内容发生变化时实时更新。通过监听Quill的 text-change 事件,可以在每次内容修改后重新调用 generateTableOfContents 函数。
  3. 用户体验优化:
    • 平滑滚动: 可以使用CSS scroll-behavior: smooth; 或JavaScript实现点击目录项时的平滑滚动效果。
    • 高亮当前章节: 随着用户滚动页面,可以根据当前视口中的标题,高亮显示目录中对应的项,提升用户体验。
    • 目录层级: 根据 h1 到 h6 的不同级别,在目录中添加视觉上的缩进,清晰展示文章结构。
  4. 性能考虑: 对于包含大量标题的超长文章,频繁地重新生成整个目录可能会影响性能。可以考虑优化更新逻辑,例如只在必要时(如添加/删除标题)才完全重建目录,或采用虚拟DOM等技术。
  5. 服务端渲染: 如果文章内容需要在服务器端渲染,确保在服务器端也能正确地为标题生成ID,并构建目录。

总结

通过定制Quill.js的链接和标题模块,我们成功克服了其在自动生成目录方面的原生限制。定制后的链接模块确保了锚点链接的页面内跳转,而定制后的标题模块则为每个标题自动赋予了唯一的ID。结合动态生成目录的JavaScript逻辑,我们可以为Quill.js编辑器创建出功能完善、导航友好的文章目录,极大地提升了长篇文章的可读性和用户体验。这种方法充分展示了Quill.js高度可定制的强大能力,允许开发者根据具体需求进行深度扩展。

以上就是使用Quill.js实现动态目录(TOC)生成教程的详细内容,更多请关注php中文网其它相关文章!

最佳 Windows 性能的顶级免费优化软件
最佳 Windows 性能的顶级免费优化软件

每个人都需要一台速度更快、更稳定的 PC。随着时间的推移,垃圾文件、旧注册表数据和不必要的后台进程会占用资源并降低性能。幸运的是,许多工具可以让 Windows 保持平稳运行。

下载
来源:php中文网
本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系admin@php.cn
最新问题
开源免费商场系统广告
热门教程
更多>
最新下载
更多>
网站特效
网站源码
网站素材
前端模板
关于我们 免责申明 举报中心 意见反馈 讲师合作 广告合作 最新更新 English
php中文网:公益在线php培训,帮助PHP学习者快速成长!
关注服务号 技术交流群
PHP中文网订阅号
每天精选资源文章推送
PHP中文网APP
随时随地碎片化学习

Copyright 2014-2025 https://www.php.cn/ All Rights Reserved | php.cn | 湘ICP备2023035733号