上传 Upload

合成进化

基础使用

action 指定上传地址，也可以使用 customRequest 完全接管请求过程。文件列表由 UploadFileList 渲染，展示每个文件的名称、进度和操作入口。

隐藏源代码

图片模式

把 mode 设为 'image' 时改由 UploadImage 渲染卡片网格：图片显示缩略图并支持点击预览，其它文件显示类型图标。thumbnailType 决定缩略图的生成方式，createThumbnailUrl 可以完全自定义缩略图地址。

隐藏源代码

拖拽上传

设置 draggable 后，内置的上传按钮会替换成 UploadDragger：整个像素虚线区域都可以接收拖入的文件，点击它同样会打开文件选择框，拖入的文件与选择框选中的文件走同一套流程。需要自己决定它摆放的位置时，把 UploadDragger 放进 trigger 插槽即可。

Click or drag files here to upload

隐藏源代码

禁用

disabled 设为 true 后，Upload 会忽略选取、拖入以及列表内的各项操作，内置按钮、UploadDragger 与 UploadFileList / UploadImage 的操作入口都会呈现禁用样式。

pixelium-logo.png
uploading.svg
pending.doc
error.doc

Click or drag files here to upload

隐藏源代码

手动上传与中断

autoUpload 设为 false 时文件先停留在待上传状态，再通过 Upload 暴露的 submit 方法开始上传，失败的文件可以用 retry 重试。abort 会把进行中和排队中的文件都标记为失败并保留在列表中，同时触发 abort 事件而不触发 error 事件；abortable 设为 false 时 Upload 会忽略中断调用，UploadFileList 与 UploadImage 也会隐藏中断入口。

隐藏源代码

选取限制

accept 限定可选的文件类型，支持扩展名、MIME 类型，以及 audio/*、image/*、video/* 三种通配；multiple 控制一次能否选取多个文件。beforeUpload 事件可以进一步校验文件，处理函数返回 false 时该文件不会进入列表。

隐藏源代码

并发

concurrency 限制同时进行的上传数量：一次选取多个文件时，超出的文件会先进入排队，处于 queueing 状态且进度恒为零，等前面的上传结束后依次开始。

隐藏源代码

下载

文件带有 url 时，UploadFileList 会把文件名渲染成下载链接，UploadImage 会显示下载入口；也可以用 customDownload 接管下载。

隐藏源代码

自定义文件列表

fileList 与 defaultFileList 分别用于受控和非受控地维护文件列表，需要完全自定义时可以用 file-list 插槽替换掉整个列表区域。

隐藏源代码

手动组合

上传的三个子组件都可以单独摆放：UploadFileList 与 UploadImage 放进 file-list 插槽，UploadDragger 放进 trigger 插槽，它们仍然通过 Upload 提供的上下文共享文件列表与各项操作。

Click or drag files here to upload

隐藏源代码

API

UploadProps

属性	类型	可选	默认值	描述	版本
accept	`string[]`	是		限定可选的文件类型。	0.2.1
size	`'small' \| 'medium' \| 'large'`	是	`'medium'`	Upload 的尺寸。	0.2.1
mode	`'file' \| 'image'`	是	`'file'`	文件列表的展示模式。	0.2.1
thumbnailType	`'objectURL' \| 'dataURL'`	是	`'objectURL'`	缩略图的生成方式。	0.2.1
createThumbnailUrl	`CreateThumbnailUrl`	是		自定义缩略图地址。	0.2.1
multiple	`boolean`	是	`true`	是否允许一次选取多个文件。	0.2.1
draggable	`boolean`	是	`false`	是否用 UploadDragger 替换内置的上传按钮。	0.2.1
disabled	`boolean`	是	`false`	是否禁用 Upload。	0.2.1
abortable	`boolean`	是	`true`	是否允许中断进行中和排队中的上传。	0.2.1
autoUpload	`boolean`	是	`true`	选取文件后是否自动开始上传。	0.2.1
concurrency	`number`	是		同时进行的上传数量上限，未设置或不大于 0 时不限制。	0.2.1
action	`string`	是		上传请求的地址。	0.2.1
method	`string`	是	`'post'`	上传请求使用的方法。	0.2.1
name	`string`	是	`'file'`	上传文件在请求中的字段名。	0.2.1
data	`UploadData`	是		附加在上传请求中的数据。	0.2.1
headers	`UploadHeaders`	是		上传请求的请求头。	0.2.1
withCredentials	`boolean`	是	`false`	跨域上传时是否携带凭据。	0.2.1
responseType	`XMLHttpRequestResponseType`	是	`'text'`	上传请求期望的响应类型。	0.2.1
isErrorState	`(xhr: XMLHttpRequest) => boolean`	是		判断上传请求是否失败。	0.2.1
customRequest	`CustomRequest`	是		自定义上传请求。	0.2.1
customDownload	`CustomDownload`	是		自定义下载行为。	0.2.1
fileList	`FileInfo[]`	是		受控的文件列表。	0.2.1
defaultFileList	`FileInfo[]`	是		非受控模式下默认的文件列表。	0.2.1
buttonProps	`ButtonProps & EmitEvent<ButtonEvents> & RestAttrs`	是		内置 Button 的属性。	0.2.1
uploadFileListProps	`UploadFileListProps`	是		传给 UploadFileList 的属性，尺寸沿用 Upload 的尺寸。	0.2.1
uploadImageProps	`UploadImageProps`	是		传给 UploadImage 的属性，尺寸沿用 Upload 的尺寸。	0.2.1
uploadDraggerProps	`UploadDraggerProps`	是		传给 UploadDragger 的属性。	0.2.1

UploadEvents

事件	参数	描述	版本
update:fileList	`fileList: FileInfo[]`	文件列表变化时触发。	0.2.1
beforeUpload	`params: { file: File; fileList: FileInfo[] }`	文件加入列表前触发，需返回 Promise<boolean \| void> \| boolean \| void 类型的数据判断是否成功，await 后值为 false 时该文件不会加入列表。	0.2.1
beforeRemove	`params: { file: FileInfo; fileList: FileInfo[] }`	文件移除前触发，需返回 Promise<boolean \| void> \| boolean \| void 类型的数据判断是否成功，await 后值为 false 时取消移除。	0.2.1
change	`fileList: FileInfo[], e: Event`	文件列表变化时触发（新增、移除或清空）。	0.2.1
progress	`item: FileInfo, percent: number, e: ProgressEvent`	上传进度变化时触发。	0.2.1
finish	`item: FileInfo, response: any, e: ProgressEvent`	文件上传完成时触发。	0.2.1
error	`item: FileInfo, error: any, e: ProgressEvent`	文件上传失败时触发。	0.2.1
abort	`item: FileInfo`	文件被中止时触发。	0.2.1
remove	`item: FileInfo, e: MouseEvent`	文件被移除时触发。	0.2.1

UploadSlots

插槽	参数	描述	版本
trigger	`open: () => void`	触发选取文件的区域。	0.2.1
file-list	`fileList: FileInfo[], remove: (id: string) => void, abort: (id?: string) => void, submit: (fileId?: string) => void, retry: (fileId?: string) => void, download: (file: FileInfo) => void`	文件列表区域，作用域提供文件列表与各项操作，其中未指定文件的操作作用于全部对应文件。	0.2.1

UploadExpose

属性	类型	可选	描述	版本
open	`() => void`	否	打开文件选择框。	0.2.1
submit	`(fileId?: string) => void`	否	开始上传待上传的文件，未指定文件时处理全部待上传的文件。	0.2.1
retry	`(fileId?: string) => void`	否	重试上传失败的文件，未指定文件时处理全部上传失败的文件。	0.2.1
remove	`(id: string) => void`	否	从列表中移除文件。	0.2.1
abort	`(id?: string) => void`	否	中断进行中和排队中的上传，未指定文件时中断全部进行中和排队中的上传。	0.2.1
clear	`() => void`	否	清空文件列表。	0.2.1

UploadFileListProps

属性	类型	可选	默认值	描述	版本
size	`'small' \| 'medium' \| 'large'`	是	`'medium'`	UploadFileList 的尺寸，未设置时沿用 Upload 的尺寸。	0.2.1
abortable	`boolean`	是	`true`	是否允许中断进行中和排队中的上传，与 Upload 同时允许时才会展示中断入口。	0.2.1
previewable	`boolean`	是	`true`	是否允许点击缩略图进行预览。	0.2.1
showProgress	`boolean`	是	`true`	是否展示上传进度。	0.2.1

UploadImageProps

属性	类型	可选	默认值	描述	版本
size	`'small' \| 'medium' \| 'large'`	是	`'medium'`	UploadImage 的尺寸，未设置时沿用 Upload 的尺寸。	0.2.1
abortable	`boolean`	是	`true`	是否允许中断进行中和排队中的上传，与 Upload 同时允许时才会展示中断入口。	0.2.1
previewable	`boolean`	是	`true`	是否允许点击缩略图进行预览。	0.2.1
showProgress	`boolean`	是	`true`	是否展示上传进度。	0.2.1

UploadDraggerProps

属性	类型	可选	默认值	描述	版本
text	`string`	是		拖拽区域的提示文字。	0.2.1

UploadDraggerSlots

插槽	参数	描述	版本
default		拖拽区域的提示内容。	0.2.1
icon		拖拽区域的图标。	0.2.1

FileInfo

export interface FileInfo {
	id: string
	name: string
	type?: string
	file?: File
	state: 'pending' | 'queueing' | 'uploading' | 'finished' | 'error'
	progress: number
	url?: string
	thumbnailUrl?: string
	response?: any
}

UploadData

export type UploadData =
	| Record<string, string>
	| ((params: { file: FileInfo }) => Record<string, string>)

UploadHeaders

export type UploadHeaders =
	| Record<string, string>
	| ((params: { file: FileInfo }) => Record<string, string>)

UploadPatch

export type UploadPatch = {
	url?: string
	thumbnailUrl?: string
	response?: any
}

UploadCustomRequestOptions

export interface UploadCustomRequestOptions {
	file: FileInfo
	action?: string
	withCredentials?: boolean
	data?: UploadData
	headers?: UploadHeaders
	signal: AbortSignal
	setProgress: (e: { percent: number }) => void
	setFinish: (patch?: UploadPatch) => void
	setError: (patch?: UploadPatch) => void
}

CustomRequest

export type CustomRequest = (options: UploadCustomRequestOptions) => any

CustomDownload

export type CustomDownload = (params: { file: FileInfo }) => void

CreateThumbnailUrl

export type CreateThumbnailUrl = (params: {
	file: FileInfo
}) => string | undefined | Promise<string | undefined>

EmitEvent

export type EmitEvent<T extends Record<string, any>> = {
	[K in keyof T as `on${Capitalize<K & string>}`]?: (...args: T[K]) => void
}

RestAttrs

import type { StyleValue } from 'vue'

export type VueClassValue = string | Record<string, any> | VueClassValue[]
export type VueStyleValue = StyleValue

export type RestAttrs = {
	style?: VueStyleValue | null
	class?: VueClassValue | null
	[x: string]: any
}

上传 Upload ​

基础使用 ​

图片模式 ​

拖拽上传 ​

禁用 ​

手动上传与中断 ​

选取限制 ​

并发 ​

下载 ​

自定义文件列表 ​

手动组合 ​

API ​

UploadProps ​

UploadEvents ​

UploadSlots ​

UploadExpose ​

UploadFileListProps ​

UploadImageProps ​

UploadDraggerProps ​

UploadDraggerSlots ​

FileInfo ​

UploadData ​

UploadHeaders ​

UploadPatch ​

UploadCustomRequestOptions ​

CustomRequest ​

CustomDownload ​

CreateThumbnailUrl ​

EmitEvent ​

RestAttrs ​

上传 Upload

基础使用

图片模式

拖拽上传

禁用

手动上传与中断

选取限制

并发

下载

自定义文件列表

手动组合

API

UploadProps

UploadEvents

UploadSlots

UploadExpose

UploadFileListProps

UploadImageProps

UploadDraggerProps

UploadDraggerSlots

FileInfo

UploadData

UploadHeaders

UploadPatch

UploadCustomRequestOptions

CustomRequest

CustomDownload

CreateThumbnailUrl

EmitEvent

RestAttrs