Quill.js 1.x 升级至 2.x 版本的 API 变更与迁移注意事项

图 0：Quill.js 1.x 到 2.x 核心演进维度概览

在企业级内容管理系统与协作平台中，Quill 凭借其基于 Delta 格式的清晰设计理念，长年占据着主流富文本编辑器的重要生态位。然而，长期停留在 1.3.x 版本的 Quill 积累了诸多与现代前端生态脱节的痛点：源码仍为 ES5/ES6 混编、缺乏官方第一方 TypeScript 类型支持（依赖常年滞后的 @types/quill 社区包）、缺乏开箱即用的原生 ES 模块导出，以及基于旧版 Parchment 规范导致自定义复杂格式时极其容易产生 DOM 结构畸变。

随着 Quill 2.0 正式版本的发布，整个编辑器内核完成了全量 TypeScript 重写，带来了原生 ESM 支持、重构后的 Parchment 格式引擎以及更加规范严谨的对外 API。由于底层模型与部分核心方法的破坏性变更，直接提升依赖版本往往会导致构建失败或运行时富文本渲染异常。本文将针对 Quill 1.x 迁移至 2.x 的关键 API 变更、底层机制调整、逐步实操迁移策略与高频避坑要点进行系统化拆解。

一、核心架构与技术生态重大变动

理解 Quill 2.0 的底层变动是顺利完成 API 迁移的基础。相较于 1.x 时代以修复补丁为主的维护策略，2.0 是底层技术栈的代际演进，其核心变化主要集中在四个维度：

• TypeScript 完整内核重构：Quill 2.0 不再依赖外部社区维护的 @types/quill，而是从底层完全采用 TypeScript 编写，随 npm 包直接提供精确的类型定义文件（包括 Delta、Range、Blot、Module 等关键类型）。
• 底层 DOM 抽象升级至 Parchment v3：Parchment 负责管理 DOM 节点与文档格式模型之间的映射。Quill 2.0 全面接纳了 Parchment 新规范，加强了对嵌套格式、容器范围（Scope）以及内联行内格式（Inline/Embed）的生命周期管理。
• 现代原生 ESM 与构建优化：废弃了以往混杂 UMD 与 CommonJS 的打包形态，全面遵循现代 Node.js exports 映射规范，天然契合 Vite、Webpack 5 及 Rollup，并支持更加精准的代码摇树优化（Tree Shaking）。
• API 严格化与安全防御提升：彻底清理或重命名了早期未经充分消毒的快捷方法（如直接操作 DOM 或静默抹除错误的 API），要求开发者显式表达操作意图以防范 XSS 漏洞。

图 1：Quill 1.x 与 Quill 2.x 核心架构与技术生态对比

二、工程配置与依赖迁移规范

升级的第一步发生在项目构建环境与依赖管理层面。如果这一步配置不当，项目往往会在编译期直接报错终止。

1. 依赖包安装与类型清理

在 package.json 中，开发者必须彻底移除 @types/quill，否则 TypeScript 编译器会同时加载外部旧类型声明与 Quill 2.x 内置类型，引发大量全局变量重复定义冲突（Duplicate Identifier）。

# 1. 移除过期的 DefinitelyTyped 社区声明
npm uninstall @types/quill

# 2. 升级核心包至 Quill 2.x 稳定版
npm install quill@^2.0.0

2. CSS 样式表引入路径调整

在 Quill 1.x 中，通常通过 import 'quill/dist/quill.snow.css'; 引入主题样式。在 Quill 2.x 中，由于 package.json 中配置了标准的 exports 字段，样式的引入支持更为简练的子路径映射：

// 方式一：推荐的现代子路径导出（Vite / Webpack 5 均原生支持）
import 'quill/dist/quill.snow.css'; 

// 或者部分构建系统支持更精简的路径：
// import 'quill/snow.css';

注意检查项目中是否存在针对 .ql-container 或 .ql-editor 的深度样式覆写（CSS Overrides）。Quill 2.x 微调了部分默认行高、边界内边距以及 SVG 图标的类名绑定结构，旧的绝对像素微调可能产生轻微错位。

三、核心 API 变更与废弃方法替换

进入代码改造阶段后，开发者需要重点对以下几组高频使用的核心 API 进行精准替换。

1. HTML 字符串注入：pasteHTML 彻底移除

在 Quill 1.x 中，许多业务系统习惯使用 quill.pasteHTML(html) 来初始化或重置编辑器内容。在 2.x 中，该方法已被彻底废弃。取而代之的是更加安全规范的剪贴板接口：

// ❌ Quill 1.x 遗留写法（2.x 中会直接报错 TypeError: quill.pasteHTML is not a function）
quill.pasteHTML('<p>欢迎使用 <strong>Quill 编辑器</strong></p>');

// ✅ Quill 2.x 方案 A：使用显式声明危险的剪贴板接口
quill.clipboard.dangerouslyPasteHTML(0, '<p>欢迎使用 <strong>Quill 编辑器</strong></p>');

// ✅ Quill 2.x 方案 B：先转换为 Delta 再调用 setContents（架构推荐最佳实践）
const delta = quill.clipboard.convert({
  html: '<p>欢迎使用 <strong>Quill 编辑器</strong></p>'
});
quill.setContents(delta, 'silent');

方案 B 的优势在于完全绕过了浏览器的不可控直接插入，保证所有 HTML 元素都经过 Parchment 格式转换器的标准化清洗，避免生成未知结构的非法 DOM 节点。

2. 光标与元素边界计算：getBounds 行为统一

Quill 1.x 中的 quill.getBounds(index, length) 返回一个包含 top、left、height、bottom 等属性的对象，但其坐标基准在不同主题容器下存在偏差。Quill 2.x 规范了返回值模型，完全对齐现代浏览器标准 DOMRect 规范：

// 获取当前光标位置的矩形边界信息
const range = quill.getSelection();
if (range) {
  const bounds = quill.getBounds(range.index, range.length);
  // bounds 提供标准: left, top, right, bottom, width, height
  // 用于精准定位浮动工具栏（Floating Toolbar）或 @人员 提及菜单
  floatingMenu.style.top = `${bounds.bottom + window.scrollY}px`;
  floatingMenu.style.left = `${bounds.left + window.scrollX}px`;
}

3. 事件触发机制与签名校验

Quill 2.0 延续了核心的 text-change 与 selection-change 事件，但强化了事件参数中数据源（Source）的传递逻辑：'user'、'api' 或 'silent'。在 TypeScript 下，事件回调参数拥有强类型推导：

import type { Delta } from 'quill';

quill.on('text-change', (delta: Delta, oldDelta: Delta, source: string) => {
  if (source === 'user') {
    // 仅捕获用户显式输入操作，避免 API 联动引发循环触发
    triggerAutoSave(quill.getContents());
  }
});

四、Parchment 升级与自定义 Blot 机制调整

如果业务中扩展了自定义组件（如代码块增强、自定义附件卡片、提及 Mention、公式渲染等），这是升级过程中最容易遇到阻碍的部分。Quill 2.x 底层采用了新版 Parchment，Blot 的类结构定义与挂载规则更加严密。

图 2：Quill 2.x Parchment 与 Blot 格式解析与生命周期

1. 自定义 Blot 的定义与静态属性规范

在 Quill 1.x 中，许多自定义 Blot 允许省略部分静态元数据，或者在 create() 方法中返回不规范的 DOM。Quill 2.x 要求所有继承自 BlockBlot、InlineBlot 或 EmbedBlot 的类必须明确遵循静态成员契约：

import Quill from 'quill';

// 1. 获取基类 Blot 定义
const BlockEmbed = Quill.import('blots/block/embed');

// 2. 声明现代自定义 Blot 类
class DividerBlot extends BlockEmbed {
  static blotName = 'divider';
  static tagName = 'hr';
  static className = 'ql-custom-divider';

  // 必须实现静态 create 方法构建 DOM
  static create(value: any) {
    const node = super.create(value) as HTMLElement;
    node.setAttribute('data-divider-style', value?.style || 'solid');
    return node;
  }

  // 提取 Delta 格式所需的纯粹值
  static value(node: HTMLElement) {
    return {
      style: node.getAttribute('data-divider-style') || 'solid'
    };
  }
}

// 3. 显式注册到 Quill，第二参数设为 true 表示强制覆盖同名实现
Quill.register(DividerBlot, true);

五、第三方插件与生态扩展适配

许多基于 Quill 1.x 的第三方生态库（例如非常流行的 quill-image-resize-module、quill-mention、quill-table）在未更新的情况下无法直接在 2.x 中运行。常见报错为无法获取全局私有属性或访问已变更的内部函数。

六、平滑升级五步实操路线

为了保证生产环境代码迁移的有序推进，建议团队按照以下标准化五步流水线实施代码重构与验证：

图 3：Quill 1.x 至 2.x 平滑迁移实操流水线

1. 第一阶段：依赖净化与构建环境就绪
   检查并清除 package.json 中的旧版声明包，更新 quill 版本到 2.x，清除本地 node_modules 和 lock 文件后执行全新安装，确认构建工具（Webpack/Vite）能够成功解析 ESM 导出。
2. 第二阶段：静态资源路径与主题样式校正
   重构所有 CSS 导入指令，检查全局页面样式中是否有针对 .ql-editor 等核心容器的硬编码覆盖，验证编辑器工具栏在不同屏幕分辨率下的图标排版。
3. 第三阶段：全面检索废弃 API 并完成安全重构
   全局搜索代码库中的 pasteHTML、quill.theme.tooltip、直接读取 quill.root.innerHTML 绕过剪贴板的写操作，按第二节规范逐一替换为 clipboard.dangerouslyPasteHTML 或 setContents。
4. 第四阶段：重写自定义 Blot 与校验注册逻辑
   将所有扩展的 Format/Embed 迁移至基于 Parchment 3 的 TypeScript 类结构，补齐静态 create 与 value 方法，确保在初始化 new Quill() 之前统一执行注册。
5. 第五阶段：历史存量 Delta 格式回归与解析验证
   从数据库中提取存量用户的 Delta JSON 数据，在 2.x 环境中执行加载与重新导出，核对 quill.getContents() 输出的 Delta 差异，确保段落格式、空换行及嵌套样式完全幂等。

七、高频踩坑排查与回归决策矩阵

在实际升级落地过程中，开发团队常常会遭遇一些隐蔽的运行时异常。以下汇总了最典型的三类错误及快速应对决策：

图 4：Quill 2.x 升级变更矩阵与避坑决策导图

1. 空段落解析与连续换行问题

在 Quill 1.x 中，空段落通常渲染为 <p><br></p>。Quill 2.x 对空白占位符的解析进行了优化，但如果开发者自行解析历史 HTML 并调用 clipboard.convert()，偶尔会发现连续空行被压缩为一个换行。

解决方案：统一在数据持久化层保存 Delta 原始 JSON，避免在服务端与客户端反复进行 HTML ↔ Delta 的不可逆双向互转。Delta 中的 { insert: ' ' } 在 Quill 2.x 中能够百分之百精准复原空行。

2. SSR（服务端渲染）下的 window / document 缺失

在 Next.js、Nuxt 或现代 SSR 框架中引入 Quill 2.0 时，由于 2.0 原生 ESM 在根模块执行时可能会嗅探 DOM 环境，直接静态 import Quill from 'quill' 可能导致服务端构建阶段抛出 ReferenceError: document is not defined。

解决方案：采用动态按需加载策略，确保 Quill 仅在客户端生命周期中挂载：

// Next.js (React) 动态导入示例
import dynamic from 'next/dynamic';

const EditorComponent = dynamic(() => import('@/components/QuillEditor'), {
  ssr: false,
  loading: () => <div class="editor-skeleton">编辑器加载中...</div>
});

3. 工具栏自定义按钮点击时光标丢失

Quill 2.x 强化了对焦点状态的控制。如果在自定义工具栏按钮的 click 事件处理中直接执行 API 操作，可能因原生按钮获取焦点而导致编辑区失焦，进而使 quill.getSelection() 返回 null。

解决方案：在自定义按钮的 mousedown 事件中调用 event.preventDefault()，防止编辑区失去焦点：

customButton.addEventListener('mousedown', (event) => {
  // 阻止按钮夺取焦点，保留编辑器内部 Selection
  event.preventDefault();
});

customButton.addEventListener('click', () => {
  const range = quill.getSelection(true); // 传入 true 强制聚焦
  quill.formatText(range.index, range.length, 'highlight', true);
});

八、总结与迁移收益

升级至 Quill 2.x 虽然需要对工程配置、废弃 API 以及自定义 Blot 进行系统的重构与审查，但其带来的收益是显著的：

• 工程健壮性飞跃：全量内置的 TypeScript 类型定义消除了以往依赖过时社区声明带来的类型安全隐患，大幅提升了团队协作与重构效率。
• 构建性能提升：现代 ESM 结构使打包产物体积更加精简，与 Vite、Webpack 5 等现代前端构建生态的兼容性得到根本性改善。
• 更强大的扩展能力：基于 Parchment 3 的严谨模型让复杂自定义富文本组件开发变得可预测，彻底规避了过去各种诡异的 DOM 嵌套坍塌 Bug。

只要严格按照本文梳理的步骤执行废弃方法重构、Blot 契约迁移以及存量 Delta 的幂等性验证，团队即可平稳跨越版本断层，为业务构建更加稳定高效的现代富文本编辑中台。