CKEditor 4 上传文件格式不支持通知机制:从 4.19.0 修复到 addFileMatcher 实战指南
CKEditor 4 上传文件格式不支持通知机制:从 4.19.0 修复到 addFileMatcher 实战指南
导读
本文围绕 CKEditor 4 在 4.19.0 版本中引入的文件格式校验与“不支持格式”通知机制展开,核心是 CKEDITOR.plugins.clipboard.addFileMatcher API 及其在 uploadwidget(上传挂件)插件中的配合使用。通过本文,你将掌握:为什么拖入/粘贴 WebP、SVG 等非默认图片格式时编辑器会弹出“File in the format ... is not supported.”提示、该提示的判定逻辑与触发链路(源码级)、如何自定义受支持的文件类型集合,以及如何在 Bender 手动测试(manual test)中复现与验证这一行为。
一、背景:拖放/粘贴文件时的类型校验缺口(#5095)
在 CKEditor 4.19.0 之前,clipboard(剪贴板)插件对拖入或粘贴文件的处理存在一个已知缺陷(issue #5095):当用户向编辑器拖入或粘贴一个 MIME 类型不在 jpg、gif、png 之列的文件(例如 image/webp、image/svg+xml)时,clipboard 插件会直接弹出“文件格式不支持”的通知,完全不理会 uploadwidget 插件通过 supportedTypes 声明支持的文件类型。
CHANGES.md 中对该问题有明确记录:
Fixed: The clipboard plugin shows notification about unsupported file format when the file type is different than
jpg,gif,png, not respecting supported types by the Upload Widget plugin.
也就是说,即便某个上传挂件(如自定义的 uploadplugin、uploadimage)明确声明了 supportedTypes: /image\/webp/,旧的判定逻辑依然会以 clipboard 内部的硬编码类型列表为准,向用户错误地提示“不支持”,导致文件既无法正常上传,又收到误导性通知。
针对这一问题,4.19.0 在 CHANGES.md 中同步新增了两个能力:
- 新增
CKEDITOR.plugins.clipboard.addFileMatcher方法,允许开发者注册自定义的文件类型匹配器; - 当尝试粘贴/拖放不支持的文件时,clipboard 插件会显示一条“文件无法被拖入或粘贴到编辑器”的通知。
二、修复后的判定链路:从粘贴事件到通知弹出
2.1 clipboard 插件的文件类型判定
在 plugins/clipboard/plugin.js 中,isFileTypeSupported() 会遍历所有已注册的 file matcher,只要其中任何一个匹配器返回 true,该文件类型即被视为支持:
function isFileTypeSupported( file ) {
var clipboardMatchers = editor.plugins.clipboard._supportedFileMatchers;
return CKEDITOR.tools.array.some( clipboardMatchers, function( matcher ) {
return matcher( file );
} );
}
注册匹配器的入口是 CKEDITOR.plugins.clipboard.addFileMatcher( editor, matcher ),它把匹配器函数推入 editor.plugins.clipboard._supportedFileMatchers 数组(plugins/clipboard/plugin.js)。API 文档(同文件 L1749-L1768)给出了典型用法:
CKEDITOR.plugins.clipboard.addFileMatcher( editor, function( file ) {
var supportedImageTypes = [ 'image/png', 'image/jpeg', 'image/gif' ];
return CKEDITOR.tools.indexOf( supportedImageTypes, file.type ) !== -1;
} );
需要注意,该 API 的文档明确说明:
Note: This feature will not cancel the
pasteevent in case of an unsupported file. It is the integrator's responsibility to properly handle incorrect files (e.g. by verifying if the file should be indeed uploaded via upload integrations).
即:匹配器只负责提示,不会拦截粘贴事件本身;是否真正处理该文件,仍由上传集成(uploadwidget 的 paste 监听器)自行决定。
2.2 通知的生成与展示
在 plugins/clipboard/plugin.js 中,通知生成逻辑如下:
displayUnsupportedFileTypesNotification()先对不支持的类型做去重(CKEDITOR.tools.array.unique)、剔除空类型,再调用createNotificationMessage()拼装消息,最终通过editor.showNotification( unsupportedTypeMsg, 'info', editor.config.clipboard_notificationDuration )弹出;createNotificationMessage()使用语言文件中的fileFormatNotSupportedNotification模板,将${formats}占位符替换为<em>包裹的具体 MIME 类型;若文件完全没有可识别格式,则使用fileWithoutFormatNotSupportedNotification模板。
对应英文语言包(plugins/clipboard/lang/en.js)为:
fileFormatNotSupportedNotification: 'The ${formats} file format(s) are not supported.',
fileWithoutFormatNotSupportedNotification: 'The file format is not supported.'
因此,拖入 image/webp 文件时实际显示的通知文本为:
File in the format image/webp is not supported.
(严格对应英文模板渲染为 The image/webp file format(s) are not supported.)
2.3 clipboard 的默认图片匹配器
clipboard 插件在 init 中首先注册一个默认匹配器 testImageBase64Support(plugins/clipboard/plugin.js),其支持列表即 #5095 所指的“硬编码三件套”:
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;
}
从代码可以推断:若 clipboard_handleImages 配置为 false,默认匹配器直接返回 false,此时是否支持完全取决于后续注册的其他匹配器(如 uploadwidget 注册的匹配器)。这也是 4.19.0 修复的核心——上传挂件注册的匹配器与默认匹配器是“或”的关系(some),而非旧逻辑中单一的硬编码判断。
三、uploadwidget 如何接入匹配器
3.1 注册流程
在 plugins/uploadwidget/plugin.js 的 addUploadWidget() 中,每注册一个上传挂件都会同步向 clipboard 注册一个文件匹配器:
function addUploadWidget( editor, name, def ) {
var fileTools = CKEDITOR.fileTools,
uploads = editor.uploadRepository,
// Plugins which support all file type has lower priority than plugins which support specific types.
priority = def.supportedTypes ? 10 : 20;
// Add a callback as a matcher in the clipboard plugin to check if notification should be displayed (#5095).
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 );
} );
...
}
要点:
- 未声明
supportedTypes:匹配器直接返回true,表示“接受任意类型”,此时 clipboard 不会弹出不支持通知; - 声明了
supportedTypes:调用CKEDITOR.fileTools.isTypeSupported( file, def.supportedTypes )判断。该函数在 plugins/filetools/plugin.js 中实现,本质是正则匹配 MIME 类型:
isTypeSupported: function( file, supportedTypes ) {
return !!file.type.match( supportedTypes );
}
priority(def.supportedTypes ? 10 : 20)用于控制paste监听器的优先级:支持特定类型的挂件优先于支持所有类型的挂件处理粘贴事件(plugins/uploadwidget/plugin.js)。
3.2 paste 监听器中的双重校验
除了向 clipboard 注册匹配器,addUploadWidget() 在定义包含 fileToElement 时还会注册自己的 paste 监听器(plugins/uploadwidget/plugin.js)。该监听器内部同样以 supportedTypes 过滤文件:
for ( i = 0; i < filesCount; i++ ) {
file = dataTransfer.getFile( i );
// No def.supportedTypes means all types are supported.
if ( !def.supportedTypes || fileTools.isTypeSupported( file, def.supportedTypes ) ) {
var el = def.fileToElement( file ),
loader = uploads.create( file, undefined, def.loaderType );
...
}
}
结合 isFileTypeSupported() 的“任一匹配器为真即支持”逻辑,可以得出完整的行为矩阵:
| 场景 | clipboard 匹配器判定 | uploadwidget paste 监听器 | 用户看到的结果 |
|---|---|---|---|
文件类型命中任一挂件的 supportedTypes |
支持 | 尝试生成占位元素并上传 | 正常上传流程,无“不支持”通知 |
| 文件类型未被任何挂件声明,且不在默认图片列表 | 不支持 | 跳过 | 弹出“The X file format(s) are not supported.”通知 |
挂件未声明 supportedTypes(接受所有类型) |
支持(返回 true) | 全部尝试处理 | 无“不支持”通知 |
四、手动测试复现:fileformatnotification
4.1 测试元信息
本测试用例(tests/plugins/uploadwidget/manual/fileformatnotification.md)带有以下 Bender 元标签:
@bender-tags: 4.19.0, bug, 5095
@bender-ui: collapsed
@bender-ckeditor-plugins: wysiwygarea, toolbar, uploadwidget, floatingspace, toolbar, sourcearea
4.19.0/bug/5095:标记该手动测试针对 4.19.0 修复的缺陷 #5095;@bender-ui: collapsed:以折叠 UI 运行;- 插件列表包含
uploadwidget,同时sourcearea保证可以切换到源码视图观察插入结果。
4.2 测试页面与测试步骤
对应的页面 tests/plugins/uploadwidget/manual/fileformatnotification.html 定义了一个只支持 WebP 的自定义上传挂件:
<div id="editor"></div>
<script>
// Internet Explorer can't properly recognize newer MIME types.
if ( CKEDITOR.env.ie || bender.tools.env.mobile ) {
bender.ignore();
}
CKEDITOR.plugins.add( 'uploadplugin', {
requires: 'uploadwidget',
init: function( editor ) {
CKEDITOR.fileTools.addUploadWidget( editor, 'uploadplugin', {
supportedTypes: /image\/(webp)/,
} );
}
} );
CKEDITOR.replace( 'editor', {
language: 'en',
extraPlugins: 'uploadplugin',
on: {
instanceReady: function( evt ) {
bender.tools.ignoreUnsupportedEnvironment( 'uploadimage' );
},
}
} );
</script>
由此可以解释测试期望行为的差异——该测试专门验证“通知只针对真正不支持的类型弹出”:
- 拖放 logo.webp 到编辑器:
- 预期(Expected):什么都不发生(不弹通知)。因为
uploadplugin声明了supportedTypes: /image\/(webp)/,clipboard 匹配器返回true,文件被正常接管; - 非预期(Unexpected):弹出 “File in the format image/webp is not supported.”。这正是 #5095 修复前会出现的错误通知。
- 预期(Expected):什么都不发生(不弹通知)。因为
- 对“粘贴”方式重复第 1 步:同样不应弹通知。
- 拖放 logo.svg 到编辑器:
- 预期(Expected):弹出 “File in the format image/svg+xml is not supported.”。因为 SVG 的 MIME 类型
image/svg+xml不匹配/image\/(webp)/,也不在默认图片类型列表内; - 非预期(Unexpected):什么都不发生。
- 预期(Expected):弹出 “File in the format image/svg+xml is not supported.”。因为 SVG 的 MIME 类型
- 对“粘贴”方式重复第 3 步:同样应弹通知。
注意:手动测试中的相对链接
../_assets/logo.webp、../_assets/logo.svg实际指向 tests/plugins/uploadwidget/_assets/ 目录下的同名资源文件。
4.3 测试环境限制
测试页面前置判断 CKEDITOR.env.ie || bender.tools.env.mobile 时执行 bender.ignore() 跳过测试,原因是 IE 与移动端浏览器无法正确识别较新的 MIME 类型(见 HTML 中注释),这与同一目录下 unsupportedfileformat.html 中针对“IE 11 以下版本”的跳过条件(CKEDITOR.env.ie && CKEDITOR.env.version < 11)同理。也就是说,本手动测试的预期行为仅在能正确识别 image/webp、image/svg+xml MIME 类型的现代桌面浏览器中可复现。
五、边界场景与相关手动测试
同一批 4.19.0 手动测试还覆盖了另外两个边界场景,可用于交叉验证匹配器逻辑:
5.1 无扩展名/无格式文件:unsupportedfileformat
tests/plugins/uploadwidget/manual/unsupportedfileformat.md:
- 拖放/粘贴无扩展名文件 logo;
- 预期:弹出 “The file format is not supported.”(对应语言包中的
fileWithoutFormatNotSupportedNotification); - 原因是文件
type为空字符串,createNotificationMessage()中!fileType为真,从而走“无格式”模板(plugins/clipboard/plugin.js)。
5.2 多种不支持格式合并通知:unsupportedfileformatmultiple
tests/plugins/uploadwidget/manual/unsupportedfileformatmultiple.md:
- 同时拖放
logo.webp与logo.svg; - 预期:弹出 “The image/svg+xml, image/webp file format(s) are not supported.”;
- 对应
displayUnsupportedFileTypesNotification()中先去重、再join(', ')拼接多个 MIME 类型的行为(plugins/clipboard/plugin.js),并证明“或”关系判定下两种类型都不被任何匹配器接受。
六、集成者注意事项
- 匹配器只提示、不拦截:
addFileMatcher文档明确说明其不会取消paste事件。若希望彻底阻止不支持的文件进入编辑器,需要在业务层自行校验(例如在paste监听器中调用evt.cancel())。 - 默认匹配器可被配置关闭:设置
config.clipboard_handleImages = false后,clipboard 内置的 PNG/JPEG/GIF 匹配器失效,通知判定完全交由你注册的匹配器决定,可用于定制严格的类型白名单。 - 上传挂件的
supportedTypes是正则:例如/image\/(webp)/、/text\/(plain|html)/,通过file.type.match()进行匹配,注意正则应精确覆盖目标 MIME 类型,避免误放行。 - 多类型通知自动合并去重:多个不支持的类型会合并为一条通知,类型列表以逗号分隔,并剔除空类型。
- 通知时长可配置:通知通过
editor.config.clipboard_notificationDuration控制显示时长(plugins/clipboard/plugin.js)。
七、小结
CKEditor 4.19.0 通过引入 CKEDITOR.plugins.clipboard.addFileMatcher 并让 uploadwidget 在注册时自动注入基于 supportedTypes 的匹配器,将“文件类型是否支持”的判定从 clipboard 插件的硬编码列表扩展为开放、可组合的匹配器集合,从根源上修复了 #5095 所描述的“上传挂件声明支持 WebP,clipboard 却报不支持”的矛盾。结合 fileformatnotification.md 等手动测试,开发者可以清晰复现、验证并定制这一通知行为,为自定义上传集成(如支持 WebP、SVG 或其他 MIME 类型)提供一致的交互反馈。