简介
本指南全面概述了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。商业许可证管理器:自托管商业部署需要新的许可证密钥管理器插件。
迁移步骤:
获取新许可证密钥:
更新配置:
// 旧的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 不推荐用于生产环境,除非您完全理解其影响并已采取适当的安全措施。| 内容 | TinyMCE 7 输出 | TinyMCE 8.0 输出 |
|---|---|---|
|
|
|
|
| `` |
|
| `` |
有关禁用 DOMPurify 清理的信息(不推荐),请参阅 xss_sanitization 选项。
核心变更
自定义皮肤的拆分按钮样式更新
在 TinyMCE 8 中,拆分工具栏按钮现渲染为两个独立组件:一个用于主要操作,另一个用于下拉箭头。
这一结构性变更修改了拆分按钮的 DOM 布局,可能会导致依赖先前结构的自定义 CSS 规则失效。
影响:此变更仅影响使用 自定义皮肤 的集成人员。
迁移指南:
如果您的实现包含自定义 skin,请按照以下步骤操作,以确保兼容性:
确认您的项目是否使用了自定义 skin。
使用 TinyMCE 8 代码库重新构建您的自定义 skin。请参阅 创建 Skin 获取说明。
更新您的拆分按钮用法,以适配新的结构,包括对
chevronTooltip选项的支持。有关更新的配置详情,请参阅 拆分工具栏按钮。测试拆分按钮在编辑器中的渲染和交互,以验证预期行为。
变更摘要:
拆分按钮现在渲染为两个独立的 DOM 元素。
依赖于旧结构的 CSS 选择器和样式可能不再正确应用。
chevronTooltipAPI 选项现已支持。
核心 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 配置
可能会影响内容解析行为
迁移步骤:
从 DomParser 配置中移除
remove_trailing_brs测试内容解析行为
更新任何自定义的 DomParser 实现
迁移清单:
从 DomParser 配置中移除
remove_trailing_brs测试内容解析行为
更新任何自定义的 DomParser 实现
Autocompleter 配置变更
自动补全器的 ch 配置属性已被移除。请使用 trigger 属性代替。
迁移步骤:
在自动补全器配置中,将
ch: '<string>'替换为trigger: '<string>'测试自动补全器功能
更新任何自定义的自动补全器实现
// 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 替代。
迁移步骤:
在您的配置中,将
table_responsive_width替换为table_sizing_mode更新选项值以匹配新的 API
测试表格的响应式行为
// 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 键行为这会影响所有文本模式,包括标题、列表、引用块和水平分隔线
迁移步骤:
测试现有的文本模式行为
如果需要 Enter 键触发,则更新配置
评估新空格键触发模式的用户体验
考虑更新有关文本模式行为的用户文档
// 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 属性。
需要检查的事项:
如果使用 Tiny Cloud:
确保 script 标签包含两个必需的属性:
<script src="https://cdn.tiny.cloud/1/no-api-key/tinymce/8/tinymce.min.js" referrerpolicy="origin" crossorigin="anonymous"></script>
如果应用程序从不同域加载资源(脚本或样式表):
配置新的 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 });
如果您使用来自不同域的 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 调用、插件配置和服务集成,以适应此版本中引入的破坏性更改。虽然一些调整可能涉及重大的代码更新,但这些增强旨在简化开发并改善整体编辑器体验。
有关更多指导,请参阅:
联系Tiny 支持寻求帮助。
尝试 TinyMCE 新的Ask AI小部件,它将为您提供帮助,只需点击任何文档页面右下角的图标即可。

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