king-design-analyzer 2.1.7 → 2.2.0

package/components/upload.json

@@ -1,499 +1,500 @@
 {
-  "id": "upload",
-  "name": "Upload",
-  "displayName": "上传",
-  "category": "form",
-  "description": "文件上传组件，支持点击、拖拽、照片墙等多种风格。支持文件大小/数量限制、上传前验证、自定义请求头和数据等功能。",
-  "importStatement": "import { Upload } from '@king-design/vue';",
-  "props": [
-    {
-      "name": "action",
-      "description": "上传地址",
-      "type": {
-        "raw": "string",
-        "kind": "string"
-      },
-      "required": true,
-      "usageExample": "<Upload action=\"/api/upload\" />"
-    },
-    {
-      "name": "files",
-      "description": "已上传和待上传的文件列表，可用 v-model:files 双向绑定",
-      "type": {
-        "raw": "UploadFile[]",
-        "kind": "array"
-      },
-      "required": false,
-      "default": "[]",
-      "usageExample": "<Upload v-model:files=\"fileList\" />"
-    },
-    {
-      "name": "type",
-      "description": "组件风格",
-      "type": {
-        "raw": "\"select\" | \"drag\" | \"gallery\"",
-        "kind": "union",
-        "unionTypes": [
-          "select",
-          "drag",
-          "gallery"
-        ]
-      },
-      "required": false,
-      "default": "\"select\"",
-      "allowedValues": [
-        {
-          "value": "select",
-          "label": "点击选择",
-          "isDefault": true
+    "id": "upload",
+    "name": "Upload",
+    "displayName": "上传",
+    "category": "form",
+    "description": "文件上传组件，支持点击、拖拽、照片墙等多种风格。支持文件大小/数量限制、上传前验证、自定义请求头和数据等功能。",
+    "importStatement": "import { Upload } from '@king-design/vue';",
+    "props": [
+        {
+            "name": "action",
+            "description": "上传地址",
+            "type": {
+                "raw": "string",
+                "kind": "string"
+            },
+            "required": true,
+            "usageExample": "<Upload action=\"/api/upload\" />"
+        },
+        {
+            "name": "files",
+            "description": "已上传和待上传的文件列表，可用 v-model:files 双向绑定",
+            "type": {
+                "raw": "UploadFile[]",
+                "kind": "array"
+            },
+            "required": false,
+            "default": "[]",
+            "usageExample": "<Upload v-model:files=\"fileList\" />"
+        },
+        {
+            "name": "defaultFiles",
+            "description": "默认文件列表，用于初始化已上传文件，不与 files 双向绑定",
+            "type": {
+                "raw": "(Partial<UploadFile> & Pick<UploadFile, 'name' | 'url'>)[]",
+                "kind": "array"
+            },
+            "required": false,
+            "default": "[]",
+            "usageExample": "<Upload :defaultFiles=\"[{ name: 'demo.png', url: 'https://example.com/demo.png' }]\" />"
+        },
+        {
+            "name": "type",
+            "description": "组件风格",
+            "type": {
+                "raw": "\"select\" | \"drag\" | \"gallery\"",
+                "kind": "union",
+                "unionTypes": [
+                    "select",
+                    "drag",
+                    "gallery"
+                ]
+            },
+            "required": false,
+            "default": "\"select\"",
+            "allowedValues": [
+                {
+                    "value": "select",
+                    "label": "点击选择",
+                    "isDefault": true
+                },
+                {
+                    "value": "drag",
+                    "label": "拖拽上传"
+                },
+                {
+                    "value": "gallery",
+                    "label": "照片墙风格"
+                }
+            ],
+            "usageExample": "<Upload type=\"drag\" />"
+        },
+        {
+            "name": "accept",
+            "description": "支持上传的文件类型",
+            "type": {
+                "raw": "string",
+                "kind": "string"
+            },
+            "required": false,
+            "default": "undefined",
+            "usageExample": "<Upload accept=\".jpg, .png, .gif\" />"
+        },
+        {
+            "name": "multiple",
+            "description": "是否支持多选文件",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Upload multiple />"
+        },
+        {
+            "name": "maxSize",
+            "description": "最大上传文件大小限制(kb)",
+            "type": {
+                "raw": "number",
+                "kind": "number"
+            },
+            "required": false,
+            "default": "undefined",
+            "usageExample": "<Upload :maxSize=\"500\" />"
+        },
+        {
+            "name": "limit",
+            "description": "最大上传文件数量限制",
+            "type": {
+                "raw": "number",
+                "kind": "number"
+            },
+            "required": false,
+            "default": "undefined",
+            "usageExample": "<Upload :limit=\"5\" />"
+        },
+        {
+            "name": "autoUpload",
+            "description": "是否选择文件后自动上传",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "true",
+            "usageExample": "<Upload :autoUpload=\"false\" />"
+        },
+        {
+            "name": "beforeUpload",
+            "description": "上传前的回调函数，返回 false 取消上传，支持异步",
+            "type": {
+                "raw": "(file: UploadFile, files: UploadFile[]) => boolean | Promise<boolean>",
+                "kind": "function",
+                "functionSignature": "(file: UploadFile, files: UploadFile[]) => boolean | Promise<boolean>"
+            },
+            "required": false,
+            "default": "undefined",
+            "usageExample": "<Upload :beforeUpload=\"handleBeforeUpload\" />"
+        },
+        {
+            "name": "beforeRemove",
+            "description": "删除前的回调函数，返回 false 取消删除，支持异步",
+            "type": {
+                "raw": "(file: UploadFile, files: UploadFile[]) => boolean | Promise<boolean>",
+                "kind": "function",
+                "functionSignature": "(file: UploadFile, files: UploadFile[]) => boolean | Promise<boolean>"
+            },
+            "required": false,
+            "default": "undefined",
+            "usageExample": "<Upload :beforeRemove=\"handleBeforeRemove\" />"
+        },
+        {
+            "name": "data",
+            "description": "上传附加的请求数据，可以是对象或函数",
+            "type": {
+                "raw": "object | ((file: UploadFile) => object)",
+                "kind": "union"
+            },
+            "required": false,
+            "default": "undefined",
+            "usageExample": "<Upload :data=\"{userId: '123'}\" />"
+        },
+        {
+            "name": "headers",
+            "description": "上传的请求头",
+            "type": {
+                "raw": "Record<string, string>",
+                "kind": "object"
+            },
+            "required": false,
+            "default": "undefined",
+            "usageExample": "<Upload :headers=\"{Authorization: 'Bearer token'}\" />"
         },
         {
-          "value": "drag",
-          "label": "拖拽上传"
+            "name": "name",
+            "description": "上传文件字段名",
+            "type": {
+                "raw": "string",
+                "kind": "string"
+            },
+            "required": false,
+            "default": "undefined",
+            "usageExample": "<Upload name=\"file\" />"
         },
         {
-          "value": "gallery",
-          "label": "照片墙风格"
+            "name": "withCredentials",
+            "description": "跨域请求是否允许传送 cookie",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Upload withCredentials />"
+        },
+        {
+            "name": "directory",
+            "description": "是否支持上传文件夹",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Upload directory />"
+        },
+        {
+            "name": "disabled",
+            "description": "是否禁用上传",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Upload disabled />"
         }
-      ],
-      "usageExample": "<Upload type=\"drag\" />"
-    },
-    {
-      "name": "accept",
-      "description": "支持上传的文件类型",
-      "type": {
-        "raw": "string",
-        "kind": "string"
-      },
-      "required": false,
-      "default": "undefined",
-      "usageExample": "<Upload accept=\".jpg, .png, .gif\" />"
-    },
-    {
-      "name": "multiple",
-      "description": "是否支持多选文件",
-      "type": {
-        "raw": "boolean",
-        "kind": "boolean"
-      },
-      "required": false,
-      "default": "false",
-      "usageExample": "<Upload multiple />"
-    },
-    {
-      "name": "maxSize",
-      "description": "最大上传文件大小限制(kb)",
-      "type": {
-        "raw": "number",
-        "kind": "number"
-      },
-      "required": false,
-      "default": "undefined",
-      "usageExample": "<Upload :maxSize=\"500\" />"
-    },
-    {
-      "name": "limit",
-      "description": "最大上传文件数量限制",
-      "type": {
-        "raw": "number",
-        "kind": "number"
-      },
-      "required": false,
-      "default": "undefined",
-      "usageExample": "<Upload :limit=\"5\" />"
-    },
-    {
-      "name": "autoUpload",
-      "description": "是否选择文件后自动上传",
-      "type": {
-        "raw": "boolean",
-        "kind": "boolean"
-      },
-      "required": false,
-      "default": "true",
-      "usageExample": "<Upload :autoUpload=\"false\" />"
-    },
-    {
-      "name": "beforeUpload",
-      "description": "上传前的回调函数，返回 false 取消上传，支持异步",
-      "type": {
-        "raw": "(file: UploadFile, files: UploadFile[]) => boolean | Promise<boolean>",
-        "kind": "function",
-        "functionSignature": "(file: UploadFile, files: UploadFile[]) => boolean | Promise<boolean>"
-      },
-      "required": false,
-      "default": "undefined",
-      "usageExample": "<Upload :beforeUpload=\"handleBeforeUpload\" />"
-    },
-    {
-      "name": "beforeRemove",
-      "description": "删除前的回调函数，返回 false 取消删除，支持异步",
-      "type": {
-        "raw": "(file: UploadFile, files: UploadFile[]) => boolean | Promise<boolean>",
-        "kind": "function",
-        "functionSignature": "(file: UploadFile, files: UploadFile[]) => boolean | Promise<boolean>"
-      },
-      "required": false,
-      "default": "undefined",
-      "usageExample": "<Upload :beforeRemove=\"handleBeforeRemove\" />"
-    },
-    {
-      "name": "data",
-      "description": "上传附加的请求数据，可以是对象或函数",
-      "type": {
-        "raw": "object | ((file: UploadFile) => object)",
-        "kind": "union"
-      },
-      "required": false,
-      "default": "undefined",
-      "usageExample": "<Upload :data=\"{userId: '123'}\" />"
-    },
-    {
-      "name": "headers",
-      "description": "上传的请求头",
-      "type": {
-        "raw": "Record<string, string>",
-        "kind": "object"
-      },
-      "required": false,
-      "default": "undefined",
-      "usageExample": "<Upload :headers=\"{Authorization: 'Bearer token'}\" />"
-    },
-    {
-      "name": "name",
-      "description": "上传文件字段名",
-      "type": {
-        "raw": "string",
-        "kind": "string"
-      },
-      "required": false,
-      "default": "undefined",
-      "usageExample": "<Upload name=\"file\" />"
-    },
-    {
-      "name": "withCredentials",
-      "description": "跨域请求是否允许传送 cookie",
-      "type": {
-        "raw": "boolean",
-        "kind": "boolean"
-      },
-      "required": false,
-      "default": "false",
-      "usageExample": "<Upload withCredentials />"
-    },
-    {
-      "name": "directory",
-      "description": "是否支持上传文件夹",
-      "type": {
-        "raw": "boolean",
-        "kind": "boolean"
-      },
-      "required": false,
-      "default": "false",
-      "usageExample": "<Upload directory />"
-    },
-    {
-      "name": "disabled",
-      "description": "是否禁用上传",
-      "type": {
-        "raw": "boolean",
-        "kind": "boolean"
-      },
-      "required": false,
-      "default": "false",
-      "usageExample": "<Upload disabled />"
-    }
-  ],
-  "events": [
-    {
-      "name": "progress",
-      "vueEventName": "@progress",
-      "description": "文件上传过程中触发",
-      "payload": [
-        {
-          "name": "event",
-          "type": "ProgressEvent",
-          "description": "进度事件"
+    ],
+    "events": [
+        {
+            "name": "progress",
+            "vueEventName": "@progress",
+            "description": "文件上传过程中触发",
+            "payload": [
+                {
+                    "name": "event",
+                    "type": "ProgressEvent",
+                    "description": "进度事件"
+                },
+                {
+                    "name": "xhr",
+                    "type": "XMLHttpRequest",
+                    "description": "请求对象"
+                },
+                {
+                    "name": "file",
+                    "type": "UploadFile",
+                    "description": "当前文件"
+                },
+                {
+                    "name": "files",
+                    "type": "UploadFile[]",
+                    "description": "所有文件列表"
+                }
+            ],
+            "usageExample": "<Upload @progress=\"handleProgress\">",
+            "handlerExample": "const handleProgress = (e, xhr, file, files) => {\n  console.log('进度:', file.percent);\n};"
         },
         {
-          "name": "xhr",
-          "type": "XMLHttpRequest",
-          "description": "请求对象"
+            "name": "success",
+            "vueEventName": "@success",
+            "description": "文件上传成功时触发",
+            "payload": [
+                {
+                    "name": "res",
+                    "type": "any",
+                    "description": "服务器响应"
+                },
+                {
+                    "name": "xhr",
+                    "type": "XMLHttpRequest",
+                    "description": "请求对象"
+                },
+                {
+                    "name": "file",
+                    "type": "UploadFile",
+                    "description": "当前文件"
+                },
+                {
+                    "name": "files",
+                    "type": "UploadFile[]",
+                    "description": "所有文件列表"
+                }
+            ],
+            "usageExample": "<Upload @success=\"handleSuccess\">",
+            "handlerExample": "const handleSuccess = (res, xhr, file, files) => {\n  console.log('上传成功:', res);\n};"
         },
         {
-          "name": "file",
-          "type": "UploadFile",
-          "description": "当前文件"
+            "name": "error",
+            "vueEventName": "@error",
+            "description": "文件超出限制或上传失败时触发",
+            "payload": [
+                {
+                    "name": "err",
+                    "type": "Error | RequestError",
+                    "description": "错误信息"
+                },
+                {
+                    "name": "file",
+                    "type": "File | File[] | UploadFile",
+                    "description": "相关文件"
+                },
+                {
+                    "name": "files",
+                    "type": "UploadFile[]",
+                    "description": "所有文件列表"
+                }
+            ],
+            "usageExample": "<Upload @error=\"handleError\">",
+            "handlerExample": "const handleError = (err, file, files) => {\n  Message.error(err.message);\n};"
+        }
+    ],
+    "methods": [
+        {
+            "name": "submit",
+            "description": "手动上传时，调用该方法开始上传",
+            "returnType": "void",
+            "usageExample": "uploadRef.value?.submit();"
+        }
+    ],
+    "typeDefinitions": [
+        {
+            "name": "UploadFile",
+            "definition": "type UploadFile = {\n  name: string\n  url?: string\n  status?: UploadFileStatus\n  type?: string\n  size?: number\n  percent?: number\n  uid?: number\n  raw?: File\n}",
+            "description": "上传文件对象类型"
         },
         {
-          "name": "files",
-          "type": "UploadFile[]",
-          "description": "所有文件列表"
+            "name": "UploadFileStatus",
+            "definition": "enum UploadFileStatus {\n  Done,\n  Ready,\n  NotReady,\n  Uploading,\n  Error\n}",
+            "description": "文件上传状态"
         }
-      ],
-      "usageExample": "<Upload @progress=\"handleProgress\"></Upload>",
-      "handlerExample": "const handleProgress = (e, xhr, file, files) => {\n  console.log('进度:', file.percent);\n};"
-    },
-    {
-      "name": "success",
-      "vueEventName": "@success",
-      "description": "文件上传成功时触发",
-      "payload": [
-        {
-          "name": "res",
-          "type": "any",
-          "description": "服务器响应"
+    ],
+    "examples": [
+        {
+            "id": "upload_basic",
+            "title": "基础用法",
+            "description": "基本的文件上传",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { Upload, Message } from '@king-design/vue';\n\nconst handleError = (err: any) => {\n  Message.error(err.message);\n};\n\nconst handleSuccess = (res: any) => {\n  Message.success('上传成功');\n};\n</script>\n<template>\n  <Upload \n    action=\"/api/upload\"\n    @error=\"handleError\"\n    @success=\"handleSuccess\"\n  />\n</template>",
+            "tags": [
+                "basic"
+            ],
+            "usedProps": [
+                "action"
+            ],
+            "usedEvents": [
+                "success",
+                "error"
+            ],
+            "usedMethods": [],
+            "scenario": "创建一个基本的文件上传"
         },
         {
-          "name": "xhr",
-          "type": "XMLHttpRequest",
-          "description": "请求对象"
+            "id": "upload_drag",
+            "title": "拖拽上传",
+            "description": "拖拽风格的上传区域",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { Upload } from '@king-design/vue';\n</script>\n<template>\n  <Upload \n    type=\"drag\"\n    action=\"/api/upload\"\n    multiple\n  />\n</template>",
+            "tags": [
+                "drag",
+                "type"
+            ],
+            "usedProps": [
+                "action",
+                "type",
+                "multiple"
+            ],
+            "usedEvents": [],
+            "usedMethods": [],
+            "scenario": "创建拖拽上传区域"
         },
         {
-          "name": "file",
-          "type": "UploadFile",
-          "description": "当前文件"
+            "id": "upload_gallery",
+            "title": "照片墙风格",
+            "description": "照片墙风格的图片上传",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { Upload, Message } from '@king-design/vue';\n\nconst handleError = (err: any) => {\n  Message.error(err.message);\n};\n</script>\n<template>\n  <Upload \n    type=\"gallery\"\n    action=\"/api/upload\"\n    multiple\n    accept=\".jpg, .png, .gif\"\n    :limit=\"5\"\n    @error=\"handleError\"\n  />\n</template>",
+            "tags": [
+                "gallery",
+                "image"
+            ],
+            "usedProps": [
+                "action",
+                "type",
+                "multiple",
+                "accept",
+                "limit"
+            ],
+            "usedEvents": [
+                "error"
+            ],
+            "usedMethods": [],
+            "scenario": "创建照片墙风格的图片上传"
         },
         {
-          "name": "files",
-          "type": "UploadFile[]",
-          "description": "所有文件列表"
+            "id": "upload_limit",
+            "title": "限制文件",
+            "description": "限制文件类型、大小和数量",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { Upload, Message } from '@king-design/vue';\n\nconst handleError = (err: any) => {\n  Message.error(err.message);\n};\n</script>\n<template>\n  <Upload \n    action=\"/api/upload\"\n    accept=\".jpg, .png\"\n    :maxSize=\"500\"\n    :limit=\"3\"\n    multiple\n    @error=\"handleError\"\n  >\n    <template #tip>只能上传 JPG/PNG 格式，不超过 500KB，最多 3 个文件</template>\n  </Upload>\n</template>",
+            "tags": [
+                "limit",
+                "maxSize",
+                "accept"
+            ],
+            "usedProps": [
+                "action",
+                "accept",
+                "maxSize",
+                "limit",
+                "multiple"
+            ],
+            "usedEvents": [
+                "error"
+            ],
+            "usedMethods": [],
+            "scenario": "限制文件类型、大小和数量"
+        },
+        {
+            "id": "upload_manual",
+            "title": "手动上传",
+            "description": "手动控制上传时机",
+            "difficulty": "medium",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { Upload, Button } from '@king-design/vue';\n\nconst upload = ref<InstanceType<typeof Upload>>();\n\nconst handleUpload = () => {\n  upload.value?.submit();\n};\n</script>\n<template>\n  <div>\n    <Upload \n      ref=\"upload\"\n      action=\"/api/upload\"\n      :autoUpload=\"false\"\n      multiple\n    >\n      <Button type=\"primary\">选择文件</Button>\n    </Upload>\n    <Button @click=\"handleUpload\">开始上传</Button>\n  </div>\n</template>",
+            "tags": [
+                "manual",
+                "autoUpload",
+                "submit"
+            ],
+            "usedProps": [
+                "action",
+                "autoUpload",
+                "multiple"
+            ],
+            "usedEvents": [],
+            "usedMethods": [
+                "submit"
+            ],
+            "scenario": "手动控制上传时机"
+        },
+        {
+            "id": "upload_before",
+            "title": "上传前验证",
+            "description": "上传前进行文件验证",
+            "difficulty": "medium",
+            "code": "<script setup lang=\"ts\">\nimport { Upload, Message } from '@king-design/vue';\nimport type { UploadFile } from '@king-design/vue';\n\nconst beforeUpload = (file: UploadFile): boolean => {\n  if (!file.name.endsWith('.jpg') && !file.name.endsWith('.png')) {\n    Message.error('只能上传 JPG/PNG 格式的文件');\n    return false;\n  }\n  if (file.size && file.size > 1024 * 1024) {\n    Message.error('文件大小不能超过 1MB');\n    return false;\n  }\n  return true;\n};\n</script>\n<template>\n  <Upload \n    action=\"/api/upload\"\n    :beforeUpload=\"beforeUpload\"\n  />\n</template>",
+            "tags": [
+                "beforeUpload",
+                "validate"
+            ],
+            "usedProps": [
+                "action",
+                "beforeUpload"
+            ],
+            "usedEvents": [],
+            "usedMethods": [],
+            "scenario": "上传前进行文件验证"
         }
-      ],
-      "usageExample": "<Upload @success=\"handleSuccess\"></Upload>",
-      "handlerExample": "const handleSuccess = (res, xhr, file, files) => {\n  console.log('上传成功:', res);\n};"
-    },
-    {
-      "name": "error",
-      "vueEventName": "@error",
-      "description": "文件超出限制或上传失败时触发",
-      "payload": [
-        {
-          "name": "err",
-          "type": "Error | RequestError",
-          "description": "错误信息"
+    ],
+    "commonMistakes": [
+        {
+            "id": "upload_missing_action",
+            "description": "未设置 action 属性",
+            "wrongCode": "<Upload /> <!-- 缺少上传地址 -->",
+            "correctCode": "<Upload action=\"/api/upload\" />",
+            "explanation": "必须设置 action 属性指定上传地址",
+            "relatedProps": [
+                "action"
+            ]
         },
         {
-          "name": "file",
-          "type": "File | File[] | UploadFile",
-          "description": "相关文件"
+            "id": "upload_max_size_unit",
+            "description": "maxSize 单位理解错误",
+            "wrongCode": "<Upload :maxSize=\"1024 * 1024\" /> <!-- 期望 1MB，实际是 1GB -->",
+            "correctCode": "<Upload :maxSize=\"1024\" /> <!-- 1MB = 1024KB -->",
+            "explanation": "maxSize 单位是 KB，1MB = 1024KB",
+            "relatedProps": [
+                "maxSize"
+            ]
         },
         {
-          "name": "files",
-          "type": "UploadFile[]",
-          "description": "所有文件列表"
+            "id": "upload_auto_upload_submit",
+            "description": "设置 autoUpload 为 false 但忘记调用 submit",
+            "wrongCode": "<Upload :autoUpload=\"false\" /> <!-- 文件不会自动上传 -->",
+            "correctCode": "<Upload ref=\"upload\" :autoUpload=\"false\" />\n// 需要手动调用 upload.value?.submit()",
+            "explanation": "设置 autoUpload 为 false 后需要手动调用 submit 方法上传",
+            "relatedProps": [
+                "autoUpload"
+            ]
         }
-      ],
-      "usageExample": "<Upload @error=\"handleError\"></Upload>",
-      "handlerExample": "const handleError = (err, file, files) => {\n  Message.error(err.message);\n};"
-    }
-  ],
-  "methods": [
-    {
-      "name": "submit",
-      "description": "手动上传时，调用该方法开始上传",
-      "returnType": "void",
-      "usageExample": "uploadRef.value?.submit();"
-    }
-  ],
-  "slots": [
-    {
-      "name": "content",
-      "description": "组件展示的内容，当没有子元素时，默认会根据type展示不同的内容"
-    },
-    {
-      "name": "tip",
-      "description": "组件展示的提示信息"
-    }
-  ],
-  "typeDefinitions": [
-    {
-      "name": "UploadFile",
-      "definition": "type UploadFile = {\n  name: string\n  url?: string\n  status?: UploadFileStatus\n  type?: string\n  size?: number\n  percent?: number\n  uid?: number\n  raw?: File\n}",
-      "description": "上传文件对象类型"
-    },
-    {
-      "name": "UploadFileStatus",
-      "definition": "enum UploadFileStatus {\n  Done,\n  Ready,\n  NotReady,\n  Uploading,\n  Error\n}",
-      "description": "文件上传状态"
-    }
-  ],
-  "examples": [
-    {
-      "id": "upload_basic",
-      "title": "基础用法",
-      "description": "基本的文件上传",
-      "difficulty": "easy",
-      "code": "<script setup lang=\"ts\">\nimport { Upload, Message } from '@king-design/vue';\n\nconst handleError = (err: any) => {\n  Message.error(err.message);\n};\n\nconst handleSuccess = (res: any) => {\n  Message.success('上传成功');\n};\n</script>\n<template>\n  <Upload \n    action=\"/api/upload\"\n    @error=\"handleError\"\n    @success=\"handleSuccess\"\n  />\n</template>",
-      "tags": [
-        "basic"
-      ],
-      "usedProps": [
-        "action"
-      ],
-      "usedEvents": [
-        "success",
-        "error"
-      ],
-      "usedMethods": [],
-      "scenario": "创建一个基本的文件上传"
-    },
-    {
-      "id": "upload_drag",
-      "title": "拖拽上传",
-      "description": "拖拽风格的上传区域",
-      "difficulty": "easy",
-      "code": "<script setup lang=\"ts\">\nimport { Upload } from '@king-design/vue';\n</script>\n<template>\n  <Upload \n    type=\"drag\"\n    action=\"/api/upload\"\n    multiple\n  />\n</template>",
-      "tags": [
-        "drag",
-        "type"
-      ],
-      "usedProps": [
-        "action",
-        "type",
-        "multiple"
-      ],
-      "usedEvents": [],
-      "usedMethods": [],
-      "scenario": "创建拖拽上传区域"
-    },
-    {
-      "id": "upload_gallery",
-      "title": "照片墙风格",
-      "description": "照片墙风格的图片上传",
-      "difficulty": "easy",
-      "code": "<script setup lang=\"ts\">\nimport { Upload, Message } from '@king-design/vue';\n\nconst handleError = (err: any) => {\n  Message.error(err.message);\n};\n</script>\n<template>\n  <Upload \n    type=\"gallery\"\n    action=\"/api/upload\"\n    multiple\n    accept=\".jpg, .png, .gif\"\n    :limit=\"5\"\n    @error=\"handleError\"\n  />\n</template>",
-      "tags": [
-        "gallery",
-        "image"
-      ],
-      "usedProps": [
-        "action",
-        "type",
-        "multiple",
-        "accept",
-        "limit"
-      ],
-      "usedEvents": [
-        "error"
-      ],
-      "usedMethods": [],
-      "scenario": "创建照片墙风格的图片上传"
-    },
-    {
-      "id": "upload_limit",
-      "title": "限制文件",
-      "description": "限制文件类型、大小和数量",
-      "difficulty": "easy",
-      "code": "<script setup lang=\"ts\">\nimport { Upload, Message } from '@king-design/vue';\n\nconst handleError = (err: any) => {\n  Message.error(err.message);\n};\n</script>\n<template>\n  <Upload \n    action=\"/api/upload\"\n    accept=\".jpg, .png\"\n    :maxSize=\"500\"\n    :limit=\"3\"\n    multiple\n    @error=\"handleError\"\n  >\n    <template #tip>只能上传 JPG/PNG 格式，不超过 500KB，最多 3 个文件</template>\n  </Upload>\n</template>",
-      "tags": [
-        "limit",
-        "maxSize",
-        "accept"
-      ],
-      "usedProps": [
-        "action",
-        "accept",
-        "maxSize",
-        "limit",
-        "multiple"
-      ],
-      "usedEvents": [
-        "error"
-      ],
-      "usedMethods": [],
-      "scenario": "限制文件类型、大小和数量"
-    },
-    {
-      "id": "upload_manual",
-      "title": "手动上传",
-      "description": "手动控制上传时机",
-      "difficulty": "medium",
-      "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { Upload, Button } from '@king-design/vue';\n\nconst upload = ref<InstanceType<typeof Upload>>();\n\nconst handleUpload = () => {\n  upload.value?.submit();\n};\n</script>\n<template>\n  <div>\n    <Upload \n      ref=\"upload\"\n      action=\"/api/upload\"\n      :autoUpload=\"false\"\n      multiple\n    >\n      <Button type=\"primary\">选择文件</Button>\n    </Upload>\n    <Button @click=\"handleUpload\">开始上传</Button>\n  </div>\n</template>",
-      "tags": [
-        "manual",
-        "autoUpload",
-        "submit"
-      ],
-      "usedProps": [
-        "action",
-        "autoUpload",
-        "multiple"
-      ],
-      "usedEvents": [],
-      "usedMethods": [
-        "submit"
-      ],
-      "scenario": "手动控制上传时机"
-    },
-    {
-      "id": "upload_before",
-      "title": "上传前验证",
-      "description": "上传前进行文件验证",
-      "difficulty": "medium",
-      "code": "<script setup lang=\"ts\">\nimport { Upload, Message } from '@king-design/vue';\nimport type { UploadFile } from '@king-design/vue';\n\nconst beforeUpload = (file: UploadFile): boolean => {\n  if (!file.name.endsWith('.jpg') && !file.name.endsWith('.png')) {\n    Message.error('只能上传 JPG/PNG 格式的文件');\n    return false;\n  }\n  if (file.size && file.size > 1024 * 1024) {\n    Message.error('文件大小不能超过 1MB');\n    return false;\n  }\n  return true;\n};\n</script>\n<template>\n  <Upload \n    action=\"/api/upload\"\n    :beforeUpload=\"beforeUpload\"\n  />\n</template>",
-      "tags": [
-        "beforeUpload",
-        "validate"
-      ],
-      "usedProps": [
-        "action",
-        "beforeUpload"
-      ],
-      "usedEvents": [],
-      "usedMethods": [],
-      "scenario": "上传前进行文件验证"
-    }
-  ],
-  "commonMistakes": [
-    {
-      "id": "upload_missing_action",
-      "description": "未设置 action 属性",
-      "wrongCode": "<Upload /> <!-- 缺少上传地址 -->",
-      "correctCode": "<Upload action=\"/api/upload\" />",
-      "explanation": "必须设置 action 属性指定上传地址",
-      "relatedProps": [
-        "action"
-      ]
-    },
-    {
-      "id": "upload_max_size_unit",
-      "description": "maxSize 单位理解错误",
-      "wrongCode": "<Upload :maxSize=\"1024 * 1024\" /> <!-- 期望 1MB，实际是 1GB -->",
-      "correctCode": "<Upload :maxSize=\"1024\" /> <!-- 1MB = 1024KB -->",
-      "explanation": "maxSize 单位是 KB，1MB = 1024KB",
-      "relatedProps": [
-        "maxSize"
-      ]
-    },
-    {
-      "id": "upload_auto_upload_submit",
-      "description": "设置 autoUpload 为 false 但忘记调用 submit",
-      "wrongCode": "<Upload :autoUpload=\"false\" /> <!-- 文件不会自动上传 -->",
-      "correctCode": "<Upload ref=\"upload\" :autoUpload=\"false\" />\n// 需要手动调用 upload.value?.submit()",
-      "explanation": "设置 autoUpload 为 false 后需要手动调用 submit 方法上传",
-      "relatedProps": [
-        "autoUpload"
-      ]
-    }
-  ],
-  "searchKeywords": [
-    "上传",
-    "upload",
-    "文件上传",
-    "拖拽上传",
-    "图片上传",
-    "附件"
-  ],
-  "useCases": [
-    "图片上传",
-    "文档上传",
-    "头像上传",
-    "附件上传",
-    "批量文件上传"
-  ],
-  "relatedComponents": [
-    "Button",
-    "Progress"
-  ]
+    ],
+    "searchKeywords": [
+        "上传",
+        "upload",
+        "文件上传",
+        "拖拽上传",
+        "图片上传",
+        "附件"
+    ],
+    "useCases": [
+        "图片上传",
+        "文档上传",
+        "头像上传",
+        "附件上传",
+        "批量文件上传"
+    ],
+    "relatedComponents": [
+        "Button",
+        "Progress"
+    ]
 }