From d70ff310bbf6a1725663852d84a416651e84b665 Mon Sep 17 00:00:00 2001 From: "Y." Date: Tue, 19 Nov 2024 17:50:15 +0800 Subject: [PATCH] feat(Upload): support capture props (#1644) --- src/upload/props.ts | 22 ++++++++++++++-------- src/upload/type.ts | 23 ++++++++++++++--------- src/upload/upload.en-US.md | 18 +++++++++--------- src/upload/upload.md | 27 ++++++++++++++------------- src/upload/upload.tsx | 1 + 5 files changed, 52 insertions(+), 39 deletions(-) diff --git a/src/upload/props.ts b/src/upload/props.ts index 6a6178ae2..12c53be8c 100644 --- a/src/upload/props.ts +++ b/src/upload/props.ts @@ -18,7 +18,7 @@ export default { type: String, default: '', }, - /** 添加按钮内容。值为空，使用默认图标渲染；值为 slot 则表示使用插槽渲染；其他值无效。 */ + /** 添加按钮内容。值为空，使用默认图标渲染；值为 slot 则表示使用插槽渲染；其他值无效 */ addContent: { type: [String, Function] as PropType, }, @@ -37,12 +37,19 @@ export default { beforeUpload: { type: Function as PropType, }, + /** 图片选取模式，可选值为 camera (直接调起摄像头) */ + capture: { + type: String, + }, /** 上传请求所需的额外字段，默认字段有 `file`，表示文件信息。可以添加额外的文件名字段，如：`{file_name: "custom-file-name.txt"}`。`autoUpload=true` 时有效。也可以使用 `formatRequest` 完全自定义上传请求的字段 */ data: { type: Object as PropType, }, - /** 是否禁用 */ - disabled: Boolean, + /** 是否禁用组件 */ + disabled: { + type: Boolean, + default: undefined, + }, /** 用于完全自定义文件列表界面内容(UI)，单文件和多文件均有效 */ fileListDisplay: { type: Function as PropType, @@ -61,7 +68,7 @@ export default { format: { type: Function as PropType, }, - /** 用于新增或修改文件上传请求参数。`action` 存在时有效。一个请求上传一个文件时，默认请求字段有 `file`；
一个请求上传多个文件时，默认字段有 `file[0]/file[1]/file[2]/.../length`，其中 `length` 表示本次上传的文件数量。
⚠️非常注意，此处的 `file[0]/file[1]` 仅仅是一个字段名，并非表示 `file` 是一个数组，接口获取字段时注意区分。
可以使用 `name` 定义 `file` 字段的别名，也可以使用 `formatRequest` 自定义任意字段 */ + /** 用于新增或修改文件上传请求 参数。`action` 存在时有效。一个请求上传一个文件时，默认请求字段有 `file`。
一个请求上传多个文件时，默认字段有 `file[0]/file[1]/file[2]/.../length`，其中 `length` 表示本次上传的文件数量。
⚠️非常注意，此处的 `file[0]/file[1]` 仅仅是一个字段名，并非表示 `file` 是一个数组，接口获取字段时注意区分。
可以使用 `name` 定义 `file` 字段的别名。
也可以使用 `formatRequest` 自定义任意字段，如添加一个字段 `fileList` ，存储文件数组 */ formatRequest: { type: Function as PropType, }, @@ -112,8 +119,7 @@ export default { sizeLimit: { type: [Number, Object] as PropType, }, - - /** 是否在请求时间超过 300ms 后显示模拟进度。上传进度有模拟进度和真实进度两种。一般大小的文件上传，真实的上传进度只有 0 和 100，不利于交互呈现，因此组件内置模拟上传进度。真实上传进度一般用于大文件上传。 */ + /** 是否在请求时间超过 300ms 后显示模拟进度。上传进度有模拟进度和真实进度两种。一般大小的文件上传，真实的上传进度只有 0 和 100，不利于交互呈现，因此组件内置模拟上传进度。真实上传进度一般用于大文件上传 */ useMockProgress: { type: Boolean, default: true, @@ -140,6 +146,8 @@ export default { onCancelUpload: Function as PropType, /** 已上传文件列表发生变化时触发，`trigger` 表示触发本次的来源 */ onChange: Function as PropType, + /** 点击上传区域时触发 */ + onClickUpload: Function as PropType, /** 上传失败后触发。`response` 指接口响应结果，`response.error` 会作为错误文本提醒。如果希望判定为上传失败，但接口响应数据不包含 `error` 字段，可以使用 `formatResponse` 格式化 `response` 数据结构。如果是多文件多请求上传场景，请到事件 `onOneFileFail` 中查看 `response` */ onFail: Function as PropType, /** 多文件/图片场景下，单个文件上传失败后触发，如果一个请求上传一个文件，则会触发多次。单文件/图片不会触发 */ @@ -160,6 +168,4 @@ export default { onValidate: Function as PropType, /** 待上传文件列表发生变化时触发。`context.files` 表示事件参数为待上传文件，`context.trigger` 引起此次变化的触发来源 */ onWaitingUploadFilesChange: Function as PropType, - /** 点击上传区域时触发。TS 类型：`(context: { e: MouseEvent })` */ - onClickUpload: Function as PropType, }; diff --git a/src/upload/type.ts b/src/upload/type.ts index 26724211e..560c112aa 100644 --- a/src/upload/type.ts +++ b/src/upload/type.ts @@ -19,7 +19,7 @@ export interface TdUploadProps { */ action?: string; /** - * 添加按钮内容。值为空，使用默认图标渲染；值为 slot 则表示使用插槽渲染；其他值无效。 + * 添加按钮内容。值为空，使用默认图标渲染；值为 slot 则表示使用插槽渲染；其他值无效 */ addContent?: string | TNode; /** @@ -40,12 +40,17 @@ export interface TdUploadProps { */ beforeAllFilesUpload?: (file: UploadFile[]) => boolean | Promise; beforeUpload?: (file: UploadFile) => boolean | Promise; + /** + * 图片选取模式，可选值为 camera (直接调起摄像头) + * @default '' + */ + capture?: string; /** * 上传请求所需的额外字段，默认字段有 `file`，表示文件信息。可以添加额外的文件名字段，如：`{file_name: "custom-file-name.txt"}`。`autoUpload=true` 时有效。也可以使用 `formatRequest` 完全自定义上传请求的字段 */ data?: Record | ((files: UploadFile[]) => Record); /** - * 是否禁用 + * 是否禁用组件 */ disabled?: boolean; /** @@ -67,7 +72,7 @@ export interface TdUploadProps { */ format?: (file: File) => UploadFile; /** - * 用于新增或修改文件上传请求参数。`action` 存在时有效。一个请求上传一个文件时，默认请求字段有 `file`；
一个请求上传多个文件时，默认字段有 `file[0]/file[1]/file[2]/.../length`，其中 `length` 表示本次上传的文件数量。
⚠️非常注意，此处的 `file[0]/file[1]` 仅仅是一个字段名，并非表示 `file` 是一个数组，接口获取字段时注意区分。
可以使用 `name` 定义 `file` 字段的别名，也可以使用 `formatRequest` 自定义任意字段 + * 用于新增或修改文件上传请求 参数。`action` 存在时有效。一个请求上传一个文件时，默认请求字段有 `file`。
一个请求上传多个文件时，默认字段有 `file[0]/file[1]/file[2]/.../length`，其中 `length` 表示本次上传的文件数量。
⚠️非常注意，此处的 `file[0]/file[1]` 仅仅是一个字段名，并非表示 `file` 是一个数组，接口获取字段时注意区分。
可以使用 `name` 定义 `file` 字段的别名。
也可以使用 `formatRequest` 自定义任意字段，如添加一个字段 `fileList` ，存储文件数组 */ formatRequest?: (requestData: { [key: string]: any }) => { [key: string]: any }; /** @@ -120,7 +125,7 @@ export interface TdUploadProps { */ sizeLimit?: number | SizeLimitObj; /** - * 是否在请求时间超过 300ms 后显示模拟进度。上传进度有模拟进度和真实进度两种。一般大小的文件上传，真实的上传进度只有 0 和 100，不利于交互呈现，因此组件内置模拟上传进度。真实上传进度一般用于大文件上传。 + * 是否在请求时间超过 300ms 后显示模拟进度。上传进度有模拟进度和真实进度两种。一般大小的文件上传，真实的上传进度只有 0 和 100，不利于交互呈现，因此组件内置模拟上传进度。真实上传进度一般用于大文件上传 * @default true */ useMockProgress?: boolean; @@ -157,6 +162,10 @@ export interface TdUploadProps { * 已上传文件列表发生变化时触发，`trigger` 表示触发本次的来源 */ onChange?: (value: Array, context: UploadChangeContext) => void; + /** + * 点击上传区域时触发 + */ + onClickUpload?: (context: { e: MouseEvent }) => void; /** * 上传失败后触发。`response` 指接口响应结果，`response.error` 会作为错误文本提醒。如果希望判定为上传失败，但接口响应数据不包含 `error` 字段，可以使用 `formatResponse` 格式化 `response` 数据结构。如果是多文件多请求上传场景，请到事件 `onOneFileFail` 中查看 `response` */ @@ -200,10 +209,6 @@ export interface TdUploadProps { files: Array; trigger: 'validate' | 'remove' | 'uploaded'; }) => void; - /** - * 点击上传区域时触发。TS 类型：`(context: { e: MouseEvent })` - */ - onClickUpload?: (context: { e: MouseEvent }) => void; } export interface UploadFile extends PlainObject { @@ -309,7 +314,7 @@ export interface ProgressContext { export type UploadProgressType = 'real' | 'mock'; export interface UploadRemoveContext { - index: number; + index?: number; file?: UploadFile; e: MouseEvent; } diff --git a/src/upload/upload.en-US.md b/src/upload/upload.en-US.md index dd1edde34..1ab50e861 100644 --- a/src/upload/upload.en-US.md +++ b/src/upload/upload.en-US.md @@ -1,6 +1,7 @@ :: BASE_DOC :: ## API + ### Upload Props name | type | default | description | required @@ -11,18 +12,18 @@ addContent | String / Slot / Function | - | Typescript：`string \| TNode`。[se allowUploadDuplicateFile | Boolean | false | allow to upload duplicate name files | N autoUpload | Boolean | true | post upload request automatically after files being selected | N beforeUpload | Function | - | stop one of files to upload。Typescript：`(file: UploadFile) => boolean \| Promise` | N +capture | String | - | \- | N data | Object | - | extra request data of uploading. `formatRequest` can redefine all request data。Typescript：`Record \| ((files: UploadFile[]) => Record)` | N -disabled | Boolean | - | make upload to be disabled | N -fileListDisplay | Slot / Function | - | used to render file list UI。Typescript：`TNode<{ files: UploadFile[]; dragEvents?: UploadDisplayDragEvents }>`。[see more ts definition](https://github.com/Tencent/tdesign-mobile-vue/blob/develop/src/common.ts) | N +disabled | Boolean | undefined | make upload to be disabled | N files | Array | [] | `v-model:files` is supported。Typescript：`Array` | N defaultFiles | Array | [] | uncontrolled property。Typescript：`Array` | N format | Function | - | to redefine `UploadFile` data structure。Typescript：`(file: File) => UploadFile` | N formatRequest | Function | - | redefine request data。Typescript：`(requestData: { [key: string]: any }) => { [key: string]: any }` | N -formatResponse | Function | - | redefine response data structure。Typescript：`(response: any, context: FormatResponseContext) => ResponseType ` `type ResponseType = { error?: string; url?: string } & Record` `interface FormatResponseContext { file: UploadFile; currentFiles?: UploadFile[] }`。[see more ts definition](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/upload/type.ts) | N +formatResponse | Function | - | redefine response data structure。Typescript：`(response: any, context: FormatResponseContext) => ResponseType` `type ResponseType = { error?: string; url?: string } & Record` ` interface FormatResponseContext { file: UploadFile; currentFiles?: UploadFile[] }`。[see more ts definition](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/upload/type.ts) | N headers | Object | - | HTTP Request Header。Typescript：`{[key: string]: string}` | N imageProps | Object | - | Typescript：`ImageProps`，[Image API Documents](./image?tab=api)。[see more ts definition](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/upload/type.ts) | N max | Number | 0 | max count of files limit | N -method | String | POST | HTTP request method。options: POST/GET/PUT/OPTION/PATCH/post/get/put/option/patch | N +method | String | POST | HTTP request method。options: POST/GET/PUT/OPTIONS/PATCH/post/get/put/options/patch | N multiple | Boolean | false | multiple files uploading | N requestMethod | Function | - | custom upload request method。Typescript：`(files: UploadFile \| UploadFile[]) => Promise` `interface RequestMethodResponse { status: 'success' \| 'fail'; error?: string; response: { url?: string; files?: UploadFile[]; [key: string]: any } }`。[see more ts definition](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/upload/type.ts) | N sizeLimit | Number / Object | - | files size limit。Typescript：`number \| SizeLimitObj` `interface SizeLimitObj { size: number; unit: SizeUnit ; message?: string }` `type SizeUnitArray = ['B', 'KB', 'MB', 'GB']` `type SizeUnit = SizeUnitArray[number]`。[see more ts definition](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/upload/type.ts) | N @@ -31,6 +32,7 @@ value | Array | [] | file list。`v-model` and `v-model:value` is supported。Ty defaultValue | Array | [] | file list。uncontrolled property。Typescript：`Array` | N withCredentials | Boolean | false | uploading request with cookie | N onChange | Function | | Typescript：`(value: Array, context: UploadChangeContext) => void`
trigger on uploaded files change。[see more ts definition](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/upload/type.ts)。
`interface UploadChangeContext { e?: MouseEvent \| ProgressEvent; response?: any; trigger: UploadChangeTrigger; index?: number; file?: UploadFile; files?: UploadFile[] }`

`type UploadChangeTrigger = 'add' \| 'remove' \| 'abort' \| 'progress-success' \| 'progress' \| 'progress-fail'`
| N +onClickUpload | Function | | Typescript：`(context: { e: MouseEvent }) => void`
| N onFail | Function | | Typescript：`(options: UploadFailContext) => void`
`response.error` used for error tips, `formatResponse` can format `response`。[see more ts definition](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/upload/type.ts)。
`interface UploadFailContext { e?: ProgressEvent; failedFiles: UploadFile[]; currentFiles: UploadFile[]; response?: any; file: UploadFile; XMLHttpRequest?: XMLHttpRequest}`
| N onPreview | Function | | Typescript：`(options: { file: UploadFile; index: number; e: MouseEvent }) => void`
trigger on preview elements click | N onProgress | Function | | Typescript：`(options: ProgressContext) => void`
uploading request progress event。[see more ts definition](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/upload/type.ts)。
`interface ProgressContext { e?: ProgressEvent; file?: UploadFile; currentFiles: UploadFile[]; percent: number; type: UploadProgressType; XMLHttpRequest?: XMLHttpRequest }`

`type UploadProgressType = 'real' \| 'mock'`
| N @@ -38,14 +40,13 @@ onRemove | Function | | Typescript：`(context: UploadRemoveContext) => void` void`
trigger after file choose and before upload。[see more ts definition](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/upload/type.ts)。
`interface UploadSelectChangeContext { currentSelectedFiles: UploadFile[] }`
| N onSuccess | Function | | Typescript：`(context: SuccessContext) => void`
trigger on all files uploaded successfully。[see more ts definition](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/upload/type.ts)。
`interface SuccessContext { e?: ProgressEvent; file?: UploadFile; fileList?: UploadFile[]; currentFiles?: UploadFile[]; response?: any; results?: SuccessContext[]; XMLHttpRequest?: XMLHttpRequest }`
| N onValidate | Function | | Typescript：`(context: { type: UploadValidateType, files: UploadFile[] }) => void`
trigger on length over limit, or trigger on file size over limit。[see more ts definition](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/upload/type.ts)。
`type UploadValidateType = 'FILE_OVER_SIZE_LIMIT' \| 'FILES_OVER_LENGTH_LIMIT' \| 'FILTER_FILE_SAME_NAME' \| 'BEFORE_ALL_FILES_UPLOAD' \| 'CUSTOM_BEFORE_UPLOAD'`
| N -onClickUpload | Function | - | trigger on upload area click. Typescript：`(context: { e: MouseEvent })` | N - ### Upload Events name | params | description -- | -- | -- change | `(value: Array, context: UploadChangeContext)` | trigger on uploaded files change。[see more ts definition](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/upload/type.ts)。
`interface UploadChangeContext { e?: MouseEvent \| ProgressEvent; response?: any; trigger: UploadChangeTrigger; index?: number; file?: UploadFile; files?: UploadFile[] }`

`type UploadChangeTrigger = 'add' \| 'remove' \| 'abort' \| 'progress-success' \| 'progress' \| 'progress-fail'`
+click-upload | `(context: { e: MouseEvent })` | \- fail | `(options: UploadFailContext)` | `response.error` used for error tips, `formatResponse` can format `response`。[see more ts definition](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/upload/type.ts)。
`interface UploadFailContext { e?: ProgressEvent; failedFiles: UploadFile[]; currentFiles: UploadFile[]; response?: any; file: UploadFile; XMLHttpRequest?: XMLHttpRequest}`
preview | `(options: { file: UploadFile; index: number; e: MouseEvent })` | trigger on preview elements click progress | `(options: ProgressContext)` | uploading request progress event。[see more ts definition](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/upload/type.ts)。
`interface ProgressContext { e?: ProgressEvent; file?: UploadFile; currentFiles: UploadFile[]; percent: number; type: UploadProgressType; XMLHttpRequest?: XMLHttpRequest }`

`type UploadProgressType = 'real' \| 'mock'`
@@ -53,7 +54,6 @@ remove | `(context: UploadRemoveContext)` | trigger on file removed。[see more select-change | `(files: File[], context: UploadSelectChangeContext)` | trigger after file choose and before upload。[see more ts definition](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/upload/type.ts)。
`interface UploadSelectChangeContext { currentSelectedFiles: UploadFile[] }`
success | `(context: SuccessContext)` | trigger on all files uploaded successfully。[see more ts definition](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/upload/type.ts)。
`interface SuccessContext { e?: ProgressEvent; file?: UploadFile; fileList?: UploadFile[]; currentFiles?: UploadFile[]; response?: any; results?: SuccessContext[]; XMLHttpRequest?: XMLHttpRequest }`
validate | `(context: { type: UploadValidateType, files: UploadFile[] })` | trigger on length over limit, or trigger on file size over limit。[see more ts definition](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/upload/type.ts)。
`type UploadValidateType = 'FILE_OVER_SIZE_LIMIT' \| 'FILES_OVER_LENGTH_LIMIT' \| 'FILTER_FILE_SAME_NAME' \| 'BEFORE_ALL_FILES_UPLOAD' \| 'CUSTOM_BEFORE_UPLOAD'`
-clickUpload | `(context: { e: MouseEvent })` | trigger on upload area click. ### UploadFile @@ -71,8 +71,8 @@ uploadTime | String | - | upload time | N url | String | - | \- | N `PlainObject` | \- | - | `PlainObject` is not an attribute of UploadFile，it means you can add and attributes to UploadFile, `type PlainObject = {[key: string]: any}`' | N - ### CSS Variables + The component provides the following CSS variables, which can be used to customize styles. Name | Default Value | Description -- | -- | -- @@ -83,4 +83,4 @@ Name | Default Value | Description --td-upload-grid-columns | 4 | - --td-upload-height | 80px | - --td-upload-radius | @radius-default | - ---td-upload-width | 80px | - +--td-upload-width | 80px | - \ No newline at end of file diff --git a/src/upload/upload.md b/src/upload/upload.md index 988c9e2d1..6c3af1eea 100644 --- a/src/upload/upload.md +++ b/src/upload/upload.md @@ -1,36 +1,38 @@ :: BASE_DOC :: ## API + ### Upload Props -名称 | 类型 | 默认值 | 说明 | 必传 +名称 | 类型 | 默认值 | 描述 | 必传 -- | -- | -- | -- | -- accept | String | - | 接受上传的文件类型，[查看 W3C示例](https://www.w3schools.com/tags/att_input_accept.asp)，[查看 MDN 示例](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/Input/file) | N action | String | - | 上传接口。设接口响应数据为字段 `response`，那么 `response.error` 存在时会判断此次上传失败，并显示错误文本信息；`response.url` 会作为文件上传成功后的地址，并使用该地址显示图片或文件 | N -addContent | String / Slot / Function | - | 添加按钮内容。值为空，使用默认图标渲染；值为 slot 则表示使用插槽渲染；其他值无效。。TS 类型：`string \| TNode`。[通用类型定义](https://github.com/Tencent/tdesign-mobile-vue/blob/develop/src/common.ts) | N +addContent | String / Slot / Function | - | 添加按钮内容。值为空，使用默认图标渲染；值为 slot 则表示使用插槽渲染；其他值无效。TS 类型：`string \| TNode`。[通用类型定义](https://github.com/Tencent/tdesign-mobile-vue/blob/develop/src/common.ts) | N allowUploadDuplicateFile | Boolean | false | 是否允许重复上传相同文件名的文件 | N autoUpload | Boolean | true | 是否在选择文件后自动发起请求上传文件 | N beforeUpload | Function | - | 如果是自动上传模式 `autoUpload=true`，表示单个文件上传之前的钩子函数，若函数返回值为 `false` 则表示不上传当前文件。
如果是非自动上传模式 `autoUpload=false`，函数返回值为 `false` 时表示从上传文件中剔除当前文件。TS 类型：`(file: UploadFile) => boolean \| Promise` | N +capture | String | - | 图片选取模式，可选值为 camera (直接调起摄像头) | N data | Object | - | 上传请求所需的额外字段，默认字段有 `file`，表示文件信息。可以添加额外的文件名字段，如：`{file_name: "custom-file-name.txt"}`。`autoUpload=true` 时有效。也可以使用 `formatRequest` 完全自定义上传请求的字段。TS 类型：`Record \| ((files: UploadFile[]) => Record)` | N -disabled | Boolean | - | 是否禁用 | N -fileListDisplay | Slot / Function | - | 【开发中】用于完全自定义文件列表界面内容(UI)，单文件和多文件均有效。TS 类型：`TNode<{ files: UploadFile[]; dragEvents?: UploadDisplayDragEvents }>`。[通用类型定义](https://github.com/Tencent/tdesign-mobile-vue/blob/develop/src/common.ts) | N +disabled | Boolean | undefined | 是否禁用组件 | N files | Array | [] | 已上传文件列表，同 `value`。TS 类型：`UploadFile`。支持语法糖 `v-model:files`。TS 类型：`Array` | N defaultFiles | Array | [] | 已上传文件列表，同 `value`。TS 类型：`UploadFile`。非受控属性。TS 类型：`Array` | N format | Function | - | 转换文件 `UploadFile` 的数据结构，可新增或修改 `UploadFile` 的属性，注意不能删除 `UploadFile` 属性。`action` 存在时有效。TS 类型：`(file: File) => UploadFile` | N -formatRequest | Function | - | 用于新增或修改文件上传请求参数。`action` 存在时有效。一个请求上传一个文件时，默认请求字段有 `file`；
一个请求上传多个文件时，默认字段有 `file[0]/file[1]/file[2]/.../length`，其中 `length` 表示本次上传的文件数量。
⚠️非常注意，此处的 `file[0]/file[1]` 仅仅是一个字段名，并非表示 `file` 是一个数组，接口获取字段时注意区分。
可以使用 `name` 定义 `file` 字段的别名，也可以使用 `formatRequest` 自定义任意字段。TS 类型：`(requestData: { [key: string]: any }) => { [key: string]: any }` | N -formatResponse | Function | - | 用于格式化文件上传后的接口响应数据，`response` 便是接口响应的原始数据。`action` 存在时有效。
此函数的返回值 `error` 或 `response.error` 会作为错误文本提醒，如果存在会判定为本次上传失败。
此函数的返回值 `url` 或 `response.url` 会作为上传成功后的链接。TS 类型：`(response: any, context: FormatResponseContext) => ResponseType ` `type ResponseType = { error?: string; url?: string } & Record` `interface FormatResponseContext { file: UploadFile; currentFiles?: UploadFile[] }`。[详细类型定义](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/upload/type.ts) | N +formatRequest | Function | - | 用于新增或修改文件上传请求 参数。`action` 存在时有效。一个请求上传一个文件时，默认请求字段有 `file`。
一个请求上传多个文件时，默认字段有 `file[0]/file[1]/file[2]/.../length`，其中 `length` 表示本次上传的文件数量。
⚠️非常注意，此处的 `file[0]/file[1]` 仅仅是一个字段名，并非表示 `file` 是一个数组，接口获取字段时注意区分。
可以使用 `name` 定义 `file` 字段的别名。
也可以使用 `formatRequest` 自定义任意字段，如添加一个字段 `fileList` ，存储文件数组。TS 类型：`(requestData: { [key: string]: any }) => { [key: string]: any }` | N +formatResponse | Function | - | 用于格式化文件上传后的接口响应数据，`response` 便是接口响应的原始数据。`action` 存在时有效。
此函数的返回值 `error` 或 `response.error` 会作为错误文本提醒，如果存在会判定为本次上传失败。
此函数的返回值 `url` 或 `response.url` 会作为上传成功后的链接。TS 类型：`(response: any, context: FormatResponseContext) => ResponseType` `type ResponseType = { error?: string; url?: string } & Record` ` interface FormatResponseContext { file: UploadFile; currentFiles?: UploadFile[] }`。[详细类型定义](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/upload/type.ts) | N headers | Object | - | 设置上传的请求头部，`action` 存在时有效。TS 类型：`{[key: string]: string}` | N imageProps | Object | - | 透传 Image 组件全部属性。TS 类型：`ImageProps`，[Image API Documents](./image?tab=api)。[详细类型定义](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/upload/type.ts) | N max | Number | 0 | 用于控制文件上传数量，值为 0 则不限制 | N -method | String | POST | HTTP 请求类型。可选项：POST/GET/PUT/OPTION/PATCH/post/get/put/option/patch | N +method | String | POST | HTTP 请求类型。可选项：POST/GET/PUT/OPTIONS/PATCH/post/get/put/options/patch | N multiple | Boolean | false | 支持多文件上传 | N requestMethod | Function | - | 自定义上传方法。返回值 `status` 表示上传成功或失败；`error` 或 `response.error` 表示上传失败的原因；
`response` 表示请求上传成功后的返回数据，`response.url` 表示上传成功后的图片/文件地址，`response.files` 表示一个请求上传多个文件/图片后的返回值。
示例一：`{ status: 'fail', error: '上传失败', response }`。
示例二：`{ status: 'success', response: { url: 'https://tdesign.gtimg.com/site/avatar.jpg' } }`。
示例三：`{ status: 'success', files: [{ url: 'https://xxx.png', name: 'xxx.png' }]}`。TS 类型：`(files: UploadFile \| UploadFile[]) => Promise` `interface RequestMethodResponse { status: 'success' \| 'fail'; error?: string; response: { url?: string; files?: UploadFile[]; [key: string]: any } }`。[详细类型定义](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/upload/type.ts) | N sizeLimit | Number / Object | - | 图片文件大小限制，默认单位 KB。可选单位有：`'B' \| 'KB' \| 'MB' \| 'GB'`。示例一：`1000`。示例二：`{ size: 2, unit: 'MB', message: '图片大小不超过 {sizeLimit} MB' }`。TS 类型：`number \| SizeLimitObj` `interface SizeLimitObj { size: number; unit: SizeUnit ; message?: string }` `type SizeUnitArray = ['B', 'KB', 'MB', 'GB']` `type SizeUnit = SizeUnitArray[number]`。[详细类型定义](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/upload/type.ts) | N -useMockProgress | Boolean | true | 是否在请求时间超过 300ms 后显示模拟进度。上传进度有模拟进度和真实进度两种。一般大小的文件上传，真实的上传进度只有 0 和 100，不利于交互呈现，因此组件内置模拟上传进度。真实上传进度一般用于大文件上传。 | N +useMockProgress | Boolean | true | 是否在请求时间超过 300ms 后显示模拟进度。上传进度有模拟进度和真实进度两种。一般大小的文件上传，真实的上传进度只有 0 和 100，不利于交互呈现，因此组件内置模拟上传进度。真实上传进度一般用于大文件上传 | N value | Array | [] | 已上传文件列表，同 `files`。TS 类型：`UploadFile`。支持语法糖 `v-model` 或 `v-model:value`。TS 类型：`Array` | N defaultValue | Array | [] | 已上传文件列表，同 `files`。TS 类型：`UploadFile`。非受控属性。TS 类型：`Array` | N withCredentials | Boolean | false | 上传请求时是否携带 cookie | N onChange | Function | | TS 类型：`(value: Array, context: UploadChangeContext) => void`
已上传文件列表发生变化时触发，`trigger` 表示触发本次的来源。[详细类型定义](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/upload/type.ts)。
`interface UploadChangeContext { e?: MouseEvent \| ProgressEvent; response?: any; trigger: UploadChangeTrigger; index?: number; file?: UploadFile; files?: UploadFile[] }`

`type UploadChangeTrigger = 'add' \| 'remove' \| 'abort' \| 'progress-success' \| 'progress' \| 'progress-fail'`
| N +onClickUpload | Function | | TS 类型：`(context: { e: MouseEvent }) => void`
点击上传区域时触发 | N onFail | Function | | TS 类型：`(options: UploadFailContext) => void`
上传失败后触发。`response` 指接口响应结果，`response.error` 会作为错误文本提醒。如果希望判定为上传失败，但接口响应数据不包含 `error` 字段，可以使用 `formatResponse` 格式化 `response` 数据结构。如果是多文件多请求上传场景，请到事件 `onOneFileFail` 中查看 `response`。[详细类型定义](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/upload/type.ts)。
`interface UploadFailContext { e?: ProgressEvent; failedFiles: UploadFile[]; currentFiles: UploadFile[]; response?: any; file: UploadFile; XMLHttpRequest?: XMLHttpRequest}`
| N onPreview | Function | | TS 类型：`(options: { file: UploadFile; index: number; e: MouseEvent }) => void`
点击图片预览时触发，文件没有预览 | N onProgress | Function | | TS 类型：`(options: ProgressContext) => void`
上传进度变化时触发，真实进度和模拟进度都会触发。
⚠️ 原始上传请求，小文件的上传进度只有 0 和 100，故而不会触发 `progress` 事件；只有大文件才有真实的中间进度。如果你希望很小的文件也显示上传进度，保证 `useMockProgress=true` 的情况下，设置 `mockProgressDuration` 为更小的值。
参数 `options.type=real` 表示真实上传进度，`options.type=mock` 表示模拟上传进度。[详细类型定义](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/upload/type.ts)。
`interface ProgressContext { e?: ProgressEvent; file?: UploadFile; currentFiles: UploadFile[]; percent: number; type: UploadProgressType; XMLHttpRequest?: XMLHttpRequest }`

`type UploadProgressType = 'real' \| 'mock'`
| N @@ -38,13 +40,13 @@ onRemove | Function | | TS 类型：`(context: UploadRemoveContext) => void`
void`
选择文件或图片之后，上传之前，触发该事件。[详细类型定义](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/upload/type.ts)。
`interface UploadSelectChangeContext { currentSelectedFiles: UploadFile[] }`
| N onSuccess | Function | | TS 类型：`(context: SuccessContext) => void`
上传成功后触发。
`context.currentFiles` 表示当次请求上传的文件（无论成功或失败），`context.fileList` 表示上传成功后的文件，`context.response` 表示上传请求的返回数据。
`context.results` 表示单次选择全部文件上传成功后的响应结果，可以在这个字段存在时提醒用户上传成功或失败。
。[详细类型定义](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/upload/type.ts)。
`interface SuccessContext { e?: ProgressEvent; file?: UploadFile; fileList?: UploadFile[]; currentFiles?: UploadFile[]; response?: any; results?: SuccessContext[]; XMLHttpRequest?: XMLHttpRequest }`
| N onValidate | Function | | TS 类型：`(context: { type: UploadValidateType, files: UploadFile[] }) => void`
文件上传校验结束事件，文件数量超出、文件大小超出限制、文件同名、`beforeAllFilesUpload` 返回值为假、`beforeUpload` 返回值为假等场景会触发。
注意：如果设置允许上传同名文件，即 `allowUploadDuplicateFile=true`，则不会因为文件重名触发该事件。
结合 `status` 和 `tips` 可以在组件中呈现不同类型的错误（或告警）提示。[详细类型定义](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/upload/type.ts)。
`type UploadValidateType = 'FILE_OVER_SIZE_LIMIT' \| 'FILES_OVER_LENGTH_LIMIT' \| 'FILTER_FILE_SAME_NAME' \| 'BEFORE_ALL_FILES_UPLOAD' \| 'CUSTOM_BEFORE_UPLOAD'`
| N -onClickUpload | Function | - | 点击上传区域时触发。TS 类型：`(context: { e: MouseEvent })` | N ### Upload Events 名称 | 参数 | 描述 -- | -- | -- change | `(value: Array, context: UploadChangeContext)` | 已上传文件列表发生变化时触发，`trigger` 表示触发本次的来源。[详细类型定义](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/upload/type.ts)。
`interface UploadChangeContext { e?: MouseEvent \| ProgressEvent; response?: any; trigger: UploadChangeTrigger; index?: number; file?: UploadFile; files?: UploadFile[] }`

`type UploadChangeTrigger = 'add' \| 'remove' \| 'abort' \| 'progress-success' \| 'progress' \| 'progress-fail'`
+click-upload | `(context: { e: MouseEvent })` | 点击上传区域时触发 fail | `(options: UploadFailContext)` | 上传失败后触发。`response` 指接口响应结果，`response.error` 会作为错误文本提醒。如果希望判定为上传失败，但接口响应数据不包含 `error` 字段，可以使用 `formatResponse` 格式化 `response` 数据结构。如果是多文件多请求上传场景，请到事件 `onOneFileFail` 中查看 `response`。[详细类型定义](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/upload/type.ts)。
`interface UploadFailContext { e?: ProgressEvent; failedFiles: UploadFile[]; currentFiles: UploadFile[]; response?: any; file: UploadFile; XMLHttpRequest?: XMLHttpRequest}`
preview | `(options: { file: UploadFile; index: number; e: MouseEvent })` | 点击图片预览时触发，文件没有预览 progress | `(options: ProgressContext)` | 上传进度变化时触发，真实进度和模拟进度都会触发。
⚠️ 原始上传请求，小文件的上传进度只有 0 和 100，故而不会触发 `progress` 事件；只有大文件才有真实的中间进度。如果你希望很小的文件也显示上传进度，保证 `useMockProgress=true` 的情况下，设置 `mockProgressDuration` 为更小的值。
参数 `options.type=real` 表示真实上传进度，`options.type=mock` 表示模拟上传进度。[详细类型定义](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/upload/type.ts)。
`interface ProgressContext { e?: ProgressEvent; file?: UploadFile; currentFiles: UploadFile[]; percent: number; type: UploadProgressType; XMLHttpRequest?: XMLHttpRequest }`

`type UploadProgressType = 'real' \| 'mock'`
@@ -52,11 +54,10 @@ remove | `(context: UploadRemoveContext)` | 移除文件时触发。[详细类 select-change | `(files: File[], context: UploadSelectChangeContext)` | 选择文件或图片之后，上传之前，触发该事件。[详细类型定义](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/upload/type.ts)。
`interface UploadSelectChangeContext { currentSelectedFiles: UploadFile[] }`
success | `(context: SuccessContext)` | 上传成功后触发。
`context.currentFiles` 表示当次请求上传的文件（无论成功或失败），`context.fileList` 表示上传成功后的文件，`context.response` 表示上传请求的返回数据。
`context.results` 表示单次选择全部文件上传成功后的响应结果，可以在这个字段存在时提醒用户上传成功或失败。
。[详细类型定义](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/upload/type.ts)。
`interface SuccessContext { e?: ProgressEvent; file?: UploadFile; fileList?: UploadFile[]; currentFiles?: UploadFile[]; response?: any; results?: SuccessContext[]; XMLHttpRequest?: XMLHttpRequest }`
validate | `(context: { type: UploadValidateType, files: UploadFile[] })` | 文件上传校验结束事件，文件数量超出、文件大小超出限制、文件同名、`beforeAllFilesUpload` 返回值为假、`beforeUpload` 返回值为假等场景会触发。
注意：如果设置允许上传同名文件，即 `allowUploadDuplicateFile=true`，则不会因为文件重名触发该事件。
结合 `status` 和 `tips` 可以在组件中呈现不同类型的错误（或告警）提示。[详细类型定义](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/upload/type.ts)。
`type UploadValidateType = 'FILE_OVER_SIZE_LIMIT' \| 'FILES_OVER_LENGTH_LIMIT' \| 'FILTER_FILE_SAME_NAME' \| 'BEFORE_ALL_FILES_UPLOAD' \| 'CUSTOM_BEFORE_UPLOAD'`
-clickUpload | `(context: { e: MouseEvent })` | 点击上传区域时触发。 ### UploadFile -名称 | 类型 | 默认值 | 说明 | 必传 +名称 | 类型 | 默认值 | 描述 | 必传 -- | -- | -- | -- | -- lastModified | Number | - | 上一次变更的时间 | N name | String | - | 文件名称 | N @@ -70,8 +71,8 @@ uploadTime | String | - | 上传时间 | N url | String | - | 文件上传成功后的下载/访问地址 | N `PlainObject` | \- | - | `PlainObject` 不是 UploadFile 中的属性，而表示 UploadFile 本身支持添加任意属性，`type PlainObject = {[key: string]: any}`' | N - ### CSS Variables + 组件提供了下列 CSS 变量，可用于自定义样式。 名称 | 默认值 | 描述 -- | -- | -- @@ -82,4 +83,4 @@ url | String | - | 文件上传成功后的下载/访问地址 | N --td-upload-grid-columns | 4 | - --td-upload-height | 80px | - --td-upload-radius | @radius-default | - ---td-upload-width | 80px | - +--td-upload-width | 80px | - \ No newline at end of file diff --git a/src/upload/upload.tsx b/src/upload/upload.tsx index 0bf2150d4..cc2fa1adc 100644 --- a/src/upload/upload.tsx +++ b/src/upload/upload.tsx @@ -183,6 +183,7 @@ export default defineComponent({ type="file" multiple={this.$props.multiple} hidden + capture={this.$props.capture as unknown as boolean} accept={this.$props.accept} onChange={this.onNormalFileChange} />