CKEditor 4 插件冲突检测机制:easyimage 优先于 image 加载与 editor-plugin-conflict 警告详解

原创2026-10-15 10:38:021,444 阅读
文章标签:前端UI组件

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 的工具栏按钮与 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 步):

  1. 打开浏览器控制台(Open console);
  2. 点击工具栏图片图标,观察实际弹出的是 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 the conflicted names is respected where the first conflicted plugin has the highest priority";
  • 检测到冲突时立即返回 true 并只触发一次警告,不再继续遍历;
  • 该方法自 4.10.1 可用(@since 4.10.1)。

各插件在 init() 开头调用它:

plugins/image/plugin.js:

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:

  1. 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 即可静默所有警告输出——排查"为什么测试中看不到冲突警告"时应首先确认该值。

  1. 默认 log 事件监听器格式化输出(core/log.js):监听器以 [CKEDITOR] 为前缀,拼接 Error code: 与错误码;当提供了 additionalData 时,把对象作为 console 的第二个参数输出——这正是手工测试预期中 {plugin: "image", replacedWith: "easyimage"} 这一行对象展示的来源。输出完错误码后,监听器还会追加一行指向错误码文档的提示(指向 CKEditor 4 官方文档站的 dev_errors 页面)。

  2. 可替换的自定义处理器:log 事件注册在优先级 999(最后执行)。若你在自己的代码里监听 CKEDITOR.on( 'log', ... ) 并 evt.cancel(),即可取消默认的 console 输出、接管冲突警告的上报方式(例如转发到自家的错误监控)。

自动化测试对同一行为的印证

手工用例之外,仓库中有多处自动化测试从不同角度固化了这一行为,可与手工测试互相印证:

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 从命令存在性与纯函数两个层面提供了可回归的验证。
登录后查看全文
ckeditor4