# Uploader <small>上传</small> ## 示例 ### 文件上传 设置 [`type`](#props-type) 的值为 `file` 进入文件上传模式。 [[ demo src="/demo/uploader/file.vue" ]] ### 图片上传 设置 [`type`](#props-type) 的值为 `image` 进入图片上传模式。 [[ demo src="/demo/uploader/image.vue" ]] ### 媒体上传 设置 [`type`](#props-type) 的值为 `media` 进入媒体上传模式。 [[ demo src="/demo/uploader/media.vue" ]] ### 前端校验 图片格式、大小、数量校验以及使用 [`validator`](#props-validator) 自定义校验。 [[ demo src="/demo/uploader/validate.vue" ]] ### 自定义配置 使用 [`upload`](#props-upload) 自定义上传过程,使用 [`controls`](#props-controls) 配置浮层操作项。 [[ demo src="/demo/uploader/custom.vue" ]] ### 拖拽排序 设置 [`sortable`](#props-sortable) 属性来指定上传项目之间可以拖拽排序。 [[ demo src="/demo/uploader/sortable.vue" ]] ### 已上传项自定义操作 设置 [`controls`](#props-controls) 属性来指定悬浮到每个上传项时的操作选项。 [[ demo src="/demo/uploader/controls.vue" ]] ### 上传入口自定义操作 设置 [`entries`](#props-entries) 属性来指定悬浮到继续上传项目时的操作选项。 [[ demo src="/demo/uploader/entries.vue" ]] ## API ### 属性 | 属性 | 类型 | 默认值 | 描述 | | --- | --- | --- | --- | | ``ui`` | `string=` | - | [^ui] | | ``type`` | `string` | `'file'` | [^type] | | ``value`` | `Object | Array<Object>` | - | [^value] | | ``key-field`` | `string` | `'key'` | 用于指定文件对象的唯一 key,作为数据变化时正确处理文件列表顺序的依据。 | | ``name`` | `string` | `'file'` | 原生 `<input>` 元素的 `name`。 | | ``action`` | `string` | - | 上传地址。 | | ``headers`` | `Object` | `uploader.headers` | 需要加入 [HTTP 请求头](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers) 的内容。可进行[全局统一配置](#configs-uploader-headers)。 | | ``with-credentials`` | `boolean` | `true` | 同 `XMLHttpRequest` 的 [`withCredentials`](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/withCredentials) 属性。 | | ``request-mode`` | `string` | `uploader.requestMode` | [^request-mode] | | ``iframe-mode`` | `string` | `uploader.iframeMode` | [^iframe-mode] | | ``callback-namespace`` | `string` | `uploader.callbackNamespace` | 在 `request-mode` 的值为 `'iframe'` 并且 `iframe-mode` 的值为 `'callback'` 的模式下,指定回调函数的命名空间,放在 `window` 对象下。可进行[全局统一配置](#configs-uploader-callbackNamespace)。 | | ``data-type``| `string` | `'json'` | [^data-type] | | ``convert-response`` | `uploader.convertResponse` | - | [^convert-response] | | ``accept`` | `string` | - | 与原生 `<input>` 元素 的 [`accept`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/Input/file#%E9%99%90%E5%88%B6%E5%8F%AF%E6%8E%A5%E5%8F%97%E7%9A%84%E6%96%87%E4%BB%B6%E7%B1%BB%E5%9E%8B) 属性相同,在浏览器的文件类型筛选后再加一层校验。对于类似 `application/msword` 这样的 MIME type 与扩展名对不上的情形跳过校验。 | | ``max-count`` | `number` | - | 最大文件数量。 | | ``max-size`` | `number | string` | - | 单个文件的最大大小,如果是 `number`,单位是 `byte`;如果是 `string`,支持在数字后面添加单位,单位可以是 `b` / `kb` / `mb` / `gb` / `tb`。 | | ``validator`` | `function(Object): Object | Promise<Object>` | - | [^validator] | | ``payload`` | `Object` | - | 附带在上传请求中的额外参数。 | | ``autoupload`` | `boolean` | `true` | 指定是否在选完文件后立刻上传。 | | ``order`` | `string` | `'asc'` | [^order] | | ``picker-position`` | `string` | `'after'` | [^picker-position] | | ``upload`` | `function(Object, Object): function` | - | [^upload] | | ``controls`` | `function(Object, Array<Object>): Array<Object>` | - | [^controls] | | ``multiple`` | `boolean` | `false` | 上传多个文件,当 `max-count` 是 `1`,`multiple` 是 `true`,那么 `value` 也是数组。 | | ``entries`` | `function(Array<Object>): Array<Object>` | - | [^entries] | | ``after-pick`` | `function(Array<Object>): void` | - | 选择文件之后的回调。 | | ``sortable`` | `boolean` | `false` | 文件列表是否可以排序。 | | ``preview-options`` | `object` | `{wrap: true, indicator: 'number'}` | 传递给 [`Lightbox`](./lightbox) 的预览选项。 | ^^^ui 预设样式。 +++枚举值 | 值 | 描述 | | -- | -- | | `s` | 小尺寸样式。 | | `m` | 中尺寸样式。 | +++ ^^^ ^^^type 上传类型。 +++枚举值 | 值 | 描述 | | -- | -- | | `file` | 文件上传。 | | `image` | 图片上传。 | | `media` | 媒体上传(支持视频和图片)。 | | `video` | 视频上传。 | +++ ^^^ ^^^value 当 `multiple` 为 `true`,返回文件对象的数组。另外,当 `max-count` 被设置为大于 `1` 的值,则会视为开启了 `multiple`。 每个文件对象的类型为 `{name: string, src: string, ...}`,以及在 `convert-response` 中自定义添加的字段。 ^^^ ^^^request-mode 指定异步上传方式。可进行[全局统一配置](#configs-uploader-request-mode)。 +++枚举值 | 值 | 描述 | | -- | -- | | `xhr` | 通过 `XMLHttpRequest` 上传。 | | `iframe` | 通过 `<iframe>` 上传。 | | `custom` | 自定义上传过程,通过 prop `upload` 方法上传。 | +++ ^^^ ^^^iframe-mode 指定在 [`request-mode`](#props-request-mode) 的值为 `iframe` 的模式下,上传成功后的回调方式。可进行[全局统一配置](#configs-uploader-request-mode)。 +++枚举值 | 值 | 描述 | | -- | -- | | `postmessage` | 通过 `PostMessage` 回调。 | | `callback` | 通过调用 `window` 的 [`callback-namespace`](#props-callback-namespace) 里的回调函数回调。 | +++ ^^^ ^^^data-type 如果回调的值是文本, 指明文本的解析方式。如果回调的数据是 `Object`,则 `data-type` 可以为空。 +++枚举值 | 值 | 描述 | | -- | -- | | `json` | 回调的文本是 JSON。 | | `text` | 回调的文本是普通文本。 | +++ ^^^ ^^^convert-response 将回调数据转换成需要的格式的函数,使组件能够判断上传是否成功以便显示相应结果,参数是回调数据。返回结果的格式要求如下: +++字段详情 | 字段 | 类型 | 描述 | | -- | -- | -- | | `success` | `boolean` | 表示上传是否成功。 | | `name` | `string=` | 文件的名称。`success` 为 `true` 时必须。 | | `src` | `string=` | 文件的地址。`success` 为 `true` 时必须。 | | `message` | `string=` | 上传失败时的出错信息。`success` 为 `false` 时必须。 | 还可以给返回结果加上其它自定义的属性,这些自定义属性会被包含在 [`value`](#props-value) 以及 [`change`](#events-change)、[`success`](#events-success)、[`failure`](#events-failure)、[`remove`](#events-remove)、[`progress`](#events-progress) 事件的回调参数 `file` 中 。可进行[全局统一配置](#configs-uploader-convert-response)。 +++ ^^^ ^^^order 上传文件的显示顺序,按照开始上传的时间排序。 +++枚举值 | 值 | 描述 | | -- | -- | | `asc` | 升序排列。 | | `desc` | 降序排列。 | +++ ^^^ ^^^picker-position 图片上传模式下,上传按钮在图片队列中的位置。 +++枚举值 | 值 | 描述 | | -- | -- | | `before` | 上传按钮始终在队列最前面。 | | `after` | 上传按钮始终在队列最后面。 | +++ ^^^ ^^^validator 自定义校验逻辑,参数为原生 [`File`](https://developer.mozilla.org/zh-CN/docs/Web/API/File) 对象。返回结果的格式要求如下: +++字段详情 | 字段 | 类型 | 描述 | | -- | -- | -- | | `valid` | `boolean` | 是否通过校验。 | | `message` | `string=` | `valid` 为 `false` 时的错误提示信息。 | 支持异步校验,返回值可以是一个 resolve 上述返回结果的 `Promise`。 ^^^ ^^^upload 在 `request-mode` 的值是 `'custom'` 的情况下自定义上传过程,第一个参数为原生 [`File`](https://developer.mozilla.org/zh-CN/docs/Web/API/File) 对象,第二个参数为包含与上传过程相关的回调函数的对象,具体字段如下: +++字段详情 | 字段 | 类型 | 描述 | | -- | -- | -- | | `onload` | `function` | 上传完成的回调函数,参数内容与 [`convert-response`](#props-convert-response) 属性返回值相同。 | | `onprogress` | `function` | 上传进度发生变化的回调函数,参数为 `{ loaded: number, total: number }`,`loaded` 为已上传部分字节数,`total` 为文件总字节数。 | | `oncancel` | `function` | 自定义上传主动取消时对组件进行的回调,无参数。 | | `onerror` | `function` | 上传出错的回调函数,参数为 `{ message: string }`,`message` 为错误提示信息。 | 如果 `upload` 返回一个函数,该函数将在用户操作取消或上传组件销毁时被调用,用来中断自定义上传过程。 ^^^ ^^^controls 图片上传模式下,用来自定义配置图片遮罩浮层上的操作项,参数为 `(file: Object, defaultControls: Array<Object>)`,`file` 为文件相关信息,`defaultControls` 为包含默认的操作项的数组。可根据文件状态的不同,返回包含不同的操作项的数组。每个操作项的具体字段如下: +++字段详情 | 字段 | 类型 | 描述 | | -- | -- | -- | | `name` | `string` | 操作项的名称,点击该按钮后会抛出同名的事件,事件的回调参数为 `(file: Object, index: number)`, `file` 为触发事件的文件对象,`index` 为文件在列表中的序号。 | | `label` | `string` | 操作项的文字描述。 | | `icon` | `string` | 操作项使用的图标。 | | `disabled` | `boolean=` | 操作项是否被禁用。如果该字段为空,则该操作项的禁用状态跟随组件整体的禁用状态。 | ^^^ ^^^entries 控制每个上传文件的操作项,如删除,预览等,会传递默认的操作项数组作为参数,返回实际生效的操作项数组。操作项对象参考 [`controls`](#props-controls) 属性的字段详情。 ^^^ ### 插槽 | 名称 | 描述 | | -- | -- | | ``button-label`` | [^button-label] | | ``upload`` | 图片上传模式下,上传按钮的区域。 | | ``desc`` | 对文件数量、格式、大小等的提示内容。 | | ``file`` | [^file] | | ``file-before`` | 单个文件内容之前的区域。作用域参数与 [`file`](#slots-file) 插槽相同。 | | ``file-after`` | 单个文件内容之后的区域。作用域参数与 [`file`](#slots-file) 插槽相同。 | | ``uploading`` | 图片上传模式下,上传中的单个图片的区域。作用域参数与 [`file`](#slots-file) 插槽相同。 | | ``failure`` | 图片上传模式下,上传失败的单个图片的区域。作用域参数与 [`file`](#slots-file) 插槽相同。 | ^^^button-label 上传按钮里的内容。 默认内容:文件上传为提示选择文件,图片上传则为上传图片图标。 ^^^ ^^^file 单个文件的区域,用来定制文件内容。 +++作用域参数 | 名称 | 类型 | 描述 | | -- | -- | -- | | `name` | `string` | 文件的名称。 | | `src` | `string` | 文件的地址。 | | `status` | `string` | 文件的状态。`'success'` 表示上传成功;`'uploading'` 表示正在上传;`'failure'` 表示上传失败。 | | `index` | `number` | 文件在列表中的序号。 | +++ ^^^ ### 事件 | 名称 | 描述 | | -- | -- | | ``change`` | [^event-change] | | ``remove`` | [^event-remove] | | ``success`` | 上传成功时触发,回调参数与 [`remove`](#events-remove) 事件的回调参数相同。 | | ``failure`` | 上传失败时触发,回调参数与 [`remove`](#events-remove) 事件的回调参数相同。 | | ``invalid`` | [^event-invalid] | | ``statuschange`` | [^event-statuschange] | | ``progress`` | [^event-progress] | ^^^event-change 只在上传成功、删除文件时触发,回调参数为 `(value)`。 +++参数详情 | 名称 | 类型 | 描述 | | -- | -- | -- | | `value` | `Object | Array<Object>` | 组件的 `value` 的值。 | +++ ^^^ ^^^event-remove 删除文件时触发,回调参数为 `(file, index)`。 +++参数详情 | 名称 | 类型 | 描述 | | -- | -- | -- | | `file` | `Object` | 被删除的文件。 | | `index` | `number` | 被删除的文件的序号。 | `file` 字段详情 | 字段 | 类型 | 描述 | | -- | -- | -- | | `name` | `string` | 文件名称。 | | `src` | `string` | 文件地址。 | | `status` | `string` | 上传状态。`'success'` 表示上传成功;`'uploading'` 表示正在上传;`'failure'` 表示上传失败。 | 同时也包含在 [`convert-response`](#props-convert-response) 中添加的自定义属性。 +++ ^^^ ^^^event-invalid 文件校验失败时触发,回调参数为 `(validity: Object)`。 +++参数字段详情 | 名称 | 类型 | 描述 | | -- | -- | -- | | `file` | `Object` | 没有通过校验的文件信息,与 [`remove`](#events-remove) 事件的回调参数中的 `file` 相同。如果校验失败的原因是选择的文件数量超过最大数量 `max-count` 限制,则这个字段为空。 | | `errors` | `Array<Object>` | 包含该文件所有校验错误信息的数组,数组的每一项是包含校验失败信息的对象。 | +++ +++校验失败信息字段详情 | 名称 | 类型 | 描述 | | -- | -- | -- | | `type` | `string` | 校验失败的类型,类型枚举值可从 `Uploader.errors` 对象获取,如 `Uploader.errors.SIZE_INVALID`。 | | `value` | `number | string | Object` | 没有通过校验的值,根据 `type` 的不同有不同的类型。 | | `message` | `string` | 检验失败的提示信息。 | +++ +++校验失败类型与参数关系 | 类型 | 描述 | `value` 类型 | `value` 描述 | | -- | -- | -- | -- | | `TYPE_INVALID` | 文件类型校验失败。 | `string` | 文件名称。 | | `SIZE_INVALID` | 文件大小校验失败。 | `number` | 文件大小字节数。 | | `TOO_MANY_FILES` | 选择的文件数超过 `max-count` 限制。 | `number` | 已选择的文件数。 | | `CUSTOM_INVALID` | `validator` 自定义校验失败。 | `Object` | 文件对象,字段同 [`remove`](#events-remove) 事件回调参数。 | +++ ^^^ ^^^event-statuschange 在所有文件总的状态发生变化时触发,回调参数为组件整体的状态 `(status: string)`。 +++值详情 | 值 | 描述 | | -- | -- | | `empty` | 没有选择任何文件上传。 | | `uploading` | 有任一文件正在上传中。 | | `failure` | 有任一文件上传失败。 | | `success` | 所有文件上传成功。 | +++ ^^^ ^^^event-progress 在 `request-mode` 的值为 `'xhr'` 的情况下,在上传进度发生变化时触发,回调参数为 `(file, index, event)`。 +++参数详情 | 名称 | 类型 | 描述 | | -- | -- | -- | | `file` | `Object` | 与 [`remove`](#events-remove) 事件的回调参数中的 `file` 相同。 | | `index` | `number` | 正在上传的文件的序号。 | | `event` | [`Event`](https://developer.mozilla.org/zh-CN/docs/Web/Events/progress) | 上传进度原生事件。 | +++ ^^^ ### 全局配置 | 名称 | 类型 | 默认值 | 描述 | | -- | -- | -- | -- | | ``uploader.requestMode`` | `string` | `'xhr'` | 参见 [`request-mode`](#props-request-mode) 属性。 | | ``uploader.iframeMode`` | `string` | `'postmessage'` | 参见 [`iframe-mode`](#props-iframe-mode) 属性。 | | ``uploader.callbackNamespace`` | `string` | `'veuiUploadResult'` | 参见 [`callback-namespace`](#props-callback-namespace) 属性。 | | ``uploader.headers`` | `Object` | - | 参见 [`headers`](#props-headers) 属性。 | | ``uploader.convertResponse`` | `function(Object): Object` | - | 参见 [`convert-response`](#props-convert-response) 属性。 | | ``uploader.pickerPosition`` | `string` | `'after'` | 参见 [`picker-position`](#props-picker-position) 属性。 | ### 图标 | 名称 | 描述 | | -- | -- | | ``upload`` | 上传文件。 | | ``add-image`` | 上传图片。 | | ``clear`` | 删除。 | | ``success`` | 上传成功。 | | ``failure`` | 上传失败。 | | ``loading`` | 上传中。 | | ``file`` | 已上传文件。 | | ``alert`` | 校验失败警告。 | | ``preview`` | 预览图片。 |