在 Quill.js 中集成代码高亮与数学公式支持的方法

图 0：Quill.js 核心引擎与 highlight.js、KaTeX 的外部分工与协同拓扑

一、依赖资源准备与全局环境注入

Quill.js 采用 Blot 架构构建文档树（Parchment），负责选区控制、DOM 节点包裹与 Delta 变更追踪。对于专业性极强的领域计算——如按语言词法分析生成语法树（AST）或将 LaTeX 字符串编译成高精度的 MathML 与几何尺寸节点，Quill 采取了职责分离的策略：代码高亮完全委托给 highlight.js，公式渲染完全委托给 KaTeX。

这种设计意味着如果仅在 Quill 的配置中简单声明 syntax: true 或 formula: true，而宿主环境缺失对应引擎，编辑器初始化过程将因找不到全局对象而报错中断。因此，正确引入必要文件是整个流程的第一道关卡。

图 1：在 Quill.js 中集成代码高亮与数学公式的五步实施流

1. CDN 极速引入模式

在传统页面或快速原型中，可直接在 HTML 页面 <head> 中通过 CDN 引入。必须严格注意：样式表与外部 JS 脚本必须完整，且外部 JS 必须优先于 Quill.js 执行。

<!-- 1. KaTeX 样式表与核心脚本（公式排版必备） -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css" />
<script src="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.js"></script>

<!-- 2. highlight.js 语法着色主题与解析脚本 -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/highlight.js@11.9.0/styles/atom-one-dark.min.css" />
<script src="https://cdn.jsdelivr.net/npm/highlight.js@11.9.0/lib/highlight.min.js"></script>

<!-- 3. Quill 核心样式与脚本 -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/quill@1.3.7/dist/quill.snow.css" />
<script src="https://cdn.jsdelivr.net/npm/quill@1.3.7/dist/quill.min.js"></script>

2. 现代工程化（NPM / Vite / Webpack）模块引入

在 Vue、React 或原生 Vite 项目中，开发者通常使用 npm install quill katex highlight.js 安装依赖。由于打包工具实行模块作用域隔离，外部库不会自动挂载到 window 上。

Quill 内部的 Syntax 模块与 FormulaBlot 在默认机制下会直接读取 window.hljs 与 window.katex。如果未手动挂载，控制台会抛出运行时异常。因此，在导入模块后必须显式赋值：

import Quill from 'quill';
import katex from 'katex';
import hljs from 'highlight.js';

// 导入相关样式表
import 'katex/dist/katex.min.css';
import 'highlight.js/styles/atom-one-dark.css';
import 'quill/dist/quill.snow.css';

// 关键步骤：在实例化任何 Quill 之前将引擎绑定到全局作用域
window.katex = katex;
window.hljs = hljs;

二、Quill 模块配置与工具栏定制

当外部解析器成功挂载后，接下来需要在初始化 Quill 实例时通过 modules 选项激活语法与公式驱动，并在 toolbar 控制器中声明触发入口。

图 2：Quill.js 内部抽象模型与外部计算引擎的协同通信结构

1. 完整可运行代码示例

下面是一个具备完整工具栏、代码块语法高亮与交互式公式插入的最小生产级实例：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8" />
  <title>Quill 混合排版实例</title>
  <!-- 资源引入 -->
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css" />
  <script src="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.js"></script>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/highlight.js@11.9.0/styles/atom-one-dark.min.css" />
  <script src="https://cdn.jsdelivr.net/npm/highlight.js@11.9.0/lib/highlight.min.js"></script>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/quill@1.3.7/dist/quill.snow.css" />
  <script src="https://cdn.jsdelivr.net/npm/quill@1.3.7/dist/quill.min.js"></script>
  <style>
    #editor-wrapper {
      max-width: 800px;
      margin: 40px auto;
    }
    #editor {
      height: 350px;
    }
  </style>
</head>
<body>
  <div id="editor-wrapper">
    <div id="editor"></div>
  </div>

  <script>
    // 确保依赖可用后初始化 Quill
    const quill = new Quill('#editor', {
      theme: 'snow',
      modules: {
        // 1. 启用语法高亮模块
        syntax: true,
        // 2. 启用数学公式模块
        formula: true,
        // 3. 配置工具栏分组
        toolbar: [
          [{ header: [1, 2, 3, false] }],
          ['bold', 'italic', 'underline', 'strike'],
          ['blockquote', 'code-block'], // 'code-block' 会调用 syntax 模块
          ['formula'],                   // 'formula' 调起 KaTeX 录入模态框
          [{ list: 'ordered' }, { list: 'bullet' }],
          ['clean']
        ]
      }
    });
  </script>
</body>
</html>

2. Quill 1.x 与 Quill 2.x 的配置差异

在实际项目维护中，Quill 版本差异是导致配置无效的常见原因：

• Quill 1.3.x：modules.syntax 直接接收布尔值 true。如果设为 true，Quill 会强制在全局寻找 window.hljs。modules.formula 同样设为 true，寻找 window.katex。
• Quill 2.0.x：语法模块重构为现代化参数接口，既支持 syntax: true（依赖 window.hljs），也支持直接传入实例对象：

  modules: {
    syntax: {
      hljs: hljs, // 直接将 import 的 hljs 实例注入，不再强制依赖全局 window 变量
      languages: [
        { key: 'javascript', label: 'JavaScript' },
        { key: 'python', label: 'Python' },
        { key: 'cpp', label: 'C++' }
      ]
    },
    formula: true
  }

三、底层运作机制与 Delta 数据模型表现

理解 Quill 是如何在底层管理代码与公式数据的，对于后续的数据持久化、服务端渲染（SSR）和只读回显至关重要。

图 3：交互输入、公式排版及代码着色的完整运行时时序与数据流转

1. 代码块的实现与 Delta 表达

当用户点击 code-block 按钮时，Quill 会将选区段落包裹进 <pre class="ql-syntax" spellcheck="false"> 中。在内部，这是一个由多个行级 Block Blot 构成的连续区域。

在 Delta 格式中，代码块并不存储高亮产生的各种 span 标签，而是存储纯文本及其行级属性：

[
  { "insert": "function calculateSquare(num) {
  return num * num;
}" },
  { "attributes": { "code-block": true } }
]

这种设计的核心优势在于数据解耦：Delta 格式只保存文本语义本身，颜色高亮是在编辑器运行时由 highlight.js 动态生成的临时 DOM 节点。当外部主题发生切换（例如从暗色主题切换为浅色主题）时，不需要重写或修改数据库中的原始 Delta 数据。

2. 数学公式的 Embed Blot 与 LaTeX 存储

与代码块不同，公式是一个不可分割的原子嵌入节点（Embed Blot）。在 DOM 层面，Quill 生成如下结构：

<span class="ql-formula" data-value="e^{i\pi} + 1 = 0" contenteditable="false">
  <!-- 内部由 KaTeX 动态注入渲染出的 MathML 和 span 绝对定位元素 -->
</span>

在对应的 Delta 结构中，公式被序列化为一个对象插入项，其保留了用户输入的原始 LaTeX 字符串：

[
  { "insert": "质能方程如下所示：" },
  { "insert": { "formula": "E = mc^2" } },
  { "insert": "
请务必牢记。" }
]

当调用 quill.setContents(delta) 重新加载数据时，Quill 的 FormulaBlot 会读取 data-value 或 Delta 中的 formula 属性，再次调用 katex.render() 重新构筑可视节点。

四、生产环境常见问题排查与技术细节

在实际生产部署中，由于网络环境、安全策略或富文本交互复杂度，开发者常会遭遇各种偶发故障。以下列出四种最高频问题的根本成因与对策。

图 4：Quill 混合内容排版常见故障排查决策矩阵

1. 故障场景分析与应对表

2. 内容安全策略（CSP）与 XSS 防护

Quill 的公式模块在将 LaTeX 渲染为 HTML 时，KaTeX 自身具备针对绝大多数脚本注入的转义防护能力。但在将包含代码块与公式的富文本保存至后端数据库并在只读端渲染时，仍然必须注意：

• 使用 DOMPurify 等清洗工具时：需将 data-value 属性加入属性白名单，并将 span、annotation、semantics、math 等 KaTeX 生成的特定标签保留，避免公式结构被安全过滤器过滤破坏。
• 只读端渲染的最佳实践：前端展示只读内容时，建议直接实例化一个配置了相同模块但带有 readOnly: true 选项的轻量 Quill 实例，或者使用 Delta 专用解析器在服务器端预先完成 KaTeX 渲染，以保证编辑视图与展示视图的视觉排版完全一致。

五、工程实施总结清单

在 Quill.js 中整合代码高亮与数学公式，本质上是“以 Quill 为容器骨架，以外部引擎为解析驱动”的典型模式。在项目上线前，建议对照以下基准清单进行确认：

1. 依赖就绪性：确认生产包构建中 window.hljs 与 window.katex 已在 Quill 之前稳定就绪。
2. 样式完整度：核实 quill.snow.css、katex.min.css 以及代码高亮主题 CSS 均已包含在页面样式表中，且 KaTeX 字体无网络阻塞。
3. 功能验证点：验证公式输入弹窗能够通过点击或快捷键正常激活，提交公式能实时排版；验证输入不同编程语言的代码段能够被正确分词上色。
4. 数据存取验证：调用 quill.getContents() 验证输出的 Delta 是否包含 attributes: { "code-block": true } 与 insert: { formula: "..." }，确保保存与回显流程完整无损。