CKEditor 4 粘贴不支持文件格式的通知机制:pastefilenotification 手动测试与源码原理解析
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 单元测试)互为补充:自动化测试保证逻辑正确,手动测试保证真实浏览器环境下的用户体验符合预期。
手动测试步骤与验收标准(原文档完整继承)
测试步骤
- 粘贴不支持的文件:向编辑器粘贴编辑器不支持的文件格式,例如 SVG 或 WebP 图片、PDF 文件、Word 文档 等。
- 逐编辑器重复:对文档中配置的每一个编辑器实例重复上述步骤(例如同时创建多个编辑器时逐一验证)。
预期行为
- 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 类型通知明确告知用户,而不是静默无响应**。其实现脉络清晰可循:
paste事件监听器遍历dataTransfer中的文件(clipboard/plugin.js);- 通过
_supportedFileMatchers列表中的匹配器判定支持性——默认图片匹配器只认可 PNG/JPEG/GIF,并受clipboard_handleImages开关影响(clipboard/plugin.js); - 对不支持类型去重、过滤后生成语言包文案并调用
editor.showNotification( ..., 'info', clipboard_notificationDuration )(clipboard/plugin.js); - 从 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 时图片粘贴的行为差异;若浏览器不支持粘贴非图片文件(部分操作系统下),按文档提示退化为仅用图片验证即可。