TOAST UI Editor 3.0 迁移指南：从2.x到3.0的全面升级解析

前言

TOAST UI Editor作为一款功能强大的Markdown编辑器，在3.0版本中进行了重大架构升级。本文将从技术角度深入解析2.x到3.0版本的迁移要点，帮助开发者顺利完成版本过渡。

核心架构变化

3.0版本最显著的改变是底层架构的全面重构：

1. 依赖模块替换：移除了CodeMirror、squire和to-mark等依赖，转而采用Prosemirror作为核心编辑引擎
2. 模型抽象化：通过Prosemirror实现了更清晰的抽象模型层
3. API重构：核心模块API和插件系统都进行了重大调整

安装与使用变更

包安装方式

虽然包名保持不变，但内部实现已完全不同：

npm install @toast-ui/editor
npm install @toast-ui/editor@<特定版本>

新增EditorCore模块

3.0版本引入了EditorCore模块，为需要自定义UI的开发者提供了更大的灵活性：

import { EditorCore } from '@toast-ui/editor';

const editorCore = new EditorCore({
  el: document.querySelector('#editor'),
  // 其他配置
});

const { mdEditor, mdPreview, wwEditor } = editorCore.getEditorElements();

打包结构优化

新版打包结构更加清晰：

dist/
├─ cdn/...        # CDN资源
├─ i18n/...       # 国际化文件
├─ esm/           # ESM模块
├─ theme/         # 主题文件
│  └─ toastui-editor-dark.css # 新增暗黑主题
├─ toastui-editor.css
└─ toastui-editor.js

暗黑主题支持

3.0版本新增了官方暗黑主题：

import Editor from '@toast-ui/editor';
import '@toast-ui/editor/dist/theme/toastui-editor-dark.css';

const editor = new Editor({
  // ...
  theme: 'dark',  // 启用暗黑主题
});

工具栏定制新方式

工具栏配置方式从一维数组升级为更直观的二维数组：

旧版(2.x)

toolbarItems: [
  'heading', 'bold', 'italic', 'strike',
  'divider',  // 需要显式添加分隔符
  'hr', 'quote'
]

新版(3.0)

toolbarItems: [
  ['heading', 'bold', 'italic', 'strike'], // 第一组
  ['hr', 'quote']  // 第二组
]

自定义工具栏项

3.0版本简化了自定义工具栏项的流程：

const customItem = {
  name: 'color',
  tooltip: '文本颜色',
  className: 'custom-color-icon',
  popup: {
    className: 'color-popup',
    body: colorPickerElement,
    style: { width: 'auto' }
  }
};

插件系统重构

3.0版本对插件系统进行了彻底重构，提供了更清晰的API边界。

命令注册

{
  markdownCommands: {
    customCommand: (payload, state, dispatch) => {
      // 命令逻辑
    }
  },
  wysiwygCommands: {
    customCommand: (payload, state, dispatch) => {
      // 命令逻辑
    }
  }
}

内容转换

{
  toHTMLRenderers: {
    customNode(node, { entering, origin }) {
      // 自定义HTML渲染逻辑
    }
  },
  toMarkdownRenderers: {
    customNode(nodeInfo) {
      // 自定义Markdown生成逻辑
    }
  }
}

工具栏项注册

{
  toolbarItems: [
    {
      groupIndex: 0,  // 第一组
      itemIndex: 1,   // 插入位置
      item: customToolbarItem
    }
  ]
}

API与事件变更

命令API变化

2.x版本	3.0版本
addCommand(type, {name, exec})	addCommand(type, name, exec)
exec(name, ...args)	exec(name, payload)

文本操作API

3.0版本废弃了getTextObject()，提供了更直观的API：

// 替换选中文本
editor.replaceSelection('新文本');

// 删除选中文本
editor.deleteSelection();

// 获取选中文本
const selectedText = editor.getSelectedText();

重要重命名

2.x方法名	3.0方法名
setHtml	setHTML
remove	destroy

浏览器支持调整

3.0版本仅支持IE11及以上浏览器，不再支持IE10。

移除的功能

1. jQuery包装器：需要自行封装
2. 直接访问底层依赖：getCodeMirror()等方法已移除
3. 废弃API：包括linkAttribute等已重命名或移除的API

迁移建议

1. 先在小规模项目中测试迁移
2. 重点关注自定义插件和工具栏的部分
3. 利用TypeScript类型定义辅助迁移
4. 彻底测试编辑器在各种场景下的表现

通过遵循本指南，开发者可以顺利完成TOAST UI Editor从2.x到3.0的迁移，享受新版带来的性能提升和开发便利。