@itshixun/qckeditor-vue2 1.0.0 → 1.0.1

package/README.md

@@ -238,6 +238,140 @@ export default {
 | focus | (event, editor) | 获得焦点 |
 | input | (data, event, editor) | 内容变化 |
 
+## 上传适配器
+
+本库提供了三种上传适配器，用于处理编辑器中的文件上传（图片、音视频等）：
+
+### 1. XHR 上传适配器（createXHRUploadAdapter）
+
+基于 XMLHttpRequest 的标准上传方式，适用于大多数后端直传场景：
+
+```js
+import { FileRepository } from 'ckeditor5';
+import { createXHRUploadAdapter } from '@itshixun/qckeditor-vue2';
+
+export default {
+  data() {
+    return {
+      content: '',
+      editorConfig: {
+        // ...其他配置
+        extraPlugins: [
+          function CustomUploadAdapterPlugin(editor) {
+            editor.plugins.get(FileRepository).createUploadAdapter = (loader) => {
+              return createXHRUploadAdapter(loader, {
+                uploadUrl: 'https://api.example.com/upload',
+                headers: { Authorization: 'Bearer token' },
+                withCredentials: true,
+                fieldName: 'file',
+                extraFormData: { category: 'images' },
+              });
+            };
+          },
+        ],
+      },
+    };
+  },
+};
+```
+
+### 2. 自定义异步上传适配器（createAsyncUploadAdapter）
+
+支持自定义异步上传流程，适用于 S3、华为云 OBS 等需要多步上传的场景：
+
+```js
+import { FileRepository } from 'ckeditor5';
+import { createAsyncUploadAdapter } from '@itshixun/qckeditor-vue2';
+
+export default {
+  data() {
+    return {
+      content: '',
+      editorConfig: {
+        extraPlugins: [
+          function CustomUploadAdapterPlugin(editor) {
+            editor.plugins.get(FileRepository).createUploadAdapter = (loader) => {
+              return createAsyncUploadAdapter(loader, async (file, updateProgress) => {
+                // 示例：上传到对象存储（预签名 URL 模式）
+
+                // 第1步：从后端获取预签名上传 URL
+                const presignRes = await fetch('/api/presign-upload', {
+                  method: 'POST',
+                  headers: { 'Content-Type': 'application/json' },
+                  body: JSON.stringify({ filename: file.name, contentType: file.type }),
+                });
+                const { uploadUrl, finalUrl } = await presignRes.json();
+
+                // 第2步：直传到对象存储（使用 XMLHttpRequest 以便监听进度）
+                await new Promise((resolve, reject) => {
+                  const xhr = new XMLHttpRequest();
+                  xhr.open('PUT', uploadUrl, true);
+                  xhr.setRequestHeader('Content-Type', file.type);
+
+                  xhr.upload.addEventListener('progress', (evt) => {
+                    if (evt.lengthComputable && updateProgress) {
+                      updateProgress(Math.round((evt.loaded / evt.total) * 100));
+                    }
+                  });
+                  xhr.addEventListener('load', () => {
+                    xhr.status >= 200 && xhr.status < 300 ? resolve() : reject('上传失败');
+                  });
+                  xhr.addEventListener('error', () => reject('上传出错'));
+                  xhr.send(file);
+                });
+
+                // 第3步：返回最终访问 URL
+                return finalUrl;
+              });
+            };
+          },
+        ],
+      },
+    };
+  },
+};
+```
+
+也可以返回 `UploadResponse` 对象：
+
+```js
+createAsyncUploadAdapter(loader, async (file, updateProgress) => {
+  // ...上传逻辑
+
+  return {
+    default: 'https://cdn.example.com/image.jpg',  // 默认 URL（必须）
+    url: 'https://cdn.example.com/image.jpg',      // 可选
+    // 还可以返回其他字段
+  };
+});
+```
+
+### 3. Mock 上传适配器（createMockUploadAdapter）
+
+用于演示环境，模拟上传过程和进度更新：
+
+```js
+import { FileRepository } from 'ckeditor5';
+import { createMockUploadAdapter } from '@itshixun/qckeditor-vue2';
+
+export default {
+  data() {
+    return {
+      content: '',
+      editorConfig: {
+        extraPlugins: [
+          function CustomUploadAdapterPlugin(editor) {
+            editor.plugins.get(FileRepository).createUploadAdapter = (loader) => {
+              return createMockUploadAdapter(loader);
+            };
+          },
+        ],
+      },
+    };
+  },
+};
+```
+
 ## 与 Vue 3 版本的区别
 
 1. **组件注册**：Vue 2 需要手动在 `components` 选项中注册