king-design-analyzer 1.0.0

package/components/upload.json

@@ -0,0 +1,499 @@
+{
+    "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
+                },
+                {
+                    "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'}\" />"
+        },
+        {
+            "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": "进度事件"
+                },
+                {
+                    "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": "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": "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();"
+        }
+    ],
+    "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"
+    ]
+}