CKEditor 4 粘贴不支持文件格式的通知机制:pastefilenotification 手动测试与源码原理解析

原创2026-10-14 22:36:201,898 阅读
文章标签:前端UI组件

CKEditor 4 粘贴不支持文件格式的通知机制:pastefilenotification 手动测试与源码原理解析

粘贴或拖放图片、PDF、Word 文档等文件到 CKEditor 4 编辑器时,编辑器会如何处理不支持的文件格式?本文围绕仓库中的手动测试用例 pastefilenotification.md,完整还原该功能的验收步骤与预期行为,并结合 clipboard、uploadwidget 等插件源码与自动化测试,深入剖析"不支持文件格式通知"(对应 GitHub issue #4750、自 4.17.0 起引入)的底层实现、相关配置项与可扩展 API,帮助开发者理解、验证并在集成中复现这一行为。

功能背景与测试文档定位

该测试文档位于 tests/plugins/clipboard/manual/ 目录,是 CKEditor 4 的 Bender 手动测试套件成员。文档头部以 @bender-tags 声明其归属与来源:

  • @bender-tags: 4.17.0, feature, 4750 —— 该功能于 4.17.0 版本引入,属于 feature 类型,对应 issue 编号 #4750;
  • @bender-ui: collapsed —— 测试在折叠的 UI 模式下运行,便于聚焦编辑器内容区域;
  • @bender-ckeditor-plugins: wysiwygarea, clipboard, undo, image, floatingspace —— 测试环境需要加载的核心插件集合,其中 clipboard 是承载本功能的插件,image 用于验证图片类文件的内联粘贴,floatingspace 提供浮动工具栏 UI。

手动测试用例的作用是以人机交互方式验证功能是否符合预期,通常与自动化测试(Bender 单元测试)互为补充:自动化测试保证逻辑正确,手动测试保证真实浏览器环境下的用户体验符合预期。

手动测试步骤与验收标准(原文档完整继承)

测试步骤

  1. 粘贴不支持的文件:向编辑器粘贴编辑器不支持的文件格式,例如 SVG 或 WebP 图片、PDF 文件、Word 文档 等。
  2. 逐编辑器重复:对文档中配置的每一个编辑器实例重复上述步骤(例如同时创建多个编辑器时逐一验证)。

预期行为

  • Expected(符合预期):编辑器显示一条通知,消息为 "This file format is not supported."(此文件格式不受支持)。
  • Unexpected(不符合预期):粘贴后什么都不发生,用户没有任何反馈。

测试注意事项(原文档特别提醒)

  • 浏览器能力差异:取决于操作系统,部分浏览器可能不支持粘贴除图片以外的文件。在这种情况下,测试时应只使用图片进行验证。
  • “复制文件”与“复制文件内容”是两种不同的操作:通过右键菜单等途径“复制文件”(复制的是文件本身,携带 MIME 类型信息)与复制文件的“内容”(复制的是文本或 HTML 数据)截然不同。这两种操作只有在图片场景下才是相同的——因为图片既可以作为文件被复制,也可以作为二进制内容被读取。这一提醒直接关系到测试的有效性:若要验证本功能,必须确保粘贴的是“文件”而非“内容”。

该功能有一个孪生测试用例 draganddropfilenotification.md,验收逻辑一致,仅操作方式改为“拖放”(Drag and Drop)而非“粘贴”,其插件列表额外包含 sourcearea。两者共同覆盖了文件进入编辑器的两条主要通路。

底层实现原理:从 paste 事件到通知展示

手动测试描述的“显示通知”行为,在 plugins/clipboard/plugin.js 中由 clipboard 插件在 paste 事件阶段实现。核心逻辑分为三个层次。

1. 文件粘贴能力探测

在插件初始化时(plugin.js),先探测当前浏览器是否支持文件粘贴:

var isFilePasteSupported = CKEDITOR.plugins.clipboard.isCustomDataTypesSupported || CKEDITOR.plugins.clipboard.isFileApiSupported,
	latestId;

这两个能力标志定义在插件单例对象上:

  • isCustomDataTypesSupported: !CKEDITOR.env.ie || CKEDITOR.env.version >= 16(plugin.js):IE 16 以下不支持自定义 MIME 类型;
  • isFileApiSupported: !CKEDITOR.env.ie || CKEDITOR.env.version > 9(plugin.js):IE 9 及以下不支持 File API。

只要浏览器支持其中之一,文件粘贴处理便会启用;在 IE 10 以下等老环境,该功能整体跳过(对应原文档中“部分浏览器不支持粘贴非图片文件”的提示)。

2. 收集不支持的文件类型

在 paste 事件监听器中(plugin.js),代码遍历 dataTransfer 中的全部文件,逐一调用 isFileTypeSupported 判断:

var unsupportedFileTypes = [];
for ( var i = 0; i < dataTransfer.getFilesCount(); i++ ) {
	var file = dataTransfer.getFile( i );

	if ( !isFileTypeSupported( file ) ) {
		unsupportedFileTypes.push( file.type );
	}
}

displayUnsupportedFileTypesNotification( unsupportedFileTypes );

其中 isFileTypeSupported(plugin.js)遍历插件注册的“文件匹配器”(file matcher)列表,只要任一匹配器判定该文件受支持即视为支持:

function isFileTypeSupported( file ) {
	var clipboardMatchers = editor.plugins.clipboard._supportedFileMatchers;
	return CKEDITOR.tools.array.some( clipboardMatchers, function( matcher ) {
		return matcher( file );
	} );
}

需要强调:通知展示不会取消 paste 事件,也不阻止后续流程,其角色纯粹是“告知用户”,这是官方文档对 addFileMatcher 的明确说明(见下文扩展 API 部分)。

3. 生成并展示通知

displayUnsupportedFileTypesNotification(plugin.js)先对文件类型做去重、过滤未知/空白类型,再通过 createNotificationMessage 构造文案并调用 editor.showNotification:

var unsupportedTypeMsg = createNotificationMessage( fileTypes.join( ', ' ) );
editor.showNotification( unsupportedTypeMsg, 'info', editor.config.clipboard_notificationDuration );

通知的展示参数为:

参数 值 说明
消息内容 语言包生成的文案 见下方语言包
类型 'info' 信息型通知
持续时间 editor.config.clipboard_notificationDuration 默认 10000 毫秒

createNotificationMessage(plugin.js)根据是否有明确的文件类型选择不同文案:

function createNotificationMessage( fileType ) {
	if ( !fileType ) {
		return editor.lang.clipboard.fileWithoutFormatNotSupportedNotification;
	}

	return editor.lang.clipboard.fileFormatNotSupportedNotification.
		replace( /\${formats\}/g, '<em>' + fileType + '</em>' );
}

也就是说,粘贴 application/pdf 时会显示 “The application/pdf file format(s) are not supported.”(文件类型以斜体 <em> 强调);若文件本身没有可识别的 MIME 类型,则退化为通用文案 “The file format is not supported.”——这正是手动测试文档中标注的预期消息。

语言包中的文案定义

两条消息定义在 plugins/clipboard/lang/en.js:

fileFormatNotSupportedNotification: 'The ${formats} file format(s) are not supported.',
fileWithoutFormatNotSupportedNotification: 'The file format is not supported.'

注意 plugins/clipboard/lang/zh-cn.js 中这两条目前仍以英文原文占位并标记为 // MISSING,即简体中文语言包尚未完成该文案的本地化翻译。若你的站点面向中文用户且需要本地化通知文案,这是可关注的语言包缺口。

图片粘贴与 clipboard_handleImages 配置

同一文件中还定义了图片文件的内联粘贴逻辑,它与“不支持格式通知”紧密耦合。testImageBase64Support(plugin.js)同时充当默认文件匹配器与图片处理开关:

function testImageBase64Support( file ) {
	// Check if turning images into base64 is disabled (#5431).
	if ( !editor.config.clipboard_handleImages ) {
		return false;
	}

	var supportedImageTypes = [ 'image/png', 'image/jpeg', 'image/gif' ];
	return CKEDITOR.tools.indexOf( supportedImageTypes, file.type ) !== -1;
}

其含义为:

  • 默认受支持的图片类型仅有 image/png、image/jpeg、image/gif 三种;
  • 因而 SVG、WebP 等图片格式会被判定为“不支持”,触发通知 —— 这正是测试文档中建议使用 SVG/WebP 图片验证的原因;
  • 配置项 clipboard_handleImages(默认 true,自 4.17.0 起,定义于 plugin.js)控制是否将图片转为 base64 内联处理。若将其设为 false,则所有图片都不再被匹配器认可,粘贴图片同样会触发“不支持格式”通知——自动化测试 pasteimage.js 与 dropimage.js 均对此场景做了断言。

图片的实际内联粘贴流程(plugin.js)通过 FileReader 将图片文件异步读取为 data:image/...;base64,... 数据 URL 并写入 evt.data.dataValue 后重新触发 paste;读取失败或中止时则恢复原流程(对应 IE 的 fileTransferCancel 兜底逻辑,见 setCustomIEEventAttribute,plugin.js)。

通知时长配置:clipboard_notificationDuration

通知展示时长由配置项 clipboard_notificationDuration 控制,定义于 plugin.js:

CKEDITOR.config.clipboard_notificationDuration = 10000;
  • 类型:Number;
  • 默认值:10000(毫秒,即 10 秒);
  • 作用范围:不仅作用于本功能,也作用于粘贴被浏览器拦截等其他 clipboard 通知(见 plugin.js)。

集成方可在 config.js 或创建编辑器时自定义,例如:

CKEDITOR.replace( 'editor1', {
	clipboard_notificationDuration: 5000, // 通知显示 5 秒后自动消失
	clipboard_handleImages: true
} );

扩展 API:CKEDITOR.plugins.clipboard.addFileMatcher

从 4.19.0 起,clipboard 插件提供了官方扩展点 CKEDITOR.plugins.clipboard.addFileMatcher( editor, matcher )(plugin.js),允许集成方自定义哪些文件类型算作“受支持”,从而精确控制通知的触发范围。官方文档给出如下示例:

CKEDITOR.plugins.clipboard.addFileMatcher( editor, function( file ) {
	var supportedImageTypes = [ 'image/png', 'image/jpeg', 'image/gif' ];
	return CKEDITOR.tools.indexOf( supportedImageTypes, file.type ) !== -1;
} );

使用须知(来自官方 API 注释):

  • 该特性在文件不受支持时不会取消 paste 事件;
  • 对于不受支持的文件如何处理(例如是否仍应上传),是集成方的责任,需自行校验。

uploadwidget 插件的实际应用

仓库内部的一个典型调用者是上传组件插件 plugins/uploadwidget/plugin.js。其 addUploadWidget 内部注册了一个文件匹配器:

CKEDITOR.plugins.clipboard.addFileMatcher( editor, function( file ) {
	// Allow any file type in case no type is defined.
	if ( !def.supportedTypes ) {
		return true;
	}

	return fileTools.isTypeSupported( file, def.supportedTypes );
} );

其中 def.supportedTypes 是上传组件的支持类型正则(如 /text\/(plain|html)/、/text\/pdf/),且未声明 supportedTypes 的组件会匹配所有文件类型。插件还通过优先级设计保证行为正确:priority = def.supportedTypes ? 10 : 20(plugin.js),即“支持特定类型”的组件比“支持所有类型”的组件拥有更高优先级。这意味着:当你启用了支持 PDF 上传的组件后,粘贴 PDF 将不再弹出“不支持格式”通知,而会走上传流程——手动测试文档中“Word 文档等不受支持格式”的判定结果,会随集成组件不同而动态变化。

自动化测试对行为的验证

除手动测试外,仓库中的 Bender 自动化测试对本功能做了系统断言,可作为理解行为边界的权威参考:

测试文件 覆盖场景
pasteimage.js test pasting unsupported file type shows notification:粘贴 application/pdf 时断言 showNotification 恰好被调用一次、消息匹配语言包模板、类型为 'info'、时长为 clipboard_notificationDuration(L78-L103);test unsupported file type 断言 PDF 不会进入编辑内容(L66-L75)
dropimage.js 拖放不受支持图片类型时展示通知的对应断言(L118-L122)
notifications.js 消息中强调文件类型、去重、只包含不支持类型信息、clipboard_handleImages 关闭时仍展示通知等边界(L33、L125、L172)
clipboard.js 通过 addFileMatcher 注册自定义匹配器后文件类型判定逻辑

这些测试共同证实:通知的触发条件、文案模板、展示类型与时长的每一个细节,都与手动测试文档中的“Expected”行为一一对应。

小结与验证建议

pastefilenotification.md 手动测试验证的是 CKEditor 4.17.0 引入的一项用户反馈机制:**当用户向编辑器粘贴(或拖放)不受支持的

文件格式时,编辑器通过 info 类型通知明确告知用户,而不是静默无响应**。其实现脉络清晰可循:

  1. paste 事件监听器遍历 dataTransfer 中的文件(clipboard/plugin.js);
  2. 通过 _supportedFileMatchers 列表中的匹配器判定支持性——默认图片匹配器只认可 PNG/JPEG/GIF,并受 clipboard_handleImages 开关影响(clipboard/plugin.js);
  3. 对不支持类型去重、过滤后生成语言包文案并调用 editor.showNotification( ..., 'info', clipboard_notificationDuration )(clipboard/plugin.js);
  4. 从 4.19.0 起,集成方可借 CKEDITOR.plugins.clipboard.addFileMatcher 扩展“受支持类型”集合,uploadwidget 组件即依赖该 API 声明自己可处理的上传类型。

实操验证建议:加载 wysiwygarea, clipboard, undo, image, floatingspace 插件后,分别粘贴 PNG(预期:图片以 base64 内联插入)、SVG/WebP/PDF(预期:弹出 “This file format is not supported.” 通知,编辑内容不变),再对比开启与关闭 clipboard_handleImages 时图片粘贴的行为差异;若浏览器不支持粘贴非图片文件(部分操作系统下),按文档提示退化为仅用图片验证即可。

登录后查看全文
ckeditor4