简介

本指南全面概述了TinyMCE 8.0中引入的破坏性变更,以及从TinyMCE 7.x迁移的必要步骤。它涵盖了API、插件和服务配置的关键更新,包括弃用的方法、重命名的组件和移除的功能。这些变更旨在提高性能、简化配置并符合现代Web标准,确保迁移过程更顺畅,并保持与现有集成的兼容性。

破坏性变更快速参考

下表总结了TinyMCE 8.0中的所有破坏性变更。每个项目链接到指南中更详细的信息。

任何标记为“高”级别的项目在迁移期间需要立即关注。

破坏性变更影响级别

许可证密钥系统

自托管部署现在需要新的许可证密钥格式和许可证密钥管理器。旧密钥不兼容。

高

DOMPurify更新

清理现在更严格;之前允许的内容可能会被删除或修改。

高

editor.selection.setContent

方法已弃用。请改用editor.insertContent。

中

remove_trailing_brs

属性已从DomParser API中移除。

低

自动完成器配置

ch属性被trigger替代。

低

table_responsive_width

选项被table_sizing_mode替代。请参阅表格大小模式了解详情。

低

文本模式变更

默认触发键从Enter键改为Space键。

低

addButton, addMenuItem, windowManager.open

方法已弃用。请改用editor.ui.registry.* API。

中

editor.documentBaseUrl

未文档化的属性已移除。请改用editor.editorManager.documentBaseURI。

低

skipFocus和skip_focus

选项在ToggleToolbarDrawer中合并为skipFocus。

低

拆分按钮

拆分按钮的CSS类和结构已变更。

低

从版本7许可证密钥过渡到版本8.0许可证密钥

本节仅适用于自托管安装。对于云部署,许可证密钥管理会自动处理。

TinyMCE 8.0引入了增强的许可证密钥系统,在迁移期间需要特别注意。

完整的许可证文档许可证密钥管理涵盖以下内容:

  • 所有许可证类型(GPL、商业、带高级功能的GPL)的详细解释

  • 基于时间的与版本锁定的许可证密钥差异

  • 许可证状态(有效、宽限期、已过期、无效)

  • 部署选项(仅云、自托管、混合)

  • 每种设置的分步配置示例

  • 商业许可证密钥管理器的设置和要求

  • 故障排除和常见问题

影响:新的许可证密钥系统引入了破坏性变更,需要更新您的配置和代码。

关键迁移注意事项:

  • 许可证密钥格式变更:

    • 版本7密钥:与TinyMCE 8.0不兼容。

    • 新密钥使用前缀T8LK:表示商业许可证,或GPL+T8LK:表示带高级功能的GPL。

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

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

迁移步骤:

  1. 获取新许可证密钥:

  2. 更新配置:

    // 旧的TinyMCE 7配置
    tinymce.init({
      selector: '#editor',
      // 无需许可证密钥
    });
    
    // 新的TinyMCE 8配置
    tinymce.init({
      selector: '#editor',
      license_key: 'T8LK:...'  // 需要新格式
    });

许可证密钥管理器设置

当使用商业许可证迁移到TinyMCE 8.0时,需要许可证密钥管理器插件才能使编辑器运行。设置因您的部署方式而异:

CDN/静态托管:

  • 确保提供的licensekeymanager文件夹位于您的TinyMCE插件目录中:

your-site/
├── tinymce/
│ └── plugins/
│   ├── licensekeymanager/     # 添加此文件夹
│   │   ├── plugin.min.js
│   │   └── index.js
│   └── ... 其他插件

NPM/模块打包器:

安装TinyMCE并确保导入许可证密钥管理器:

// 导入 TinyMCE
import tinymce from 'tinymce';

// 导入许可证密钥管理器
import 'tinymce/plugins/licensekeymanager';

tinymce.init({
  selector: '#editor',
  license_key: 'T8LK:...'  // 需要新的格式
});

React/Next.js:

使用 @tinymce/tinymce-react 包时:

import { Editor } from '@tinymce/tinymce-react';
import 'tinymce/plugins/licensekeymanager';

export default function MyEditor() {
  return (
    <Editor
      init={{
        license_key: 'T8LK:...'
      }}
    />
  );
}

PHP/Laravel:

发布 TinyMCE 资源时,确保包含许可证密钥管理器:

<script src="{{ asset('path/to/tinymce/tinymce.min.js') }}"></script>
<script src="{{ asset('path/to/tinymce/plugins/licensekeymanager/plugin.min.js') }}"></script>
<script>
  tinymce.init({
    selector: '#editor',
    license_key: 'T8LK:...'
  });
</script>
  • 使用 Tiny Cloud 时会自动包含许可证密钥管理器。

  • 无需将该插件添加到 plugins 配置选项中。

  • 对于打包的应用,必须在 TinyMCE 初始化前加载许可证密钥管理器。

  • 对于打包的应用,请确保在构建优化过程中不要排除许可证密钥管理器。

有关许可证密钥管理器设置和故障排除的完整详细信息,请参阅设置商业许可证密钥管理器。

许可证迁移清单:

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

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

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

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

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

DOMPurify 更新与更严格的清理(破坏性变更)

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

这一变更提高了安全性,并与 DOMPurify 推荐的默认设置保持一致。然而,依赖先前较宽松清理行为的现有内容和集成可能会受到影响。

关键变更:

  • DOMPurify 升级至 3.2.6

  • 启用 SAFE_FOR_XML — 该设置对注释和属性值实施更严格的处理,防止某些 XSS 攻击向量。

  • 内容影响 — 包含标签的 HTML 注释、Internet Explorer 条件注释以及带有类 HTML 值的属性,现在在清理过程中可能会被移除。之前允许的内容可能会被删除。

影响:此变更通过防止之前允许的注释和属性中潜在的 XSS 攻击来提高安全性。然而,也可能导致内容被意外删除或修改。

迁移步骤:

  • 审查工作流并测试之前依赖宽松清理规则的内容。

  • TinyMCE 现在提供了 内容过滤:allow_html_in_comments 选项。启用此选项后,仍可启用清理,同时允许在注释中使用 HTML 标签。

使用 allow_html_in_comments 会增加 XSS 漏洞的风险。allow_html_in_comments 不推荐用于生产环境,除非您完全理解其影响并已采取适当的安全措施。
表 1. 示例:内容差异
内容TinyMCE 7 输出TinyMCE 8.0 输出

<div><!-- <p>Hello World</p> -→</div>

<div><!-- <p>Hello World</p> -→</div>

<div></div>

<iframe><!-- Hello World -→</iframe>

<p><iframe sandbox=""><!-- Hello World -→</iframe></p>

``

<script><!-- Hello World -→</script>

<script><!-- Hello World -→</script>

``

有关禁用 DOMPurify 清理的信息(不推荐),请参阅 xss_sanitization 选项。

核心变更

自定义皮肤的拆分按钮样式更新

在 TinyMCE 8 中,拆分工具栏按钮现渲染为两个独立组件:一个用于主要操作,另一个用于下拉箭头。

这一结构性变更修改了拆分按钮的 DOM 布局,可能会导致依赖先前结构的自定义 CSS 规则失效。

影响:此变更仅影响使用 自定义皮肤 的集成人员。

迁移指南:

如果您的实现包含自定义 skin,请按照以下步骤操作,以确保兼容性:

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

  • 使用 TinyMCE 8 代码库重新构建您的自定义 skin。请参阅 创建 Skin 获取说明。

  • 更新您的拆分按钮用法,以适配新的结构,包括对 chevronTooltip 选项的支持。有关更新的配置详情,请参阅 拆分工具栏按钮。

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

变更摘要:

  • 拆分按钮现在渲染为两个独立的 DOM 元素。

  • 依赖于旧结构的 CSS 选择器和样式可能不再正确应用。

  • chevronTooltip API 选项现已支持。

核心 API 变更

破坏性变更概述

以下部分详细说明了需要更新代码的重要变更。请仔细阅读每个部分。

更新的方法

skipFocus 和 skip_focus

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.documentBaseUrl

未公开的 editor.documentBaseUrl 属性已被移除。

示例用法
// 在 TinyMCE 8 中已移除
console.log('documentBaseUrl', editor.documentBaseUrl);

// 替代用法
console.log('documentBaseURI', editor.editorManager.documentBaseURI.getURI());
使用 editor.editorManager.documentBaseURI.getURI() 进行所有基 URL 操作。

影响:此变更通过移除未公开且与文档化的 documentBaseURI 属性不一致的 API,提高了 URL 处理的一致性。

迁移步骤:

要将 documentBaseUrl 的所有引用更新为新 API,请将任何 editor.documentBaseUrl(或类似)的用法替换为 editor.editorManager.documentBaseURI.getURI()。属性 documentBaseUrl 已被移除,现在访问文档基 URL 的正确方式是通过 editorManager.documentBaseURI 属性,它是一个 URI 对象。您可以在其上调用 .getURI() 以获取 URL 的字符串值。

例如,将此代码:
const baseUrl = editor.documentBaseUrl;

更新为:

const baseUrl = tinymce.activeEditor.editorManager.documentBaseURI.getURI();

进行此变更是必要的,因为未公开的 editor.documentBaseUrl API 已被移除,以提高 URL 处理的一致性。新方法使用文档化的 documentBaseURI 属性,该属性提供一个 URI 对象,并具有 getURI() 等方法来检索完整的 URL 字符串。

有关更多信息,请参阅:tinymce.editor/#properties。

迁移清单:

  • 在代码库中搜索所有 editor.documentBaseUrl 的实例。

  • 将其替换为 tinymce.activeEditor.editorManager.documentBaseURI.getURI()(如果您有 editor 引用,也可以使用 editor.editorManager.documentBaseURI.getURI())。


弃用的方法

editor.selection.setContent

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

影响:此变更通过整合插入方法简化了内容操作。

迁移步骤:

要替换 editor.selection.setContent,请改用 editor.insertContent。新方法与其他 TinyMCE 内容操作方法更加一致。

示例用法
// TinyMCE 8 中已弃用,将在 9 中移除
editor.selection.setContent('<p>New content</p>');

// 推荐的替代方法
editor.insertContent('<p>New content</p>');

迁移清单:

  • 将所有 editor.selection.setContent 的实例替换为 editor.insertContent

  • 更新使用旧方法的自定义插件

  • 在您的编辑器实例中测试内容插入

从 DomParser 中移除 remove_trailing_brs 属性

remove_trailing_brs 设置在 TinyMCE 6.5 中已被弃用,并在 TinyMCE 7.0 中从 DomParser API 中移除。

影响:

  • DomParser 不再支持 remove_trailing_brs 选项

  • 这会影响自定义的 DomParser 配置

  • 可能会影响内容解析行为

迁移步骤:

  1. 从 DomParser 配置中移除 remove_trailing_brs

  2. 测试内容解析行为

  3. 更新任何自定义的 DomParser 实现

迁移清单:

  • 从 DomParser 配置中移除 remove_trailing_brs

  • 测试内容解析行为

  • 更新任何自定义的 DomParser 实现

Autocompleter 配置变更

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

迁移步骤:

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

  2. 测试自动补全器功能

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

示例:
// Old TinyMCE 6 configuration
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' }
    ];
  }
});

// New TinyMCE 7+ configuration
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 替代

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

迁移步骤:

  1. 在您的配置中,将 table_responsive_width 替换为 table_sizing_mode

  2. 更新选项值以匹配新的 API

  3. 测试表格的响应式行为

示例:
// Old TinyMCE 6 configuration
tinymce.init({
  selector: "textarea",
  table_responsive_width: true
});

// New TinyMCE 7+ configuration
tinymce.init({
  selector: "textarea",
  table_sizing_mode: "responsive"
});

迁移清单:

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

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

  • 测试表格的响应式行为

文本模式变更

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

影响:

  • Markdown 风格的格式化现在在按下空格键时触发

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

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

迁移步骤:

  1. 测试现有的文本模式行为

  2. 如果需要 Enter 键触发,则更新配置

  3. 评估新空格键触发模式的用户体验

  4. 考虑更新有关文本模式行为的用户文档

示例:
// Default TinyMCE 7+ behavior (Space key trigger)
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' }
  ]
});

// Restore previous behavior (Enter key trigger)
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' }
  ]
});

迁移清单:

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

  • 如果需要 Enter 键触发,则更新配置

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

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

addButton、addMenuItem 和 windowManager.open

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

// 在 TinyMCE 8 中已弃用,将在 9 中移除
// 添加按钮的旧方法
editor.addButton('myButton', {
  text: 'My Button',
  onclick: function() {
    editor.insertContent('Hello World!');
  }
});

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

迁移清单:

  • 将所有 editor.addButton 实例替换为 editor.ui.registry.addButton

  • 将所有 editor.addMenuItem 实例替换为 editor.ui.registry.addMenuItem

  • 将所有 editor.windowManager.open 实例替换为 editor.windowManager.open

  • 更新使用旧方法的自定义插件

  • 在编辑器实例中测试按钮和菜单功能

fire()

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

// 在 TinyMCE 8 中已弃用,将在 9 中移除
// 触发自定义事件的旧方法
editor.fire('someEvent');

// 触发自定义事件的新方法
editor.dispatch('someEvent');

影响:此更改使 TinyMCE 符合现代事件处理惯例,使 API 对开发者更加直观。

迁移清单:

  • 在代码库中搜索所有 fire() 方法的使用

  • 将每个实例替换为 dispatch()

  • 审查并更新第三方插件

  • 测试所有自定义事件处理


插件更新

语言包文件名更改

语言包文件名已标准化为遵循 RFC5646 格式。此更新确保跨平台语言处理的一致性,并改进国际化支持。虽然 TinyMCE 8.0 支持旧的下划线格式(例如 en_GB.js)和新的连字符格式(例如 en-GB.js),但下划线格式已弃用,将在 TinyMCE 9 中移除。现在迁移到 RFC5646 格式可确保未来兼容性,并减少即将升级期间的维护开销。

影响:使用基于下划线格式的自定义语言包和配置应在升级到 TinyMCE 9 之前更新,以避免加载失败。

迁移清单:

  • 识别部署中的所有语言包文件

  • 将文件重命名为 RFC5646 格式(例如,en_GB.js → en-GB.js)

  • 更新对语言文件的配置引用

  • 更新处理语言文件的构建脚本

  • 在应用程序中测试语言切换

  • 更新自定义翻译文件以使用新格式

// 已弃用的格式(仅在 8.x 版本中支持)
language_url: '/langs/en_GB.js'

// 推荐的格式
language_url: '/langs/en-GB.js'
对下划线格式的支持将在 TinyMCE 9 中移除。建议尽早迁移。

更新 Image 和 Accessibility Checker 插件

Image 和 Accessibility Checker 插件现在遵循最新的 W3C 装饰性图像标准,要求使用空的 alt 属性,而不是 role="presentation" 属性。此更改有助于改进可访问性支持。

影响:使用这些插件的客户需要更新其配置,以确保继续符合可访问性标准。

迁移清单:

  • 识别内容中以前使用 role="presentation" 作为装饰性目的的图像

  • 用空的 alt 属性 alt="" 替换这些属性

  • 如已自定义,更新图像插件配置

  • 使用更新后的内容测试可访问性检查器

有关更改的更多信息,请参阅:Accessibility Checker: Image rules。

跨源资源加载配置

升级到 TinyMCE 8 时,需要审查并可能更新集成处理跨源资源加载的方式。TinyMCE 8 提供了一个新配置选项,用于控制加载资源的 crossorigin 属性。

需要检查的事项:

  1. 如果使用 Tiny Cloud:

    • 确保 script 标签包含两个必需的属性:

      <script src="https://cdn.tiny.cloud/1/no-api-key/tinymce/8/tinymce.min.js" referrerpolicy="origin" crossorigin="anonymous"></script>
  2. 如果应用程序从不同域加载资源(脚本或样式表):

    • 配置新的 crossorigin 函数,以控制所有资源的 crossorigin 属性。

      示例:配置 crossorigin 函数
      const crossOriginFunction = (url, resourceType) => {
          // 在此返回 'anonymous' 或 'use-credentials' 将显式设置该属性
          return 'anonymous';
          // return 'use-credentials';
          // return undefined; // 通过返回 undefined 为所有资源省略 'crossorigin' 属性
      };
      
      tinymce.init({
        selector: "textarea",
        crossorigin: crossOriginFunction
      });
  3. 如果您使用来自不同域的 content_css:

    • 对于样式表,content_css_cors 选项具有优先权。

    • 如果您使用跨域样式表,请检查您的 content_css 配置。

迁移清单:

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

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

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

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

有关新的 crossorigin 函数 API 的完整详细信息,请参阅:crossorigin 配置选项。

技术清理

删除的空文件

从代码库中删除了几个空文件,以减少杂乱并改善维护:

  • 来自 Comments 插件的空 CSS 文件

  • 来自 Mentions 插件的空 LESS 文件

影响:这些更改没有功能性影响,但可能会影响明确引用这些文件的自定义构建流程。

迁移清单:

  • 检查构建流程中是否有对 Comments 插件 CSS 的引用

  • 检查构建流程中是否有对 Mentions 插件 LESS 的引用

  • 删除这些空文件的任何导入

  • 删除后测试 Comments 和 Mentions 插件

服务和配置更改

Java Swing 集成弃用

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

影响:使用 Java Swing 集成的客户需要迁移到替代解决方案。

迁移清单:

  • 评估替代集成选项

  • 规划从 Java Swing 集成的迁移

有关 Java Swing 集成的信息,请参阅:TinyMCE for Java Swing 集成

停止提供 Medical English (UK)

由于许可限制,"Medical English (UK)" 词典已被移除。使用此功能的客户必须相应更新其配置。

影响:依赖此词典的用户将需要为医疗特定的拼写检查做出其他安排。

迁移清单:

  • 从拼写检查器配置中移除 "Medical English (UK)"

  • 移除任何与 Medical English 相关的自定义词典集成

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

  • 如需要,配置替代的医疗词典

服务版本与 TinyMCE 编辑器解耦

以前与编辑器捆绑的服务,如 Java Servlet 服务,不再包含在 TinyMCE 8.0 包中。客户应迁移到容器化服务部署或考虑其他托管选项。

影响:这减少了编辑器和后端服务之间的依赖关系,简化了更新和维护。

迁移步骤:

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

TinyMCE 8.0 不再包含后端服务(如拼写检查器)的 Java WAR 文件。客户需要迁移到现代 Docker/OCI 容器以进行自托管部署。

影响:这降低了基础设施复杂性,并与现代 DevOps 实践保持一致。

迁移清单:

  • 盘点当前的 WAR 文件部署

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

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

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

  • 部署和测试容器化服务

  • 更新服务连接配置

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

有关使用 Docker 部署服务端组件的更多信息,请参阅:容器化服务部署。

结论

升级到 TinyMCE 8.0 要求集成商更新其 API 调用、插件配置和服务集成,以适应此版本中引入的破坏性更改。虽然一些调整可能涉及重大的代码更新,但这些增强旨在简化开发并改善整体编辑器体验。

有关更多指导,请参阅:

  • TinyMCE 文档。

  • 联系Tiny 支持寻求帮助。

  • 尝试 TinyMCE 新的Ask AI小部件,它将为您提供帮助,只需点击任何文档页面右下角的图标即可。

Ask AI 小部件

其他资源

有关 TinyMCE 8.0 变更的更多详细信息,请参阅TinyMCE 8.0 发布说明。