从6迁移到8

最后更新：2026-11-04 10:10:15

概述

TinyMCE 已从版本 6 显著演进到版本 8.0，引入了架构改进、现代化的 UI 增强、更严格的安全默认设置以及更新的插件结构。本综合指南概述了从 TinyMCE v6 升级到 v8.0 所需的关键破坏性变更、推荐的迁移操作步骤和顶层配置调整。

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

主要变更

插件生态系统

TinyMCE 插件生态系统从版本 7.0 开始发生变化，几个插件被移除或重新分类。

已移除的插件（从 TinyMCE 7.0 开始不再可用）：
- template：在 7.0 中被移除。由高级模板插件替代。
集成到 TinyMCE 核心（在 6.0 中被移除，早于此迁移路径）：
- textcolor：在 6.0 中作为单独插件被移除。文本颜色功能现在通过 forecolor 和 backcolor 工具栏按钮成为 TinyMCE 核心的一部分，无需额外插件即可使用。
现在仅限高级版（在 6.0 中被移除，早于此迁移路径）：
- imagetools：在 6.0 中被移除。由高级增强图像编辑功能替代，可通过 TinyMCE 6.0 中引入的 editimage 插件使用。

如果从 TinyMCE 6 迁移，这些插件（imagetools 和 textcolor）已在版本 6.0 中移除，因此无需迁移。以下部分仅供参考，适用于从旧版本升级或代码库中包含遗留引用的情况。

插件迁移示例

template（在 v7 中被移除）：
- 使用高级模板插件或实现自定义模态对话框。
- 对于复杂的模板需求，考虑使用高级模板。
imagetools（在 v6 中被移除）：
- 使用高级增强图像编辑功能。
- 确保您拥有增强图像编辑功能的有效商业许可证。
textcolor（在 v6 中集成到核心）：
- 文本颜色功能现在内置在 TinyMCE 核心中。使用 forecolor 和 backcolor 工具栏按钮，无需额外插件即可使用。

内容结构

内容结构要求已更新：

要求：所有编辑器内容必须包含在块级元素中（例如，<p>）。

配置变更

在版本 7 和 8 中，几个配置选项已更新：

新的默认值：
- highlight_on_focus：现在默认为 true（为编辑器添加焦点轮廓）
- convert_unsafe_embeds：现在默认为 true（将 object/embed 元素转换为更安全的替代方案）
- sandbox_iframes：现在默认为 true（为 iframe 添加 sandbox 属性）
- sandbox_iframes_exclusions：要从 iframe sandboxing 中排除的 URL 主机列表
- license_key：必须设置为 gpl 或有效的许可证密钥
- 新的 crossorigin 配置选项，用于跨域资源加载

示例：

tinymce.init({
  selector: "textarea",
  highlight_on_focus: true,
  convert_unsafe_embeds: true,
  sandbox_iframes: true,
  sandbox_iframes_exclusions: ["youtube.com", "vimeo.com"],
  license_key: "T8LK:...", // 需要新格式
  crossorigin: (url, resourceType) => 'anonymous'
});

许可变更（GPL v2+ 和商业版）

TinyMCE 8.0 对许可系统进行了重大更改：

新格式：许可证密钥现在使用前缀 T8LK:（商业许可证）或 GPL+T8LK:（带有高级功能的 GPL）
许可证密钥管理器：自托管的商业部署需要新的许可证密钥管理器插件
强制许可证密钥：所有部署现在都需要有效的许可证密钥

示例：

tinymce.init({
  selector: "textarea",
  license_key: "T8LK:your-license-key" // 需要新格式
});

许可证迁移检查清单：

联系支持以获取新的 TinyMCE 8.0 许可证密钥，或为开源版本使用 GPL
为商业许可证安装许可证密钥管理器插件
使用新的许可证密钥格式更新配置
使用新许可证测试编辑器功能
验证所有高级功能是否正常工作

API 变更

在 TinyMCE 8 中已弃用

editor.selection.setContent

editor.selection.setContent API 已被弃用，将在 TinyMCE 9 中移除。

示例：

// 在 TinyMCE 8 中已弃用，将在 9 中移除
editor.selection.setContent('<p>新内容</p>');

// 新方法
editor.insertContent('<p>新内容</p>');

迁移清单：

将所有 editor.selection.setContent 实例替换为 editor.insertContent
更新使用旧方法的自定义插件
在编辑器实例中测试内容插入功能

fire() 方法

用于事件处理的 fire() 方法已被 dispatch() 取代。为避免命名混淆，fire() 方法将在 TinyMCE 9 中移除。

示例：

// 在 TinyMCE 8 中已弃用，将在 9 中移除
editor.fire('someEvent');

// 新方法
editor.dispatch('someEvent');

影响：此变更使 TinyMCE 符合现代事件处理规范，让 API 对开发者更直观。

迁移清单：

在代码库中搜索所有使用 fire() 方法的地方
将每个实例替换为 dispatch()
审查并更新第三方插件
测试所有自定义事件处理

addButton、addMenuItem 和 windowManager.open

addButton、addMenuItem 和 windowManager.open 方法已被 editor.ui.registry.* API 取代。

示例：

// 在 TinyMCE 8 中已弃用，将在 9 中移除
editor.addButton('myButton', {
  text: '我的按钮',
  onclick: function() {
    editor.insertContent('Hello World!');
  }
});

// 新方法
editor.ui.registry.addButton('myButton', {
  text: '我的按钮',
  onAction: function() {
    editor.insertContent('Hello World!');
  }
});

迁移清单：

将所有 editor.addButton 实例替换为 editor.ui.registry.addButton
将所有 editor.addMenuItem 实例替换为 editor.ui.registry.addMenuItem
将所有 editor.windowManager.open 实例替换为 editor.windowManager.open
更新使用旧方法的自定义插件
在编辑器实例中测试按钮和菜单功能

editor.documentBaseUrl

editor.documentBaseUrl 属性已被移除。请改用 editor.editorManager.documentBaseURI.getURI()。

迁移步骤：

在代码库中搜索所有 editor.documentBaseUrl 实例
将其替换为 tinymce.activeEditor.documentBaseURI.getURI()（如果有 editor 引用，则使用 editor.documentBaseURI.getURI()）
测试依赖文档基础 URL 的功能

示例：

// 在 TinyMCE 8 中已弃用，将在 9 中移除
const baseUrl = editor.documentBaseUrl;

// 新方法
const baseUrl = editor.editorManager.documentBaseURI.getURI();

影响：此变更移除了与文档化 documentBaseURI 属性不一致的未文档化 API，提高了 URL 处理的一致性。

迁移清单：

在代码库中搜索所有 editor.documentBaseUrl 实例。
将其替换为 tinymce.activeEditor.editorManager.documentBaseURI.getURI()（如果有 editor 引用，则使用 editor.editorManager.documentBaseURI.getURI()）。

skipFocus 和 skip_focus 整合

在 TinyMCE 8.0 中，ToggleToolbarDrawer 命令的 skipFocus 和 skip_focus 选项已整合为一个更一致的参数。有关更多信息，请参阅可用命令。

影响：

降低 API 复杂度
明确预期行为
需要更新命令调用

迁移步骤：

定位所有 ToggleToolbarDrawer 命令的使用实例
在命令参数中将 skipFocus 替换为 skip_focus
测试工具栏抽屉行为

示例：

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

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

迁移清单：

定位所有 ToggleToolbarDrawer 命令的用法
在命令选项中将 skipFocus 替换为 skip_focus
更新任何使用此命令的自定义插件
在更改后测试 toolbar drawer 行为

已移除的方法

旧版 API 方法

从 TinyMCE core 6.0 版本开始，已移除 InsertOrderedList 和 InsertUnorderedList 命令，现在由 Lists 插件提供。

自动补全器 `ch` 属性

自动补全器的 ch 配置属性已在 TinyMCE 7.0 中移除。请改用 trigger 属性。

迁移步骤：

在自动补全器配置中，将 ch: '<string>' 替换为 trigger: '<string>'
测试自动补全器功能
更新任何自定义的自动补全器实现

示例：

// 旧版 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>'
测试自动补全器功能
更新任何自定义的自动补全器实现

remove_trailing_brs 属性

remove_trailing_brs 设置在 TinyMCE 7.0 中已从 DomParser API 移除，该设置在 TinyMCE 6.5 中已被弃用。有关 DomParser 的更多信息，请参阅 DomParser API。

影响：

DomParser 不再支持 remove_trailing_brs 选项
这会影响自定义的 DomParser 配置
可能会影响内容解析行为

迁移清单：

从 DomParser 配置中移除 remove_trailing_brs
测试内容解析行为
更新任何自定义的 DomParser 实现

文本模式变更

TinyMCE 7.0 更新了 text_patterns 的默认行为，现在当用户按下 Space 键而不是 Enter 键时应用格式。

影响：

现在按下 Space 键会触发 Markdown 风格的格式
可以通过配置 trigger: 'enter' 恢复之前的 Enter 键行为
这会影响所有文本模式，包括标题、列表、引用块和水平分隔线

迁移步骤：

测试现有的文本模式行为
如果需要 Enter 键触发，则更新配置
评估新 Space 键触发的用户体验
考虑更新关于文本模式行为的用户文档

示例：

// TinyMCE 7+ 默认行为（Space 键触发）
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' }
  ]
});

// 恢复之前的行为（Enter 键触发）
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' }
  ]
});

迁移清单：

测试现有的 Space 键触发文本模式行为
如果需要 Enter 键触发，则更新配置
评估新 Space 键触发的用户体验
更新关于文本模式行为的用户文档

table_responsive_width 已被 table_sizing_mode 取代

table_responsive_width 选项在 TinyMCE 7.0 中已被 table_sizing_mode 取代。

迁移步骤：

在您的配置中，将 table_responsive_width 替换为 table_sizing_mode
更新选项值以匹配新的 API
测试表格的响应式行为

示例：

// 旧版 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
测试表格响应行为

force_hex_color选项

force_hex_color选项在TinyMCE 7.0中被移除。现在只有像rgb(255, 255, 255)这样的绝对格式RGB值会被转换为HEX值。

插件变更

移除Template插件

template插件在TinyMCE 7.0中被移除。如果您正在使用此插件，需要迁移到付费的Templates插件。

迁移步骤：1. 从插件列表中移除template2. 将templates添加到插件列表中3. 更新配置以使用新的Templates插件API

迁移清单：

如果使用了，从配置中移除template插件
评估是否需要付费的Templates插件(advtemplate)
移除所有与模板相关的配置选项
更新所有自定义模板实现
如果迁移到付费插件，测试模板功能

移除Image Tools插件

本节仅适用于从TinyMCE 5或更早版本升级的情况。imagetools插件在TinyMCE 6.0中被移除，因此如果您是从TinyMCE 6迁移，此插件已不可用。

imagetools插件在TinyMCE 6.0中被移除。如果您正在使用此插件，需要迁移到付费的Enhanced Image Editing功能。

迁移步骤：1. 从插件列表中移除imagetools2. 将editimage添加到插件列表中（付费功能）3. 确保您拥有Enhanced Image Editing功能的有效商业许可证4. 更新所有自定义图像编辑配置

迁移清单：

从插件列表中移除imagetools
将editimage添加到插件列表中（付费功能）
确保您拥有Enhanced Image Editing的有效商业许可证
更新所有自定义图像编辑配置
测试图像编辑功能

示例：

// 旧的TinyMCE 5配置
tinymce.init({
  selector: "textarea",
  plugins: "imagetools",
  imagetools_toolbar: "rotateleft rotateright | flipv fliph | editimage imageoptions"
});

// 新的TinyMCE 6+配置
tinymce.init({
  selector: "textarea",
  plugins: "editimage", // 付费功能
  editimage_toolbar: "rotateleft rotateright | flipv fliph | editimage imageoptions"
});

Text Color插件（已集成到核心）

本节仅适用于从TinyMCE 5或更早版本升级的情况。textcolor插件在TinyMCE 6.0中被移除，因此从TinyMCE 6迁移无需操作。

textcolor插件在TinyMCE 6.0中作为单独插件被移除，因为其功能已集成到TinyMCE核心中。forecolor和backcolor工具栏按钮无需额外插件即可使用。

迁移清单：

从插件列表中移除textcolor
forecolor和backcolor工具栏按钮仍作为核心工具栏按钮可用

示例：

// 旧的TinyMCE 5配置
tinymce.init({
  selector: "textarea",
  plugins: "textcolor",
  toolbar: "forecolor backcolor"
});

// 新的TinyMCE 6+配置（无需插件）
tinymce.init({
  selector: "textarea",
  toolbar: "forecolor backcolor"
});

Media URL Resolver变更

在TinyMCE 6及更早版本中，media_url_resolver选项提供resolve和reject回调，而不是Promise。在TinyMCE 7.0中，media_url_resolver选项现在需要返回一个Promise。

迁移清单：

更新media_url_resolver实现以返回Promise，而不是使用回调
从解析器函数中移除resolve和reject回调参数
使用更新后的解析器测试媒体嵌入功能
更新所有自定义媒体URL解析器实现

示例：

// 旧的TinyMCE 6方法
tinymce.init({
  selector: "textarea",
  media_url_resolver: function(data, resolve, reject) {
    // 此处为自定义逻辑
    resolve(data.url);
  }
});

// 新的TinyMCE 7+方法
tinymce.init({
  selector: "textarea",
  media_url_resolver: function(data) {
    return new Promise(function(resolve, reject) {
      // 此处为自定义逻辑
      resolve(data.url);
    });
  }
});

UI和UX变更

表格高度变更

TinyMCE 7.0引入了对表格高度处理方式的变更。

在TinyMCE 7.0中，单元格和行高度应用于表格的方式已更改：

当使用调整大小手柄或“行属性”对话框调整表格大小时，现有的height样式将从适用的td/th元素中剥离，仅应用于table元素和tr元素。

通知关闭按钮

在TinyMCE的先前版本中，通知可以在没有关闭按钮（X）的情况下显示。可访问性是编辑器的重要组成部分，当通知中没有此按钮时，无法通过键盘导航关闭该通知。

在TinyMCE 7.0中，现在强制通知必须包含关闭按钮以提高可访问性。

拆分按钮更改

在TinyMCE 8.0中，拆分工具栏按钮现在渲染为两个不同的组件：一个用于主要操作，另一个用于下拉箭头。

此结构更改修改了拆分按钮的DOM布局，可能会破坏依赖于先前结构的自定义CSS规则。

迁移步骤：

更新拆分按钮的使用方式以适应新结构，包括对 chevronTooltip 选项的支持。有关更新的配置详细信息，请参阅拆分工具栏按钮。
测试编辑器中拆分按钮的渲染和交互，以验证预期行为。

迁移清单：

确认您的项目是否使用自定义皮肤。
使用TinyMCE 8.0代码库重新构建您的自定义皮肤。有关说明，请参阅创建皮肤。
更新拆分按钮的使用方式以适应新结构，包括对 chevronTooltip 选项的支持。有关更新的配置详细信息，请参阅拆分工具栏按钮。
测试编辑器中拆分按钮的渲染和交互，以验证预期行为。

安全更改

沙箱Iframe

在TinyMCE 7.0中，sandbox_iframes 的默认值从 false 更改为 true，这意味着插入编辑器的所有 iframe 元素默认都会获得 sandbox="" 属性，从而阻止大多数操作，包括脚本执行和同源访问，这可能会破坏现有编辑器内容或产生不良效果。

为了防止任何预期的iframe被沙箱化，我们建议将此类iframe的源域添加到新的 sandbox_iframes_exclusions 选项列表中，并在必要时将域包含在默认列表中。要防止所有iframe被沙箱化，请在编辑器配置中将 sandbox_iframes 选项设置为 false。

转换不安全的嵌入

在TinyMCE 7.0中，convert_unsafe_embeds 的默认值从 false 更改为 true，这意味着所有 object 和 embed 标签在插入编辑器时会自动转换为不同的元素。

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);

跨域资源加载

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

新配置：

外部资源的 crossorigin 属性支持
增强加载外部内容的安全性
更好地控制资源加载策略

迁移清单：

验证云部署的script标签属性。
如果使用跨域资源，配置 crossorigin 函数。
在部署环境中测试资源加载。
如果使用跨域样式表，检查 content_css 配置。

服务更改

Java Swing集成弃用

TinyMCE的Java Swing集成在TinyMCE 8.0中已被弃用，并将于2025年12月31日达到生命周期终点。

迁移步骤：

评估替代集成选项
计划在2025年12月31日之前完成的迁移时间表

迁移清单：

评估备选集成方案
规划迁移时间线，确保在 2025 年 12 月 31 日之前完成

Medical English Dictionary Discontinuation

“Medical English (UK)” 字典已停用，在 TinyMCE 8.0 中不再可用。

迁移检查清单：

从拼写检查器配置中移除 “Medical English (UK)”
移除所有与 Medical English 相关的自定义字典集成
使用其余字典测试拼写检查功能
根据需要配置替代的医学字典

Transition from Java WAR Files to Containerized Services

TinyMCE 8.0 不再包含用于拼写检查器等后端服务的 Java WAR 文件。对于自托管部署，客户需要迁移到现代的 Docker/OCI 容器。

迁移检查清单：

盘点当前的 WAR 文件部署
审查您环境的容器化需求
规划向容器化服务的过渡时间线
搭建容器基础设施（Docker/Kubernetes）
部署并测试容器化服务
更新服务连接配置
如果您仍需要旧版 WAR 文件，请联系 Tiny Support

Migration Tips

License Migration checklist:

联系支持团队获取新的 TinyMCE 8.0 许可证密钥，或为开源版本使用 GPL
为商业许可证安装许可证密钥管理器插件
使用新的许可证密钥格式更新配置
使用新许可证测试编辑器功能
验证所有高级功能是否正常运行

Custom Skin Migration checklist:

确认您的项目是否使用了自定义外观。
使用 TinyMCE 8 代码库重新构建您的自定义外观。有关说明，请参阅 Creating a Skin。
更新您的拆分按钮使用方式，使其与新结构保持一致，包括对 chevronTooltip 选项的支持。有关更新的配置详情，请参阅 Split Toolbar Buttons。
测试编辑器中拆分按钮的渲染和交互，以验证预期行为。

General Migration checklist:

许可证密钥已更新为新格式（T8LK: 前缀）
许可证密钥管理器插件已安装（商业许可证）
所有已弃用的 API 方法已被替换（editor.selection.setContent、editor.fire() 等）
自定义外观已重新构建，以兼容 TinyMCE 8
已使用您的内容测试 DOMPurify 清理行为
已根据需要配置跨源资源加载
所有高级功能均正常运行
Media URL resolver 已更新，以使用 Promise
Autocompleter 配置使用 trigger 而非 ch
Template 插件已根据需要替换为高级版 Templates 插件
语言包文件已更新为 RFC5646 格式
可访问性检查器配置已根据 W3C 标准进行更新
构建过程中已移除空文件引用
已规划 Java Swing 集成迁移（如适用）
已移除 Medical English 字典引用
WAR 文件部署已迁移至容器化服务
拆分按钮的 CSS 已针对自定义外观进行更新
已测试表格高度处理
已验证通知关闭按钮的行为
已审查沙盒 iframe 配置
已测试不安全嵌入转换行为

Additional Resources

Helpful Links

为了使您的升级过程顺利，请查看以下特定版本的迁移指南：

Migrating from TinyMCE 5 to TinyMCE 6

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

Next Steps

完成迁移后：

全面测试所有功能
更新您的文档
向您的团队培训任何新功能
考虑升级到最新版本的 TinyMCE，以获得持续支持

从6迁移到8

概述

主要变更

插件生态系统

插件迁移示例

内容结构

配置变更

许可变更（GPL v2+ 和商业版）

API 变更

在 TinyMCE 8 中已弃用

editor.selection.setContent

fire() 方法

addButton、addMenuItem 和 windowManager.open

editor.documentBaseUrl

skipFocus 和 skip_focus 整合

已移除的方法

旧版 API 方法

自动补全器 ch 属性

remove_trailing_brs 属性

文本模式变更

table_responsive_width 已被 table_sizing_mode 取代

force_hex_color选项

插件变更

移除Template插件

移除Image Tools插件

Text Color插件（已集成到核心）

Media URL Resolver变更

UI和UX变更

表格高度变更

通知关闭按钮

拆分按钮更改

安全更改

沙箱Iframe

转换不安全的嵌入

DOMPurify更新

跨域资源加载

服务更改

Java Swing集成弃用

Medical English Dictionary Discontinuation

Transition from Java WAR Files to Containerized Services

Migration Tips

License Migration checklist:

Custom Skin Migration checklist:

General Migration checklist:

Additional Resources

Helpful Links

Next Steps

自动补全器 `ch` 属性