概述
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 核心处理。
现在仅限高级版:
插件迁移示例
contextmenu(在 v6 中移除):使用浏览器原生上下文菜单或自定义逻辑。
考虑使用
editor.ui.registry.addContextMenu来实现自定义右键操作。有关更多信息,请参见上下文菜单。
bbcode(在 v6 中移除):如果需要 BBCode 支持,请实现自定义解析或服务器端处理。
fullpage(在 v8 中为高级版功能):使用高级版全页 HTML插件(
fullpagehtml)进行完整 HTML 文档编辑。
template(在 v7 中移除):使用高级版 advtemplate 插件或实现自定义模态对话框。
textcolor(在 v6 中集成到核心):文字颜色功能现已内置于 TinyMCE 核心。使用
forecolor和backcolor工具栏按钮,无需额外插件即可使用。
imagetools:(在 v6 中已移除):使用高级 增强图像编辑 或 由 Uploadcare 提供的图像优化器 插件以获得图像编辑功能。
工具栏和菜单名称变更
如果您使用了以下工具栏按钮或菜单选项,它们在 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 的方法:
media_url_resolver现在需要返回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 中的默认变更:
sandbox iframes:现在默认为true(向 iframes 添加 sandbox 属性)convert_unsafe_embeds:现在默认为true(将 object/embed 元素转换为更安全的替代方案)highlight_on_focus:现在默认为true(为编辑器添加焦点轮廓)
TinyMCE 7.0 中的新选项:
license_key:必须设置为gpl或有效的许可证密钥sandbox_iframes_exclusions:要从 iframe 沙箱中排除的 URL 主机列表
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→tableofcontentsTinyMCE 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.insertContenteditor.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插件。
迁移步骤:
从您的插件列表中移除
template向插件列表中添加
templates更新您的配置以使用新的Templates插件API
确保您拥有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);跨域资源加载
迁移步骤:
测试现有内容的净化变更
审查自定义净化配置
更新任何依赖于先前净化行为的内容
跨域资源加载
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 服务现已与编辑器版本解耦,可独立更新。
优势:* 服务可独立更新* 更好的安全性和性能更新* 减少对编辑器版本更新的依赖
迁移步骤:
审查服务集成配置
如有需要,更新服务端点
使用 TinyMCE 8 测试服务功能
WAR 文件向容器迁移
TinyMCE 服务正从 Java WAR 文件过渡到容器化服务。
影响:
部署方法需要更新
服务配置可能会改变
基础设施要求可能有所不同
迁移检查清单:
盘点当前的 WAR 文件部署
审查您环境的容器化需求
规划向容器化服务的过渡时间表
搭建容器基础设施(Docker/Kubernetes)
部署并测试容器化服务
更新服务连接配置
如果仍需使用旧版 WAR 文件,请联系 Tiny 支持
迁移提示
备份与准备:升级前确保进行全面备份。
更新核心初始化:
更新
theme和skin设置以反映新的 oxide 主题和皮肤。在 TinyMCE 5 中,Silver 主题搭配 Oxide 皮肤已是标准配置,但请验证您的配置是否符合 TinyMCE 8 的要求。将
forced_root_block: false选项更新为forced_root_block: "p"。整合工具栏。
审查 v8.0 新增的安全设置默认值。
如果使用自托管,将许可证密钥更新为新格式。
插件迁移:
从配置中移除已弃用的插件。
更新重命名的插件(例如,
spellchecker→tinymcespellchecker)。验证高级插件的兼容性。
如果使用商业许可证,安装许可证密钥管理器插件。
自定义代码更新:
使用
editor.ui.registry.*API 重写自定义插件。替换 v5 的 API 方法,如
editor.addButton、editor.addMenuItem、editor.windowManager.open。更新媒体嵌入处理(
media_url_resolverAPI 变更)。替换已弃用的 API 方法(
editor.insertContent取代editor.selection.setContent,editor.dispatch()取代editor.fire()等)。
CSS 更新:
更新自定义样式以符合新的 Oxide 标准。尽管许多
.mce-*类已被替换为.tox-*类,但仍有部分.mce-*前缀在使用。请审查您的 CSS 以确保兼容性。如果使用了自定义皮肤,请更新 split button CSS(TinyMCE 8 变更)。
测试与部署:
在生产环境部署之前,请彻底测试更新后的配置。
验证 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 行为