CKEditor 4 插件冲突检测机制:easyimage 优先于 image 加载与 editor-plugin-conflict 警告详解
CKEditor 4 插件冲突检测机制:easyimage 优先于 image 加载与 editor-plugin-conflict 警告详解
CKEditor 4 同时提供 image、image2 与 easyimage 三个功能重叠的图片插件,当它们被同时启用时,编辑器如何通过 editor.plugins.detectConflict() 判定加载优先级,并以 editor-plugin-conflict 警告码向控制台报告冲突?本文基于仓库中的手工测试用例 tests/plugins/image/manual/easyimage.md 展开,完整还原该测试的操作步骤、预期结果,并结合 core/editor.js、plugins/image/plugin.js 等源码,讲清冲突检测、插件退让与警告输出这条完整调用链,帮助你在集成 CKEditor 4 时正确理解多图片插件共存的加载行为。
冲突背景:三个功能重叠的图片插件
CKEditor 4 的仓库中并存着三代图片插件:
image:传统的基于对话框(CKEDITOR.dialog)的图片插入/编辑插件,见 plugins/image/plugin.js;image2:基于 Widget 框架重写的图片插件,保留尺寸调整手柄等交互,见 plugins/image2/plugin.js;easyimage:基于 Widget + 气球工具栏(balloon toolbar)+ 云端上传的简化图片方案,见 plugins/easyimage/plugin.js。
三者都注册名为 Image 的工具栏按钮与 image 相关命令,若同时加载会互相踩踏。CKEditor 4.10.1 针对这一问题(内部工单 #1791)引入了 editor.plugins.detectConflict() 机制:功能重叠的插件在自己的 init() 中主动检测"竞争者"是否已登记在编辑器上,若是则放弃注册自己的命令、对话框与按钮,并通过 CKEDITOR.warn() 输出警告。CHANGES.md 中记录了该方法的引入:"Added the editor.plugins.detectConflict() method finding conflicts between provided plugins."。
优先级关系由各自的退让逻辑决定:
| 插件 | 退让对象(检测目标) | 源码位置 |
|---|---|---|
image |
easyimage、image2(按顺序,前者优先) |
plugins/image/plugin.js |
image2 |
easyimage |
plugins/image2/plugin.js |
easyimage |
不退让(自身未调用 detectConflict) | plugins/easyimage/plugin.js |
也就是说,easyimage > image2 > image:只要 easyimage 在编辑器插件集合中,另外两者都会退出。
手工测试用例:tests/plugins/image/manual/easyimage.md
本文章的主题文档 tests/plugins/image/manual/easyimage.md 是一个 bender 框架的手工测试用例(manual test),用于人工验证"image 与 easyimage 同时加载时,easyimage 生效且控制台出现冲突警告"。其原文内容完整如下:
@bender-tags: 4.10.1, bug, 1791
@bender-ui: collapsed
@bender-ckeditor-plugins: wysiwygarea, toolbar, image, easyimage
@bender-include: %BASE_PATH%/plugins/easyimage/_helpers/tools.js
1. Open console.
1. Check loaded image plugin type by clicking image icon.
## Expected
* Easyimage plugin is loaded.
* Console warining:
[CKEDITOR] Error code: editor-plugin-conflict. {plugin: "image", replacedWith: "easyimage"}
## Unexpected
* Image plugin is loaded.
* No or different console warning.
逐项解读该用例的定义:
@bender-tags: 4.10.1, bug, 1791—— 标注该用例验证的功能/缺陷修复自 4.10.1 版本引入,对应工单 #1791;@bender-ui: collapsed—— 在 bender 测试列表中默认折叠显示;@bender-ckeditor-plugins: wysiwygarea, toolbar, image, easyimage—— 声明本测试编辑器只加载这四个插件。这是冲突场景的关键:同时声明image与easyimage,模拟用户误配两者共存的真实情况;@bender-include—— 引入辅助断言工具。该 helper 在仓库中的实际位置是 tests/plugins/easyimage/_helpers/tools.js,提供assertCommandsState、assertMenuItemsState等命令/菜单状态断言函数,以及 easyimage 云服务的测试令牌等常量。
测试页面与操作步骤
与 md 文件同名的 tests/plugins/image/manual/easyimage.html 是对应的测试宿主页面:
<div id="editor"></div>
<script>
if ( bender.tools.env.mobile ) {
bender.ignore();
}
bender.tools.ignoreUnsupportedEnvironment( 'easyimage' );
CKEDITOR.replace( 'editor' );
</script>
页面本身没有显式传 plugins 配置——插件列表由 md 头部的 @bender-ckeditor-plugins 元数据交由 bender 框架注入。两处 bender 调用是环境守卫:移动端直接忽略测试;ignoreUnsupportedEnvironment( 'easyimage' ) 在 easyimage 插件的 isSupportedEnvironment() 判定不支持当前环境时跳过。
人工操作步骤(md 中的 1、2 步):
- 打开浏览器控制台(Open console);
- 点击工具栏图片图标,观察实际弹出的是 easyimage 的上传/气泡工具栏行为,还是传统 image 对话框,以此确认生效的插件类型。
预期与意外结果
- Expected(预期):easyimage 插件生效;控制台出现如下警告:
[CKEDITOR] Error code: editor-plugin-conflict.
{plugin: "image", replacedWith: "easyimage"}
- Unexpected(异常,即测试不通过):image 插件生效(说明退让逻辑失效),或者控制台没有输出、输出了不同内容的警告。
核心机制:detectConflict 的实现
冲突检测的实现在 core/editor.js 中,挂在 CKEDITOR.editor.prototype.plugins 上:
detectConflict: function( plugin, conflicted ) {
for ( var i = 0; i < conflicted.length; i++ ) {
var pluginName = conflicted[ i ];
if ( this[ pluginName ] ) {
CKEDITOR.warn( 'editor-plugin-conflict', {
plugin: plugin,
replacedWith: pluginName
} );
return true;
}
}
return false;
}
要点:
- 第二个参数是竞争插件名数组,按顺序遍历,第一个已存在于
editor.plugins集合中的插件被视为冲突方,其名称进入警告信息的replacedWith字段——源码注释明确说明"The order of theconflictednames is respected where the first conflicted plugin has the highest priority"; - 检测到冲突时立即返回
true并只触发一次警告,不再继续遍历; - 该方法自 4.10.1 可用(
@since 4.10.1)。
各插件在 init() 开头调用它:
init: function( editor ) {
var pluginName = 'image';
// Abort when Easyimage or Image2 are to be loaded since this plugins
// share the same functionality (#1791).
if ( editor.plugins.detectConflict( pluginName, [ 'easyimage', 'image2' ] ) ) {
return;
}
// ...注册对话框、命令、按钮、右键菜单...
}
由于检测放在 init() 的最前面,一旦命中冲突,image 插件的对话框(CKEDITOR.dialog.add)、image 命令(editor.addCommand)、工具栏按钮(editor.ui.addButton( 'Image', ... ))与右键菜单全部不会注册——这正是手工测试中"点击图片图标看到的是 easyimage 行为"的原因,也是自动化测试断言 editor.commands.image 未定义、editor.commands.easyimage 存在的依据。
plugins/image2/plugin.js 同理,检测目标只有 easyimage:
init: function( editor ) {
// Abort when Easyimage is to be loaded since this plugins
// share the same functionality (#1791).
if ( editor.plugins.detectConflict( 'image2', [ 'easyimage' ] ) ) {
return;
}
// ...
}
easyimage 插件自身源码中不存在 detectConflict 调用(从源码结构看),即它不参与退让,是这条优先级链的最终赢家。
警告如何到达控制台:CKEDITOR.warn 与默认日志处理器
detectConflict 触发的 CKEDITOR.warn( 'editor-plugin-conflict', {...} ) 并不同步写 console,而是经由日志事件链,实现在 core/log.js:
CKEDITOR.warn检查级别开关(core/log.js):
CKEDITOR.warn = function( errorCode, additionalData ) {
if ( CKEDITOR.verbosity & CKEDITOR.VERBOSITY_WARN ) {
CKEDITOR.fire( 'log', { type: 'warn', errorCode: errorCode, additionalData: additionalData } );
}
};
日志级别由 CKEDITOR.verbosity 二进制标志控制,定义于 core/log.js:CKEDITOR.VERBOSITY_WARN = 1、CKEDITOR.VERBOSITY_ERROR = 2,默认值为两者按位或(即 warn 与 error 都输出)。将 CKEDITOR.verbosity 置 0 即可静默所有警告输出——排查"为什么测试中看不到冲突警告"时应首先确认该值。
-
默认
log事件监听器格式化输出(core/log.js):监听器以[CKEDITOR]为前缀,拼接Error code:与错误码;当提供了additionalData时,把对象作为 console 的第二个参数输出——这正是手工测试预期中{plugin: "image", replacedWith: "easyimage"}这一行对象展示的来源。输出完错误码后,监听器还会追加一行指向错误码文档的提示(指向 CKEditor 4 官方文档站的 dev_errors 页面)。 -
可替换的自定义处理器:
log事件注册在优先级 999(最后执行)。若你在自己的代码里监听CKEDITOR.on( 'log', ... )并evt.cancel(),即可取消默认的 console 输出、接管冲突警告的上报方式(例如转发到自家的错误监控)。
自动化测试对同一行为的印证
手工用例之外,仓库中有多处自动化测试从不同角度固化了这一行为,可与手工测试互相印证:
- tests/plugins/image/init.js —— 以
plugins: 'image,easyimage'配置创建编辑器,用 sinon spy 钩住CKEDITOR.warn,断言:
assert.isTrue( spy.calledWith( 'editor-plugin-conflict', { plugin: 'image', replacedWith: 'easyimage' } ) );
assert.isUndefined( editor.commands.image, 'Command: Image' );
assert.isNotUndefined( editor.commands.easyimage, 'Command: Easyimage' );
即"警告内容 + image 命令被放弃 + easyimage 命令存在"三点齐备。同文件还覆盖 image,image2 组合下 { plugin: 'image', replacedWith: 'image2' } 的场景(tests/plugins/image/init.js)。
-
tests/plugins/image2/init.js —— 断言
image2场景下警告为{ plugin: 'image2', replacedWith: 'easyimage' }。 -
tests/core/plugins/plugins.js —— 针对
detectConflict本身的两个单元用例:构造仅含plugin1/plugin2的假editor.plugins,验证"有冲突"时返回true且以列表首个匹配插件(plugin1)作为replacedWith;"无冲突"时返回false且不调用CKEDITOR.warn。
同目录下还有 tests/plugins/image/manual/easyimageimage2.md 这一扩展手工用例:同时加载 image, image2, easyimage,预期两条警告(分别 {plugin: "image", ...} 与 {plugin: "image2", ...});以及 tests/plugins/image2/manual/easyimage.md 覆盖 image2 与 easyimage 的两两组合。它们共同构成 #1791 的完整验收矩阵。
实战:复现与规避该冲突
复现
在任意 CKEditor 4.10.1+ 页面中,只要让两个冲突插件同时出现在最终插件集合,即可看到警告。最简复现:
CKEDITOR.replace( 'editor', {
plugins: 'wysiwygarea,toolbar,image,easyimage'
} );
初始化后打开控制台,即可看到:
[CKEDITOR] Error code: editor-plugin-conflict.
{plugin: "image", replacedWith: "easyimage"}
注意两点:警告只在 CKEDITOR.verbosity 含 VERBOSITY_WARN 位时输出;若通过 extraPlugins 或插件间 requires 关系间接引入 easyimage(例如某自定义插件 requires: 'easyimage'),冲突同样会被触发——detectConflict 检查的是编辑器最终登记的插件集合,而非配置字面量。
规避
- 若产品上使用 easyimage,就不要在
config.plugins/extraPlugins中保留image或image2,或显式removePlugins: 'image'; - 反之若使用传统
image对话框,就不要引入 easyimage/image2。
easyimage 启用后的常用配置
既然 easyimage 是冲突中的最终赢家,以下配置项(定义于 plugins/easyimage/plugin.js)决定它接管图片功能后的具体形态:
| 配置项 | 默认值 | 作用 |
|---|---|---|
easyimage_toolbar |
<a href="https://link.gitcode.com/i/e858b29fee627d06b7cfce374560dfa7" target="_blank">'EasyImageFull', 'EasyImageSide', 'EasyImageAlt'] |
图片气泡工具栏/右键菜单按钮列表,支持字符串或数组,见 [plugins/easyimage/plugin.js |
easyimage_class |
'easyimage' |
升级(upcast)到 widget 的 <figure> 所需 class,设为 null 则不要求 class,见 plugins/easyimage/plugin.js |
easyimage_sideClass |
(widget allowedContent 引用) |
side 图片样式在 <figure> 上允许的 class,见 plugins/easyimage/plugin.js |
easyimage_styles |
full/side/alignLeft/alignCenter/alignRight 五组内置样式 |
与默认样式对象合并自定义图片样式,见 plugins/easyimage/plugin.js |
内置默认样式会生成 easyimage-full、easyimage-side、easyimage-align-* 等 class(配套样式在 plugins/easyimage/styles 中),easyimage_styles 通过 CKEDITOR.tools.object.merge 与之合并,可实现增删样式按钮。
小结
- CKEditor 4 用
editor.plugins.detectConflict( plugin, conflicted )(core/editor.js)解决图片类插件并存问题:竞争列表按优先级排序,首个命中即告警并退让; - 退让发生在插件
init()入口——image与image2命中冲突时直接return,不注册命令、对话框与按钮,easyimage 因此成为事实上的唯一生效插件; - 警告经
CKEDITOR.warn→log事件 → 默认监听器到达控制台,输出格式为[CKEDITOR] Error code: editor-plugin-conflict.+ 附加数据对象,受CKEDITOR.verbosity级别控制,且可通过自定义log监听器接管; - 手工用例 tests/plugins/image/manual/easyimage.md 验证的正是这条链路的端到端行为:同时加载
image,easyimage时,easyimage 生效、控制台出现{plugin: "image", replacedWith: "easyimage"}警告,任何一项不满足即判定失败;自动化测试 tests/plugins/image/init.js 与 tests/core/plugins/plugins.js 从命令存在性与纯函数两个层面提供了可回归的验证。