docs_vue2/one/docs/components/uploader.md
2020-08-13 11:47:56 +08:00

313 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Uploader <small>上传</small>
## 示例
### 文件上传
设置 `type` 的值为 `file` 进入文件上传模式。
[[ demo src="/demo/uploader/file.vue" ]]
### 图片上传
设置 `type` 的值为 `image` 进入图片上传模式。
[[ demo src="/demo/uploader/image.vue" ]]
### 前端校验
图片格式、大小、数量校验以及使用 `validator` 自定义校验。
[[ demo src="/demo/uploader/validate.vue" ]]
### 自定义配置
使用 `upload` 自定义上传过程,使用 `controls` 配置浮层操作项。
[[ demo src="/demo/uploader/custom.vue" ]]
## API
### 属性
| 属性 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `type` | `string` | `'file'` | [^type] |
| `value` | `Object|Array<Object>` | - | [^value] |
| `name` | `string` | `'file'` | 原生 `<input>` 元素的 `name`。 |
| `action` | `string` | - | 上传地址。 |
| `headers` | `Object` | `uploader.headers` | 需要加入 [HTTP 请求头](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers) 的内容。可进行全局统一配置。 |
| `with-credentials` | `boolean` | `true` | 同 `XMLHttpRequest``with-credentials` 属性。 |
| `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` 对象下。可进行全局统一配置。 |
| `data-type`| `string` | `'json'` | [^data-type] |
| `convert-response` | `uploader.convertResponse` | - | [^convert-response] |
| `accept` | `string` | - | 与原生 `<input>` 元素 的 `accept` 相同,在浏览器的文件类型筛选后再加一层校验。对于类似 `application/msword` 这样的 MIME type 与扩展名对不上的情形跳过校验。 |
| `extensions` | `Array<string>` | `['jpg', 'jpeg', 'gif', 'png', 'bmp', 'tif', 'tiff', 'webp', 'apng', 'svg']` | 如果 `accept` 的值是类似 `'image/*'` 这样的形式,可以指定能通过校验的所有的扩展名。 |
| `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] |
^^^type
上传类型。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `file` | 文件上传。 |
| `image` | 图片上传。 |
+++
^^^
^^^value
+++字段详情
| `max-count` | 字段类型 |
| -- | -- |
| `1` | `Object` |
| 大于 `1``null` | `Array<Object>` |
每个文件对象的类型为 `{name: string, src: string, ...}`,以及在 `convert-response` 中自定义添加的字段。
+++
^^^
^^^request-mode
指定异步上传方式。可进行全局统一配置。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `xhr` | 通过 `XMLHttpRequest` 上传。 |
| `iframe` | 通过 `<iframe>` 上传。 |
| `custom` | 自定义上传过程,通过 prop `upload` 方法上传。 |
+++
^^^
^^^iframe-mode
指定在 `request-mode` 的值为 `iframe` 的模式下,上传成功后的回调方式。可进行全局统一配置。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `postmessage` | 通过 `PostMessage` 回调。 |
| `callback` | 通过调用 `window``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` 以及 `change`、`success`、`failure`、`remove`、`progress` 事件的回调参数 `file` 中 。可进行全局统一配置。
+++
^^^
^^^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` prop 返回值相同。 |
| `onprogress` | `function` | 上传进度发生变化的回调函数,参数为 `{ loaded: number, total: number }``loaded` 为已上传部分大小,`total` 为文件总大小。 |
| `onerror` | `function` | 上传出错的回调函数,参数为 `{ message: string }``message` 为错误提示信息。 |
该方法如果返回一个函数,该函数将在用户操作取消或上传组件销毁时被调用,用来中断自定义上传过程。
^^^
^^^controls
图片上传模式下,自定义配置图片遮罩浮层上的操作项,参数为 `(file: Object, defaultControls: Array<Object>)``file` 为文件相关信息,`defaultControls` 为包含默认的操作项的数组。该方法可根据文件状态的不同,返回包含不同的操作项的数组。每个操作项的具体字段如下:
+++字段详情
| 字段 | 类型 | 描述 |
| -- | -- | -- |
| `name` | `string` | 操作项的名称,点击该按钮后会抛出同名的事件,事件的回调参数为 `(file: Object, index: number)` `file` 为触发事件的文件对象,`index` 为文件在列表中的序号。 |
| `icon` | `string` | 操作项使用的图标。 |
| `disabled` | `boolean=` | 操作项是否被禁用。如果该字段为空,则该操作项的禁用状态跟随组件整体的禁用状态。 |
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `button-label` | [^button-label] |
| `upload` | 图片上传模式下,上传按钮的区域。 |
| `desc` | 对文件数量、格式、大小等的提示内容。 |
| `file` | [^file] |
| `file-before` | 单个文件内容之前的区域。作用域参数与 `file` 作用域插槽相同。 |
| `file-after` | 单个文件内容之后的区域。作用域参数与 `file` 作用域插槽相同。 |
| `uploading` | 图片上传模式下,上传中的单个图片的区域。作用域参数与 `file` 作用域插槽相同。 |
| `failure` | 图片上传模式下,上传失败的单个图片的区域。作用域参数与 `file` 作用域插槽相同。 |
^^^button-label
上传文件的按钮里的内容。
默认内容:提示选择文件。
^^^
^^^file
单个文件的区域,用来定制文件内容。
+++作用域参数
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `name` | `string` | 文件的名称。 |
| `src` | `string` | 文件的地址。 |
| `status` | `string` | 文件的状态。`'success'` 表示上传成功;`'uploading'` 表示正在上传;`'failure'` 表示上传失败。 |
| `index` | `number` | 文件在列表中的序号。 |
+++
^^^
### 事件
| 名称 | 描述 |
| -- | -- |
| `change` | [^event-change] |
| `remove` | [^event-remove] |
| `success` | 上传成功时触发,回调参数与 `remove` 事件的回调参数相同。 |
| `failure` | 上传失败时触发,回调参数与 `remove` 事件的回调参数相同。 |
| `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` 中添加的自定义属性。
+++
^^^
^^^event-statuschange
在所有文件总的状态发生变化时触发,回调参数为组件整体的状态 `(status: string)`
+++值详情
| 值 | 描述 |
| -- | -- |
| `empty` | 没有选择任何文件上传。 |
| `uploading` | 有任一文件正在上传中。 |
| `failure` | 有任一文件上传失败。 |
| `success` | 所有文件上传成功。 |
+++
^^^
^^^event-progress
`request-mode` 的值为 `'xhr'` 的情况下,在上传进度发生变化时触发,回调参数为 `(file, index, event)`
+++参数详情
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `file` | `Object` | 与 `remove` 事件的回调参数中的 `file` 相同。 |
| `index` | `number` | 正在上传的文件的序号。 |
| `event` | [`Event`](https://developer.mozilla.org/zh-CN/docs/Web/Events/progress) | 上传进度原生事件。 |
+++
^^^
### 全局配置
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `uploader.requestMode` | `string` | `'xhr'` | 参见 [`request-mode`](#props) 属性。 |
| `uploader.iframeMode` | `string` | `'postmessage'` | 参见 [`iframe-mode`](#props) 属性。 |
| `uploader.callbackNamespace` | `string` | `'veuiUploadResult'` | 参见 [`callback-namespace`](#props) 属性。 |
| `uploader.headers` | `Object` | - | 参见 [`headers`](#props) 属性。 |
| `uploader.convertResponse` | `function(Object): Object` | - | 参见 [`convert-response`](#props) 属性。 |
| `uploader.pickerPosition` | `string` | `'after'` | 参见 [`picker-position`](#props) 属性。 |
### 图标
| 名称 | 描述 |
| -- | -- |
| `upload` | 上传文件。 |
| `add-image` | 上传图片。 |
| `clear` | 删除。 |
| `success` | 上传成功。 |
| `failure` | 上传失败。 |
| `loading` | 上传中。 |
| `file` | 已上传文件。 |
| `alert` | 校验失败警告。 |
| `preview` | 预览图片。 |