概述

TinyMCE 从版本 5 发展到版本 8.0 有了显著变化,引入了架构改进、现代 UI 增强、更严格的安全默认设置以及更新的插件结构。本综合指南概述了从 TinyMCE v5 升级到 v8.0 所需的关键破坏性变更、建议的迁移行动步骤以及顶级配置调整。

本指南提供了从 TinyMCE 5 到 TinyMCE 8 的完整迁移路径,在一个全面的文档中涵盖了版本 6、7 和 8 的所有变更。

关键变更

UI 主题和皮肤

  • 细微调整:v5 中基于 Oxide 的皮肤大多保持兼容,但可能需要针对 v8.0 进行小幅 CSS 调整。

  • 影响:对自定义皮肤进行视觉测试,因为细微的 DOM 变化可能会影响布局和样式。

  • 浏览器支持:v8.0 不再支持 Internet Explorer 11(在 v6 中已弃用),需要使用现代浏览器。

  • 拆分按钮变化:TinyMCE 8 对拆分按钮进行了结构更改,可能会影响自定义皮肤。

示例:
tinymce.init({
  selector: "textarea",
  skin: "oxide-dark",
  content_css: "dark",
});

插件生态系统

TinyMCE 插件生态系统从版本 6.0 开始进行了重大改革,许多插件要么被移除、集成到核心中,要么成为高级功能。以下总结了这些变化。

  • 移除的插件(自 TinyMCE 6.0 起不再可用):

    • bbcode, legacyoutput:在 5.9.0 中弃用。在 6.0 中移除。

    • imagetools:在 6.0 中移除。由 TinyMCE 6.0 中引入的 editimage 插件所提供的高级增强图像编辑功能取代。

  • 集成到 TinyMCE 核心:

    • paste, hr, table, noneditable, nonbreaking, print, colorpicker 和 contextmenu:这些插件已被吸收到 TinyMCE 核心中,不再需要单独安装。有关更多信息,请参见复制和粘贴、表格、不可编辑内容以及 上下文菜单。

    • textcolor:在 6.0 中作为单独插件被移除。文本颜色功能现在通过 forecolor 和 backcolor 工具栏按钮集成到 TinyMCE 核心中,无需额外插件即可使用。

    • contextmenu:在版本 5.0 中弃用,此后上下文菜单功能集成到 TinyMCE 核心编辑器中。在版本 6.0 中移除。有关更多信息,请参见 contextmenu 文档。

    • tabfocus:在 6.0 中移除。通过 Tab 键进行的键盘导航现在由浏览器和 TinyMCE 核心处理。

  • 现在仅限高级版:

    • fullpage:在 6.0 中移除。由高级版全页 HTML插件(fullpagehtml)取代。

    • tableofcontents:以前作为开源 toc 插件提供。现更名为 tableofcontents,并作为高级插件提供。有关更多信息,请参见目录。

    • spellchecker:在 5.9.0 中弃用。在 6.0 中移除。

    • advtemplate:取代 template 插件,用于高级模板用例。

    • template:在 7.0 中移除。由高级版模板插件取代。

插件迁移示例

  • contextmenu(在 v6 中移除):

  • bbcode(在 v6 中移除):

    • 如果需要 BBCode 支持,请实现自定义解析或服务器端处理。

  • fullpage(在 v8 中为高级版功能):

    • 使用高级版全页 HTML插件(fullpagehtml)进行完整 HTML 文档编辑。

  • template(在 v7 中移除):

    • 使用高级版 advtemplate 插件或实现自定义模态对话框。

  • textcolor(在 v6 中集成到核心):

    • 文字颜色功能现已内置于 TinyMCE 核心。使用 forecolor 和 backcolor 工具栏按钮,无需额外插件即可使用。

  • imagetools:(在 v6 中已移除):

工具栏和菜单名称变更

如果您使用了以下工具栏按钮或菜单选项,它们在 TinyMCE 各个主要版本中已更改名称。请参阅各版本的发布说明以获取完整的迁移详细信息。

TinyMCE 5 → TinyMCE 6:

  • formatselect → blocks(工具栏项)

  • blockformats → blocks(菜单项)

  • styleselect → styles(工具栏项)

  • formats → styles(菜单项)

  • fontselect → fontfamily(工具栏项)

  • fontformats → fontfamily(菜单项)

  • fontsizeselect → fontsize(工具栏项)

  • fontsizes → fontsize(菜单项)

  • imagetools → editimage(插件及相关工具栏项)

  • toc → tableofcontents(插件、菜单项和工具栏项)

  • tocupdate → tableofcontentsupdate(工具栏项)

TinyMCE 6 → TinyMCE 7:

  • InsertOrderedList 和 InsertUnorderedList 命令已从 TinyMCE 核心移除,现由 Lists 插件提供。

  • 默认文本模式触发器已更新,在按下 Space 键时激活,而不是 Enter。新增了 trigger 属性以配置块级文本模式行为。

TinyMCE 7 → TinyMCE 8:

  • 若干 API 方法已被弃用或移除(详见下方的 API 变更部分)

  • License key 系统已更新,具有新的格式要求

  • DOMPurify 过滤已得到加强

有关更多详细信息,请参阅 最新的发布说明。

请始终参阅最新的插件文档 插件 以获取最新的可用性和迁移指南。
工具栏变更示例:
tinymce.init({
  selector: "textarea",
  toolbar: "undo redo | forecolor backcolor | bold italic | alignleft aligncenter alignright alignjustify",
  plugins: ["lists link image table code"] // 注:xref:lists.adoc[Lists]、xref:link.adoc[Link]、xref:image.adoc[Image]、xref:table.adoc[Table] 和 xref:code.adoc[Code] 插件
});

内容结构

  • 已移除:forced_root_block: false。

    • 要求:所有编辑器内容必须包含在块元素中(例如 <p>)。有关更多信息,请参阅 forced_root_block。

示例:
tinymce.init({
  selector: "textarea",
  forced_root_block: "p"
});

配置变更

  • 在 TinyMCE 6.0 中已移除:旧版移动主题已移除,但特定于移动设备的配置仍通过 mobile 选项支持。

  • UI API 更新:

    • 更新自定义插件以使用 editor.ui.registry.*。

    • 替换已弃用的方法,如 editor.addButton、editor.addMenuItem 和 editor.windowManager.open。

  • 基于 Promise 的方法:

  • 已移除的选项:

    • force_hex_color 已移除。请使用标准的 CSS 颜色声明。

文本模式变更(v7)

TinyMCE 7.0 更新了 text_patterns 的默认行为,在用户按下 Space 键而非 Enter 键时应用格式。

影响:

  • 现在,Markdown 风格的格式在按下 Space 键时触发

  • 通过配置 trigger: 'enter' 可恢复之前的 Enter 键行为

  • 这会影响所有文本模式,包括标题、列表、引述块和水平线

示例:
// 默认 TinyMCE 7+ 行为(空格键触发)
tinymce.init({
  selector: "textarea",
  text_patterns: [
    { start: '#', format: 'h1', trigger: 'space' },
    { start: '##', format: 'h2', trigger: 'space' },
    { start: '1.', cmd: 'InsertOrderedList', trigger: 'space' },
    { start: '*', cmd: 'InsertUnorderedList', trigger: 'space' },
    { start: '>', cmd: 'mceBlockQuote', trigger: 'space' }
  ]
});

// 恢复旧行为(回车键触发)
tinymce.init({
  selector: "textarea",
  text_patterns: [
    { start: '#', format: 'h1', trigger: 'enter' },
    { start: '##', format: 'h2', trigger: 'enter' },
    { start: '1.', cmd: 'InsertOrderedList', trigger: 'enter' },
    { start: '*', cmd: 'InsertUnorderedList', trigger: 'enter' },
    { start: '>', cmd: 'mceBlockQuote', trigger: 'enter' }
  ]
});

迁移检查清单:

  • 测试现有的文本模式行为是否使用空格键触发

  • 如果需要使用回车键触发,则更新配置

  • 评估新空格键触发的用户体验

  • 更新有关文本模式行为的用户文档

从 TinyMCE 7.0 开始,remove_trailing_brs 设置已从 DomParser API 中移除(此前在 TinyMCE 6.5 中已弃用)。有关 DomParser 的更多信息,请参阅 DomParser API。

自动补全器配置变更(v7)

自动补全器的 ch 配置属性已被移除。请改用 trigger 属性。

示例:
// 旧的 TinyMCE 6 配置
editor.ui.registry.addAutocompleter('myautocompleter', {
  ch: '@',
  minChars: 0,
  fetch: function(pattern) {
    return [
      { value: 'john@example.com', text: 'John Doe' },
      { value: 'jane@example.com', text: 'Jane Smith' }
    ];
  }
});

// 新的 TinyMCE 7+ 配置
editor.ui.registry.addAutocompleter('myautocompleter', {
  trigger: '@',
  minChars: 0,
  fetch: function(pattern) {
    return [
      { value: 'john@example.com', text: 'John Doe' },
      { value: 'jane@example.com', text: 'Jane Smith' }
    ];
  }
});

迁移检查清单:

  • 在自动补全器配置中将 ch: '<string>' 替换为 trigger: '<string>'

  • 测试自动补全器功能

  • 更新任何自定义的自动补全器实现

table_responsive_width 已被 table_sizing_mode 替换(v7)

在 TinyMCE 7.0 中,table_responsive_width 选项已被 table_sizing_mode 替换。

示例:
// 旧的 TinyMCE 6 配置
tinymce.init({
  selector: "textarea",
  table_responsive_width: true
});

// 新的 TinyMCE 7+ 配置
tinymce.init({
  selector: "textarea",
  table_sizing_mode: "responsive"
});

迁移检查清单:

  • 在您的配置中将 table_responsive_width 替换为 table_sizing_mode

  • 更新选项值以匹配新的 API

  • 测试表格的响应式行为

  • TinyMCE 7.0 中的默认变更:

  • TinyMCE 7.0 中的新选项:

  • TinyMCE 8.0 中的新选项:

    • 增强的许可证密钥系统,具有新的格式要求

    • 更严格的 DOMPurify 清理,默认启用 SAFE_FOR_XML

    • 新的 crossorigin 配置选项,用于跨源资源加载

示例:
tinymce.init({
  selector: "textarea",
  toolbar: "undo redo | blocks | bold italic | alignleft aligncenter alignright alignjustify | outdent indent | removeformat",
  toolbar_mode: "floating",
  license_key: "T8LK:...", // TinyMCE 8.0 中要求的新格式
  // 安全选项现在在 TinyMCE 7.0 中默认启用
  sandbox_iframes: true,
  convert_unsafe_embeds: true,
  // 可选:从 iframe 沙箱中排除特定域
  sandbox_iframes_exclusions: ["youtube.com", "vimeo.com"],
  // 可访问性改进,现在默认启用
  highlight_on_focus: true,
  // TinyMCE 8.0 新增:跨源资源加载
  crossorigin: (url, resourceType) => 'anonymous'
});
如需了解最新的插件可用性及配置参考,请参阅插件。

请参阅版本特定的发行说明,了解 TinyMCE 5、6、7 和 8 版本之间工具栏按钮名称及命令可用性的变化。例如:

TinyMCE 5 → TinyMCE 6:

  • formatselect → blocks

  • styleselect → styles

  • fontselect → fontfamily

  • fontsizeselect → fontsize

  • imagetools → editimage

  • toc → tableofcontents

TinyMCE 6 → TinyMCE 7:

  • InsertOrderedList / InsertUnorderedList 命令已从 TinyMCE 核心移除(请使用 lists 插件)。

  • 默认的文本模式触发器已从 Enter 更新为 Space,可通过 trigger 进行配置。

TinyMCE 7 → TinyMCE 8:

  • editor.selection.setContent → editor.insertContent

  • editor.fire() → editor.dispatch()

  • editor.documentBaseUrl → editor.editorManager.documentBaseURI.getURI()

许可变更(GPL v2+ 及商业许可)

  • 旧许可:TinyMCE 5 采用 LGPL 2.1 许可。

  • 新许可:TinyMCE 8.0 采用 GPL v2+ 或商业许可。

  • 影响:如果您自行托管 TinyMCE,则必须在编辑器配置中包含许可证密钥选项。如果您从云端加载 TinyMCE,则无需此要求。

TinyMCE 8 中的许可证密钥系统更新

TinyMCE 8 引入了新的许可证密钥系统,需要立即关注:

  • 新格式:许可证密钥现在使用前缀 T8LK:(适用于商业许可)或 GPL+T8LK:(适用于 GPL 及高级功能)

  • 强制要求:自托管部署现在需要有效的许可证密钥;否则编辑器将被设置为 readonly

  • 许可证密钥管理器:自托管的商业部署需要新的许可证密钥管理器插件

欲了解完整详情,请参阅 7→8 迁移指南中的许可证密钥系统更新。

许可证迁移清单:

  • 联系支持获取新的 TinyMCE 8.0 许可证密钥,或使用开源版本的 GPL 许可

  • 商业许可需安装许可证密钥管理器插件

  • 使用新的许可证密钥格式更新配置

  • 使用新许可证测试编辑器功能

  • 验证所有高级功能是否正常

示例:
tinymce.init({
selector: "textarea",
license_key: "T8LK:your-license-key" // 必须使用新格式
});

API 变更

在 6-8 版本中,部分 API 方法已被弃用或移除。主要变更包括:

  • 在 TinyMCE 8 中已弃用:

    • editor.selection.setContent → 请改用 editor.insertContent

    • editor.fire() → 请改用 editor.dispatch()

    • editor.documentBaseUrl → 请改用 editor.editorManager.documentBaseURI.getURI()

skipFocus 与 skip_focus 的合并(v8)

在 TinyMCE 8.0 中,ToggleToolbarDrawer 命令的 skipFocus 和 skip_focus 选项已合并为一个更一致的参数。欲了解更多信息,请参阅可用命令。

影响:

  • 降低了 API 复杂度

  • 明确了预期行为

  • 需要更新命令调用

示例:
// 旧方法(在 TinyMCE 8 中已弃用)
editor.execCommand('ToggleToolbarDrawer', false, { skipFocus: true });

// 新方法(推荐)
editor.execCommand('ToggleToolbarDrawer', false, null, { skip_focus: true });

迁移清单:

  • 找到所有使用 ToggleToolbarDrawer 命令的实例

  • 在命令选项中将 skipFocus 替换为 skip_focus

  • 更新任何使用此命令的自定义插件

  • 更改后测试工具栏抽屉行为

  • 已移除的方法::

    • editor.addButton、editor.addMenuItem、editor.windowManager.open(已被 editor.ui.registry.* API 取代)

欲了解完整的 API 迁移详情,请参阅 7→8 迁移指南中的核心 API 变更。

插件变更

移除 Template 插件

`template`插件已在TinyMCE 7.0中移除。如果您之前在使用这个插件,需要迁移到付费的Templates插件。

迁移步骤:

  1. 从您的插件列表中移除template

  2. 向插件列表中添加templates

  3. 更新您的配置以使用新的Templates插件API

  4. 确保您拥有Templates插件的有效商业许可证

迁移检查清单:

  • 如果使用了template插件,则从配置中移除

  • 评估对付费Templates插件(advtemplate)的需求

  • 移除所有模板相关的配置选项

  • 更新所有自定义模板实现

  • 如果迁移到付费插件,测试模板功能

示例:
// 旧版TinyMCE 5/6/7配置
tinymce.init({
  selector: "textarea",
  plugins: "template",
  templates: [
    {title: '测试模板 1', content: '测试1'},
    {title: '测试模板 2', content: '测试2'}
  ]
});

// 新版TinyMCE 8配置
tinymce.init({
  selector: "textarea",
  plugins: "templates",
  templates: [
    {title: '测试模板 1', content: '测试1'},
    {title: '测试模板 2', content: '测试2'}
  ]
});

媒体URL解析器变更 (v7)

media_url_resolver选项现在需要基于Promise的实现,而不是同步回调函数。

示例:
// 旧版TinyMCE 5/6实现
tinymce.init({
  selector: "textarea",
  media_url_resolver: function (data, resolve) {
    resolve({
      html: '<iframe src="' + data.url + '" width="560" height="314" allowfullscreen="allowfullscreen"></iframe>'
    });
  }
});

// 新版TinyMCE 7+实现
tinymce.init({
  selector: "textarea",
  media_url_resolver: function (data) {
    return new Promise(function (resolve) {
      resolve({
        html: '<iframe src="' + data.url + '" width="560" height="314" allowfullscreen="allowfullscreen"></iframe>'
      });
    });
  }
});

迁移检查清单:

  • 将media_url_resolver实现更新为返回Promise,而不是使用回调函数

  • 从解析器函数中移除resolve和reject回调参数

  • 使用更新后的解析器测试媒体嵌入功能

  • 更新任何自定义的媒体URL解析器实现

用户界面和用户体验变更

表格高度变更 (v7)

TinyMCE 7.0更改了表格高度的处理方式。表格现在使用min-height而不是height,以实现更好的响应式行为。

影响:

  • 现有的表格高度配置可能需要调整

  • 应审查针对表格高度的自定义CSS

  • 表格的响应式行为可能会发生变化

拆分按钮变更 (v8)

TinyMCE 8.0引入了对拆分按钮的结构性更改,这可能影响自定义皮肤和CSS。

变更:* 拆分按钮的DOM结构已更新* 拆分按钮的CSS选择器可能需要调整* 应测试自定义皮肤与拆分按钮的兼容性

迁移检查清单:

  • 确认您的项目是否使用了自定义皮肤。

  • 使用TinyMCE 8.0代码库重建您的自定义皮肤。请参阅创建皮肤以获取说明。

  • 更新您的拆分按钮使用方式以适应新结构,包括支持chevronTooltip选项。请参考拆分工具栏按钮以获取更新的配置详情。

  • 测试编辑器中拆分按钮的渲染和交互,以验证预期行为。

安全变更

DOMPurify更新

TinyMCE 8.0将DOMPurify依赖项更新至3.2.6版本,并默认启用SAFE_FOR_XML标志。这是一个破坏性变更:之前在TinyMCE 7中通过净化的内容,现在可能在净化过程中被剥离或更改。

影响:

  • 更严格的内容净化

  • 一些之前允许的内容可能会被剥离

  • 现在应用针对XML的特定净化规则

迁移检查清单:

  • 审查现有内容中包含标签的HTML注释

  • 使用DOMPurify 3.2.6测试内容净化行为

  • 如果注释被意外剥离,更新内容工作流程

  • 如有需要,考虑启用allow_html_in_comments(需注意安全性)

  • 如果使用了Internet Explorer条件注释,请进行测试

  • 验证具有类HTML值的属性是否被正确处理

示例:
// 可能受更严格净化影响的内容
const content = '<div><script>alert("test")</script></div>';

// 测试净化行为
const sanitized = editor.dom.sanitize(content);
console.log('净化后的内容:', sanitized);

跨域资源加载

迁移步骤:

  1. 测试现有内容的净化变更

  2. 审查自定义净化配置

  3. 更新任何依赖于先前净化行为的内容

跨域资源加载

TinyMCE 8.0 引入了更严格的跨域资源加载控制。

新配置:

  • 支持为外部资源添加 crossorigin 属性

  • 增强了外部内容加载的安全性

  • 对资源加载策略的更优控制

迁移检查清单:

  • 验证 Cloud 部署的 script 标签属性。

  • 如果使用跨域资源,配置 crossorigin 函数。

  • 在您的部署环境中测试资源加载。

  • 如果使用跨域样式表,审查 content_css 配置。

服务变更

Java Swing 集成弃用

Java Swing 集成在 TinyMCE 8.0 中已被弃用,将于 2025 年 12 月 31 日终止支持。

影响:

  • 基于 Java Swing 的集成需要迁移规划

  • 应考虑替代的集成方式

  • 旧版 Java 集成可能会停止工作

迁移检查清单:

  • 评估替代的集成方案

  • 规划迁移时间表,确保在 2025 年 12 月 31 日前完成

医学英语词典停用

“医学英语(英国)”词典已停用。

影响:

  • 使用该词典的应用需要切换到替代方案

  • 拼写检查配置可能需要更新

  • 语言包引用应进行更新

迁移检查清单:

  • 从拼写检查器配置中移除“医学英语(英国)”

  • 移除任何与医学英语相关的自定义词典集成

  • 使用剩余词典测试拼写检查功能

  • 根据需要配置替代的医学词典

服务版本解耦

TinyMCE 服务现已与编辑器版本解耦,可独立更新。

优势:* 服务可独立更新* 更好的安全性和性能更新* 减少对编辑器版本更新的依赖

迁移步骤:

  1. 审查服务集成配置

  2. 如有需要,更新服务端点

  3. 使用 TinyMCE 8 测试服务功能

WAR 文件向容器迁移

TinyMCE 服务正从 Java WAR 文件过渡到容器化服务。

影响:

  • 部署方法需要更新

  • 服务配置可能会改变

  • 基础设施要求可能有所不同

迁移检查清单:

  • 盘点当前的 WAR 文件部署

  • 审查您环境的容器化需求

  • 规划向容器化服务的过渡时间表

  • 搭建容器基础设施(Docker/Kubernetes)

  • 部署并测试容器化服务

  • 更新服务连接配置

  • 如果仍需使用旧版 WAR 文件,请联系 Tiny 支持

迁移提示

  1. 备份与准备:升级前确保进行全面备份。

  2. 更新核心初始化:

    • 更新 theme 和 skin 设置以反映新的 oxide 主题和皮肤。在 TinyMCE 5 中,Silver 主题搭配 Oxide 皮肤已是标准配置,但请验证您的配置是否符合 TinyMCE 8 的要求。

    • 将 forced_root_block: false 选项更新为 forced_root_block: "p"。

    • 整合工具栏。

    • 审查 v8.0 新增的安全设置默认值。

    • 如果使用自托管,将许可证密钥更新为新格式。

  3. 插件迁移:

    • 从配置中移除已弃用的插件。

    • 更新重命名的插件(例如,spellchecker → tinymcespellchecker)。

    • 验证高级插件的兼容性。

    • 如果使用商业许可证,安装许可证密钥管理器插件。

  4. 自定义代码更新:

  5. CSS 更新:

    • 更新自定义样式以符合新的 Oxide 标准。尽管许多 .mce-* 类已被替换为 .tox-* 类,但仍有部分 .mce-* 前缀在使用。请审查您的 CSS 以确保兼容性。

    • 如果使用了自定义皮肤,请更新 split button CSS(TinyMCE 8 变更)。

  6. 测试与部署:

    • 在生产环境部署之前,请彻底测试更新后的配置。

    • 验证 media、iframe 和内容安全设置。

    • 测试 license key 功能和 premium 功能。

    • 验证 DOMPurify 针对您内容的净化行为。

其他资源

有用的链接

为了使您的升级顺利,请查看以下针对特定版本的迁移指南:

这些指南包含更深入的配置说明、插件替换和示例。

后续步骤

请务必仔细按照迁移步骤操作,以避免插件缺失、UI 损坏和意外的格式更改等常见问题。建议在最终部署之前,在 staging 环境中运行更新后的编辑器以进行完整验证。

迁移检查清单

在部署到生产环境之前,请验证:

  • License key 已更新为新格式(T8LK: 前缀)

  • 已安装 License Key Manager 附加组件(商业许可证)

  • 所有已弃用的 API 方法均已替换(editor.selection.setContent、editor.fire() 等)

  • 自定义皮肤已针对 TinyMCE 8 兼容性重新构建

  • DOMPurify 的净化行为已针对您的内容进行了测试

  • 如有必要,已配置跨域资源加载

  • 所有 premium 功能均正常工作

  • Media URL resolver 已更新以使用 Promises

  • 如有需要,Template 插件已替换为 premium Templates 插件

  • 语言包文件已更新为 RFC5646 格式

  • Accessibility checker 配置已针对 W3C 标准进行更新

  • 构建过程中已移除空文件引用

  • 已规划 Java Swing 集成迁移(如适用)

  • 已移除 Medical English 字典引用

  • WAR 文件部署已迁移到容器化服务

  • 已针对自定义皮肤更新 split button CSS

  • 已测试 Table 高度处理

  • 已验证通知关闭按钮的行为

  • 已审查 Sandbox iframes 配置

  • 已测试 Convert unsafe embeds 行为