CKEditor 5 简单上传适配器Simple Upload Adapter实战指南最小化配置把图片直传自有服务器【免费下载链接】ckeditor5Powerful rich text editor framework with a modular architecture, modern integrations, and features like collaborative editing.项目地址: https://gitcode.com/GitHub_Trending/ck/ckeditor5Simple Upload Adapter 是 CKEditor 5 内置的上传适配器插件它基于浏览器原生XMLHttpRequestAPI以极简的编辑器配置只需一个uploadUrl将用户选择的图片直传到你自己的服务器并自动把服务器返回的图片地址写回编辑内容。读完本文你将掌握该适配器的安装启用、config.simpleUpload全部配置项、文件类型限制方法以及服务端必须遵循的上传协议请求格式、成功响应、错误响应与进度上报并能结合仓库源码理解其底层实现与调用链。功能概述一个uploadUrl打通图片直传在 CKEditor 5 的图片上传体系中官方提供了多种上传方案。Simple Upload Adapter 的定位是最小化配置、直连自有后端你不需要引入任何第三方云服务或复杂的中间件只需在编辑器配置里指定一个接收上传的 URL编辑器便会通过XMLHttpRequest把文件以multipart/form-data形式POST到该地址并解析服务器返回的 JSON 来确定图片在内容中的最终地址。相关配置与协议说明见仓库文档 packages/ckeditor5-upload/docs/features/simple-upload-adapter.md。需要说明的是该功能属于 CKEditor 5 的 premium商业授权功能范畴。从源码看SimpleUploadAdapter 声明了isPremiumPlugin: true、isOfficialPlugin: true以及licenseFeatureCode: SUA因此使用时需要为编辑器配置licenseKey开发评估阶段可填GPL。在编辑器架构中的定位适配器与 FileRepository 的分工要理解 Simple Upload Adapter先要了解 CKEditor 5 的上传架构。FileRepository见 packages/ckeditor5-upload/src/filerepository.ts是文件上传的中央调度器它负责创建FileLoader、维护所有上传任务、汇总进度并通过createUploadAdapter工厂把实际与服务器通信这件事委托给某个上传适配器。SimpleUploadAdapter正是这样一款适配器插件。它声明了依赖requires: [ FileRepository ]在init()阶段从配置读取simpleUpload对象然后把FileRepository.createUploadAdapter工厂指向内部实现的Adapter类。换言之Simple Upload Adapter 与 Base64 Upload Adapter、自定义适配器base64-upload-adapter.md、custom-upload-adapter.md是同一接口的不同实现你随时可以替换。安装与启用在完成编辑器基础安装后把SimpleUploadAdapter加入plugins数组并在simpleUpload配置中至少提供uploadUrlimport { ClassicEditor, SimpleUploadAdapter } from ckeditor5; ClassicEditor .create( { licenseKey: YOUR_LICENSE_KEY, // 或 GPL plugins: [ SimpleUploadAdapter, /* ... */ ], toolbar: [ /* ... */ ], simpleUpload: { // 上传配置见下文 } } ) .then( /* ... */ ) .catch( /* ... */ );源码中的init()逻辑simpleuploadadapter.ts明确了两个静默失败边界值得注意若未配置simpleUpload插件直接return不会注册任何上传工厂若配置了simpleUpload但缺少uploadUrl插件会输出警告simple-upload-adapter-missing-uploadurl并返回上传同样不会生效。对应行为在 tests/adapters/simpleuploadadapter.js 中有测试覆盖缺配置或缺uploadUrl时FileRepository都不会获得createUploadAdapter属性。客户端配置config.simpleUploadSimpleUploadConfig接口定义见 packages/ckeditor5-upload/src/uploadconfig.ts完整示例ClassicEditor .create( { // ...其他配置... simpleUpload: { // 图片上传的目标地址必填 uploadUrl: http://example.com, // 是否开启 XMLHttpRequest 的 withCredentials 属性 withCredentials: true, // 随请求一起发送到上传服务器的 HTTP 头 headers: { X-CSRF-TOKEN: CSRF-Token, Authorization: Bearer JSON Web Token } } } ) .then( /* ... */ ) .catch( /* ... */ );各配置项一览配置项类型默认值必填作用uploadUrlstring—是上传目标 URL一旦指定就启用编辑器内容中插入资源的自动上传headersRecordstring, string或( file: File ) Recordstring, string无否随XMLHttpRequest发送的 HTTP 头常用于认证与 CSRF 防护withCredentialsbooleanfalse否设置请求的withCredentials属性仅影响跨站请求可携带 Cookie 等凭据headers的两种写法headers既可以静态指定也可以按文件动态生成此时回调会收到当前待上传的File对象ClassicEditor .create( { simpleUpload: { uploadUrl: http://example.com, // 写法一静态对象 headers: { X-CSRF-TOKEN: CSRF-Token, Authorization: Bearer JSON Web Token } // 写法二根据文件动态生成二选一 // headers: ( file ) { // return { // X-File-Name: file.name, // X-File-Size: file.size // }; // } } } );这一点在源码的_sendRequest()中有直接体现simpleuploadadapter.ts如果headers是函数会先以文件为参数调用得到最终头集合再逐一setRequestHeader。测试 simpleuploadadapter.js 验证了函数写法确实会按file.name、file.size生成请求头。withCredentials与跨站请求withCredentials: true会让上传请求带上跨站凭据如 Cookie。默认值为false仅在跨站请求场景下有意义开启后服务器还需要配合返回对应的 CORS 响应头如允许携带凭据的Access-Control-Allow-Origin与Access-Control-Allow-Credentials跨站请求才能成功。测试simpleuploadadapter.js分别验证了开启与不开启两种情况下请求的withCredentials取值。配置允许上传的文件类型允许上传的文件类型需要在两处分别配置客户端通过 CKEditor 5 的 UI 与命令限制可选择的图片类型服务端在自己的后端应用中实现真正的过滤校验。客户端配置image.upload.types使用image.upload.types配置项定义允许上传到编辑器的图片 MIME 类型子类型ClassicEditor .create( { image: { upload: { // 只允许 PNG 和 JPEG types: [ png, jpeg ] } } } );类型字符串应与图片 MIME 类型的子类型一致例如image/jpeg对应jpeg。默认情况下编辑器允许上传jpeg、png、gif、bmp、webp、tiff六类图片你可以自定义该列表比如额外放开 SVG 等格式。这一默认值定义在 packages/ckeditor5-image/src/imageupload/imageuploadediting.ts 的editor.config.define( image, { upload: { types: [...] } } )中接口与说明见 packages/ckeditor5-image/src/imageconfig.ts。注意客户端限制只作用于通过编辑器 UI 与命令选择/上传的环节类型识别与过滤的最终防线必须放在服务器上。服务端配置服务器必须自行实现上传类型的过滤机制拒绝任何不允许的图片类型。这属于安全边界不可依赖客户端配置。服务端配置要使用该上传适配器必须提供一个符合以下协议的服务端应用负责接收上传并与编辑器通信。通信协议上传流程启动后适配器会向config.simpleUpload.uploadUrl发送一个POST请求请求方法POST请求体FormData形式multipart/form-data。源码_sendRequest()中data.append( upload, file )表明表单字段名为uploadsimpleuploadadapter.ts响应类型responseType恒为json即服务器必须返回 JSON附加请求头可通过config.simpleUpload.headers发送任意 HTTP 头例如用户认证头并通过config.simpleUpload.withCredentials控制凭据携带跨站要求若使用withCredentials服务器需要相应 CORS 头配合。上传成功响应上传成功后服务器应返回以下两种 JSON 之一。返回单个url——指向服务器上已上传图片的地址{ url: https://example.com/images/foo.jpg }返回urls对象——当服务器支持响应式图片responsive images时使用{ urls: { default: https://example.com/images/foo.jpg, 800: https://example.com/images/foo-800.jpg, 1024: https://example.com/images/foo-1024.jpg, 1920: https://example.com/images/foo-1920.jpg } }其中defaultURL 会写入富文本内容中图片的src属性其余尺寸 URL 会写入srcset属性供浏览器按视口几何尺寸选择最合适的图片。服务器响应中的 URL 有两个去向编辑过程中展示图片用户在编辑器里看到的即时效果写入最终保存到数据库的编辑器内容。从源码看适配器在load事件里做了响应归一化simpleuploadadapter.ts若响应含url会先包装成{ default: url }的urls再把urls与原响应其余属性一起 resolve 给上层因此依赖上传适配器的其他功能如响应式图片、自定义元数据也可以读取到附加字段。测试还验证了服务器返回urls时原样透传以及允许携带自定义附加属性两种场景simpleuploadadapter.js。错误处理如果上传出现问题服务器必须返回包含error属性的对象。这会取消编辑器中的本次上传例如当图片过大或不符合校验规则时允许用户重新选择其他图片{ error: { message: The image upload failed because the image was too big (max 1.5MB). } }若error对象包含message该消息会交给编辑器的通知系统Notification#showWarning展示给用户因此建议提供清晰、具体的错误信息若error对象缺少message编辑器通知系统会显示默认提示Could not upload file:[filename].。源码层面的对应逻辑在_initListeners()中simpleuploadadapter.tserror/abort事件直接 rejectload事件中若响应缺失或含error也会 reject优先使用error.message否则回退到内置的通用文案Couldnt upload file: ${ file.name }.。测试覆盖了网络错误服务器返回带 message 的 error服务器返回空 error三种路径simpleuploadadapter.js。上传进度该适配器开箱即用地向用户展示文件上传进度。底层实现中适配器监听XMLHttpRequest.upload的progress事件lengthComputable时把loaded/total写入FileLoader的uploaded/uploadTotal可观察属性simpleuploadadapter.ts而FileRepository会汇总所有 loader 的进度并通过PendingActions注册一条Upload in progress N%.上传进行中 N%的待处理动作filerepository.ts编辑器据此显示进度提示。对应测试见 simpleuploadadapter.js。适配器完整生命周期源码视角综合源码simpleuploadadapter.ts与测试一次上传的完整调用链如下用户在编辑器中选择/拖入图片ImageUploadEditing插件介入默认类型过滤在此发生见 imageuploadediting.tsFileRepository.createLoader( file )创建FileLoader并调用createUploadAdapter( loader )实例化本适配器的AdapterAdapter.upload()返回 Promise初始化XMLHttpRequestPOSTresponseTypejson→ 挂载事件监听error/abort/load/progress→ 组装FormData并设置headers、withCredentials后发送simpleuploadadapter.ts响应到达后按上文协议 resolve含urls归一化或 reject含错误消息用户在编辑过程中删除图片时FileLoader.abort()会调用Adapter.abort()中止底层 XHR 请求abort()在任何阶段调用都安全测试 simpleuploadadapter.js 有覆盖。下一步想了解 CKEditor 5 中其他图片上传方式Base64 内嵌、CKFinder、自定义适配器等的整体对比可阅读 docs/features/image-upload.md图片在编辑器中的处理、样式与响应式能力参见图片功能相关文档docs/features 目录与 packages/ckeditor5-image 源码本功能的完整实现与测试均可从仓库直接查阅源码 simpleuploadadapter.ts、配置类型 uploadconfig.ts、单元测试 simpleuploadadapter.js。【免费下载链接】ckeditor5Powerful rich text editor framework with a modular architecture, modern integrations, and features like collaborative editing.项目地址: https://gitcode.com/GitHub_Trending/ck/ckeditor5创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
CKEditor 5 简单上传适配器（Simple Upload Adapter）实战指南：最小化配置把图片直传自有服务器
CKEditor 5 简单上传适配器Simple Upload Adapter实战指南最小化配置把图片直传自有服务器【免费下载链接】ckeditor5Powerful rich text editor framework with a modular architecture, modern integrations, and features like collaborative editing.项目地址: https://gitcode.com/GitHub_Trending/ck/ckeditor5Simple Upload Adapter 是 CKEditor 5 内置的上传适配器插件它基于浏览器原生XMLHttpRequestAPI以极简的编辑器配置只需一个uploadUrl将用户选择的图片直传到你自己的服务器并自动把服务器返回的图片地址写回编辑内容。读完本文你将掌握该适配器的安装启用、config.simpleUpload全部配置项、文件类型限制方法以及服务端必须遵循的上传协议请求格式、成功响应、错误响应与进度上报并能结合仓库源码理解其底层实现与调用链。功能概述一个uploadUrl打通图片直传在 CKEditor 5 的图片上传体系中官方提供了多种上传方案。Simple Upload Adapter 的定位是最小化配置、直连自有后端你不需要引入任何第三方云服务或复杂的中间件只需在编辑器配置里指定一个接收上传的 URL编辑器便会通过XMLHttpRequest把文件以multipart/form-data形式POST到该地址并解析服务器返回的 JSON 来确定图片在内容中的最终地址。相关配置与协议说明见仓库文档 packages/ckeditor5-upload/docs/features/simple-upload-adapter.md。需要说明的是该功能属于 CKEditor 5 的 premium商业授权功能范畴。从源码看SimpleUploadAdapter 声明了isPremiumPlugin: true、isOfficialPlugin: true以及licenseFeatureCode: SUA因此使用时需要为编辑器配置licenseKey开发评估阶段可填GPL。在编辑器架构中的定位适配器与 FileRepository 的分工要理解 Simple Upload Adapter先要了解 CKEditor 5 的上传架构。FileRepository见 packages/ckeditor5-upload/src/filerepository.ts是文件上传的中央调度器它负责创建FileLoader、维护所有上传任务、汇总进度并通过createUploadAdapter工厂把实际与服务器通信这件事委托给某个上传适配器。SimpleUploadAdapter正是这样一款适配器插件。它声明了依赖requires: [ FileRepository ]在init()阶段从配置读取simpleUpload对象然后把FileRepository.createUploadAdapter工厂指向内部实现的Adapter类。换言之Simple Upload Adapter 与 Base64 Upload Adapter、自定义适配器base64-upload-adapter.md、custom-upload-adapter.md是同一接口的不同实现你随时可以替换。安装与启用在完成编辑器基础安装后把SimpleUploadAdapter加入plugins数组并在simpleUpload配置中至少提供uploadUrlimport { ClassicEditor, SimpleUploadAdapter } from ckeditor5; ClassicEditor .create( { licenseKey: YOUR_LICENSE_KEY, // 或 GPL plugins: [ SimpleUploadAdapter, /* ... */ ], toolbar: [ /* ... */ ], simpleUpload: { // 上传配置见下文 } } ) .then( /* ... */ ) .catch( /* ... */ );源码中的init()逻辑simpleuploadadapter.ts明确了两个静默失败边界值得注意若未配置simpleUpload插件直接return不会注册任何上传工厂若配置了simpleUpload但缺少uploadUrl插件会输出警告simple-upload-adapter-missing-uploadurl并返回上传同样不会生效。对应行为在 tests/adapters/simpleuploadadapter.js 中有测试覆盖缺配置或缺uploadUrl时FileRepository都不会获得createUploadAdapter属性。客户端配置config.simpleUploadSimpleUploadConfig接口定义见 packages/ckeditor5-upload/src/uploadconfig.ts完整示例ClassicEditor .create( { // ...其他配置... simpleUpload: { // 图片上传的目标地址必填 uploadUrl: http://example.com, // 是否开启 XMLHttpRequest 的 withCredentials 属性 withCredentials: true, // 随请求一起发送到上传服务器的 HTTP 头 headers: { X-CSRF-TOKEN: CSRF-Token, Authorization: Bearer JSON Web Token } } } ) .then( /* ... */ ) .catch( /* ... */ );各配置项一览配置项类型默认值必填作用uploadUrlstring—是上传目标 URL一旦指定就启用编辑器内容中插入资源的自动上传headersRecordstring, string或( file: File ) Recordstring, string无否随XMLHttpRequest发送的 HTTP 头常用于认证与 CSRF 防护withCredentialsbooleanfalse否设置请求的withCredentials属性仅影响跨站请求可携带 Cookie 等凭据headers的两种写法headers既可以静态指定也可以按文件动态生成此时回调会收到当前待上传的File对象ClassicEditor .create( { simpleUpload: { uploadUrl: http://example.com, // 写法一静态对象 headers: { X-CSRF-TOKEN: CSRF-Token, Authorization: Bearer JSON Web Token } // 写法二根据文件动态生成二选一 // headers: ( file ) { // return { // X-File-Name: file.name, // X-File-Size: file.size // }; // } } } );这一点在源码的_sendRequest()中有直接体现simpleuploadadapter.ts如果headers是函数会先以文件为参数调用得到最终头集合再逐一setRequestHeader。测试 simpleuploadadapter.js 验证了函数写法确实会按file.name、file.size生成请求头。withCredentials与跨站请求withCredentials: true会让上传请求带上跨站凭据如 Cookie。默认值为false仅在跨站请求场景下有意义开启后服务器还需要配合返回对应的 CORS 响应头如允许携带凭据的Access-Control-Allow-Origin与Access-Control-Allow-Credentials跨站请求才能成功。测试simpleuploadadapter.js分别验证了开启与不开启两种情况下请求的withCredentials取值。配置允许上传的文件类型允许上传的文件类型需要在两处分别配置客户端通过 CKEditor 5 的 UI 与命令限制可选择的图片类型服务端在自己的后端应用中实现真正的过滤校验。客户端配置image.upload.types使用image.upload.types配置项定义允许上传到编辑器的图片 MIME 类型子类型ClassicEditor .create( { image: { upload: { // 只允许 PNG 和 JPEG types: [ png, jpeg ] } } } );类型字符串应与图片 MIME 类型的子类型一致例如image/jpeg对应jpeg。默认情况下编辑器允许上传jpeg、png、gif、bmp、webp、tiff六类图片你可以自定义该列表比如额外放开 SVG 等格式。这一默认值定义在 packages/ckeditor5-image/src/imageupload/imageuploadediting.ts 的editor.config.define( image, { upload: { types: [...] } } )中接口与说明见 packages/ckeditor5-image/src/imageconfig.ts。注意客户端限制只作用于通过编辑器 UI 与命令选择/上传的环节类型识别与过滤的最终防线必须放在服务器上。服务端配置服务器必须自行实现上传类型的过滤机制拒绝任何不允许的图片类型。这属于安全边界不可依赖客户端配置。服务端配置要使用该上传适配器必须提供一个符合以下协议的服务端应用负责接收上传并与编辑器通信。通信协议上传流程启动后适配器会向config.simpleUpload.uploadUrl发送一个POST请求请求方法POST请求体FormData形式multipart/form-data。源码_sendRequest()中data.append( upload, file )表明表单字段名为uploadsimpleuploadadapter.ts响应类型responseType恒为json即服务器必须返回 JSON附加请求头可通过config.simpleUpload.headers发送任意 HTTP 头例如用户认证头并通过config.simpleUpload.withCredentials控制凭据携带跨站要求若使用withCredentials服务器需要相应 CORS 头配合。上传成功响应上传成功后服务器应返回以下两种 JSON 之一。返回单个url——指向服务器上已上传图片的地址{ url: https://example.com/images/foo.jpg }返回urls对象——当服务器支持响应式图片responsive images时使用{ urls: { default: https://example.com/images/foo.jpg, 800: https://example.com/images/foo-800.jpg, 1024: https://example.com/images/foo-1024.jpg, 1920: https://example.com/images/foo-1920.jpg } }其中defaultURL 会写入富文本内容中图片的src属性其余尺寸 URL 会写入srcset属性供浏览器按视口几何尺寸选择最合适的图片。服务器响应中的 URL 有两个去向编辑过程中展示图片用户在编辑器里看到的即时效果写入最终保存到数据库的编辑器内容。从源码看适配器在load事件里做了响应归一化simpleuploadadapter.ts若响应含url会先包装成{ default: url }的urls再把urls与原响应其余属性一起 resolve 给上层因此依赖上传适配器的其他功能如响应式图片、自定义元数据也可以读取到附加字段。测试还验证了服务器返回urls时原样透传以及允许携带自定义附加属性两种场景simpleuploadadapter.js。错误处理如果上传出现问题服务器必须返回包含error属性的对象。这会取消编辑器中的本次上传例如当图片过大或不符合校验规则时允许用户重新选择其他图片{ error: { message: The image upload failed because the image was too big (max 1.5MB). } }若error对象包含message该消息会交给编辑器的通知系统Notification#showWarning展示给用户因此建议提供清晰、具体的错误信息若error对象缺少message编辑器通知系统会显示默认提示Could not upload file:[filename].。源码层面的对应逻辑在_initListeners()中simpleuploadadapter.tserror/abort事件直接 rejectload事件中若响应缺失或含error也会 reject优先使用error.message否则回退到内置的通用文案Couldnt upload file: ${ file.name }.。测试覆盖了网络错误服务器返回带 message 的 error服务器返回空 error三种路径simpleuploadadapter.js。上传进度该适配器开箱即用地向用户展示文件上传进度。底层实现中适配器监听XMLHttpRequest.upload的progress事件lengthComputable时把loaded/total写入FileLoader的uploaded/uploadTotal可观察属性simpleuploadadapter.ts而FileRepository会汇总所有 loader 的进度并通过PendingActions注册一条Upload in progress N%.上传进行中 N%的待处理动作filerepository.ts编辑器据此显示进度提示。对应测试见 simpleuploadadapter.js。适配器完整生命周期源码视角综合源码simpleuploadadapter.ts与测试一次上传的完整调用链如下用户在编辑器中选择/拖入图片ImageUploadEditing插件介入默认类型过滤在此发生见 imageuploadediting.tsFileRepository.createLoader( file )创建FileLoader并调用createUploadAdapter( loader )实例化本适配器的AdapterAdapter.upload()返回 Promise初始化XMLHttpRequestPOSTresponseTypejson→ 挂载事件监听error/abort/load/progress→ 组装FormData并设置headers、withCredentials后发送simpleuploadadapter.ts响应到达后按上文协议 resolve含urls归一化或 reject含错误消息用户在编辑过程中删除图片时FileLoader.abort()会调用Adapter.abort()中止底层 XHR 请求abort()在任何阶段调用都安全测试 simpleuploadadapter.js 有覆盖。下一步想了解 CKEditor 5 中其他图片上传方式Base64 内嵌、CKFinder、自定义适配器等的整体对比可阅读 docs/features/image-upload.md图片在编辑器中的处理、样式与响应式能力参见图片功能相关文档docs/features 目录与 packages/ckeditor5-image 源码本功能的完整实现与测试均可从仓库直接查阅源码 simpleuploadadapter.ts、配置类型 uploadconfig.ts、单元测试 simpleuploadadapter.js。【免费下载链接】ckeditor5Powerful rich text editor framework with a modular architecture, modern integrations, and features like collaborative editing.项目地址: https://gitcode.com/GitHub_Trending/ck/ckeditor5创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考