feat(Uploader): add preview-cover slot (#6707)

* feat(Uploader): add preview-cover slot * docs: upd * fix: case name
2020-07-05 20:09:20 +08:00
parent 340a90feaa
commit 5793481ba4
8 changed files with 240 additions and 75 deletions
@@ -13,7 +13,7 @@ Vue.use(Uploader);

 ### 基础用法

-文件上传完毕后会触发`after-read`回调函数，获取到对应的`file`对象
+文件上传完毕后会触发 `after-read` 回调函数，获取到对应的 `file` 对象。

 ```html
 <van-uploader :after-read="afterRead" />
@@ -32,7 +32,7 @@ export default {

 ### 文件预览

-通过`v-model`可以绑定已经上传的文件列表，并展示文件列表的预览图
+通过`v-model`可以绑定已经上传的文件列表，并展示文件列表的预览图。

 ```html
 <van-uploader v-model="fileList" multiple />
@@ -53,17 +53,9 @@ export default {
 };
 ```

-### 禁用
-
-通过`disabled`属性禁用文件上传
-
-```html
-<van-uploader disabled />
-```
-
 ### 上传状态

-通过`status`属性可以标识上传状态，`uploading`表示上传中，`failed`表示上传失败，`done`表示上传完成（从 2.4.7 版本开始支持）
+通过 `status` 属性可以标识上传状态，`uploading` 表示上传中，`failed` 表示上传失败，`done` 表示上传完成。

 ```html
 <van-uploader v-model="fileList" :after-read="afterRead" />
@@ -103,7 +95,7 @@ export default {

 ### 限制上传数量

-通过`max-count`属性可以限制上传文件的数量，上传数量达到限制后，会自动隐藏上传区域
+通过 `max-count` 属性可以限制上传文件的数量，上传数量达到限制后，会自动隐藏上传区域。

 ```html
 <van-uploader v-model="fileList" multiple :max-count="2" />
@@ -121,22 +113,20 @@ export default {

 ### 限制上传大小

-通过`max-size`属性可以限制上传文件的大小，超过大小的文件会被自动过滤，这些文件信息可以通过`oversize`事件获取
+通过 `max-size` 属性可以限制上传文件的大小，超过大小的文件会被自动过滤，这些文件信息可以通过 `oversize` 事件获取。

 ```html
-<van-uploader
-  multiple
-  :max-count="5"
-  :max-size="3 * 1024 * 1024"
-  @oversize="onOversize"
-/>
+<van-uploader multiple :max-size="500 * 1024" @oversize="onOversize" />
 ```

 ```js
+import Toast from 'vant';
+
 export default {
  methods: {
    onOversize(file) {
      console.log(file);
+      Toast('文件大小不能超过 500kb');
    },
  },
 };
@@ -144,17 +134,43 @@ export default {

 ### 自定义上传样式

-通过插槽可以自定义上传区域的样式
+通过默认插槽可以自定义上传区域的样式。

 ```html
 <van-uploader>
-  <van-button icon="photo" type="primary">上传文件</van-button>
+  <van-button icon="plus" type="primary">上传文件</van-button>
 </van-uploader>
 ```

-### 上传前自定义处理
+### 自定义预览样式

-通过传入`beforeRead`函数可以在上传前进行校验，返回`true`表示校验通过，返回`false`表示校验失败。支持返回`Promise`对 file 对象进行自定义处理，例如压缩图片。
+通过 `preview-cover` 插槽可以自定义覆盖在预览区域上方的内容。
+
+```html
+<van-uploader v-model="fileList">
+  <template #preview-cover="{ file }">
+    <div class="preview-cover van-ellipsis">{{ file.name }}</div>
+  </template>
+</van-uploader>
+
+<style>
+  .preview-cover {
+    position: absolute;
+    box-sizing: border-box;
+    bottom: 0;
+    width: 100%;
+    padding: 4px;
+    color: #fff;
+    font-size: 12px;
+    text-align: center;
+    background: rgba(0, 0, 0, 0.3);
+  }
+</style>
+```
+
+### 上传前置处理
+
+通过传入 `beforeRead` 函数可以在上传前进行校验和处理，返回 `true` 表示校验通过，返回 `false` 表示校验失败。支持返回 `Promise` 对 file 对象进行自定义处理，例如压缩图片。

 ```html
 <van-uploader :before-read="beforeRead" />
@@ -191,12 +207,21 @@ export default {
 };
 ```

+### 禁用文件上传
+
+通过 `disabled` 属性禁用文件上传
+
+```html
+<van-uploader disabled />
+```
+
 ## API

 ### Props

 | 参数 | 说明 | 类型 | 默认值 |
 | --- | --- | --- | --- |
+| v-model (fileList) | 已上传的文件列表 | _FileListItem[]_ | - |
 | accept | 允许上传的文件类型，[详细说明](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/Input/file#%E9%99%90%E5%88%B6%E5%85%81%E8%AE%B8%E7%9A%84%E6%96%87%E4%BB%B6%E7%B1%BB%E5%9E%8B) | _string_ | `image/*` |
 | name `v2.0.3` | 标识符，可以在回调函数的第二项参数中获取 | _number \| string_ | - |
 | preview-size | 预览图和上传区域的尺寸，默认单位为`px` | _number \| string_ | `80px` |
@@ -207,13 +232,13 @@ export default {
 | deletable `v2.2.12` | 是否展示删除按钮 | _boolean_ | `true` |
 | show-upload `v2.5.6` | 是否展示上传区域 | _boolean_ | `true` |
 | lazy-load `v2.6.2` | 是否开启图片懒加载，须配合 [Lazyload](#/zh-CN/lazyload) 组件使用 | _boolean_ | `false` |
-| capture | 图片选取模式，可选值为`camera`(直接调起摄像头) | _string_ | - |
+| capture | 图片选取模式，可选值为 `camera` (直接调起摄像头) | _string_ | - |
 | after-read | 文件读取完成后的回调函数 | _Function_ | - |
-| before-read | 文件读取前的回调函数，返回`false`可终止文件读取，<br>支持返回`Promise` | _Function_ | - |
-| before-delete | 文件删除前的回调函数，返回`false`可终止文件读取，<br>支持返回`Promise` | _Function_ | - |
-| max-size | 文件大小限制，单位为`byte` | _number \| string_ | - |
+| before-read | 文件读取前的回调函数，返回 `false` 可终止文件读取，<br>支持返回`Promise` | _Function_ | - |
+| before-delete | 文件删除前的回调函数，返回 `false` 可终止文件读取，<br>支持返回`Promise` | _Function_ | - |
+| max-size | 文件大小限制，单位为 `byte` | _number \| string_ | - |
 | max-count | 文件上传数量限制 | _number \| string_ | - |
-| result-type `v2.2.7` | 文件读取结果类型，可选值为`file` `text` | _string_ | `dataUrl` |
+| result-type `v2.2.7` | 文件读取结果类型，可选值为 `file` `text` | _string_ | `dataUrl` |
 | upload-text | 上传区域文字提示 | _string_ | - |
 | image-fit `v2.1.5` | 预览图裁剪模式，可选值见 [Image](#/zh-CN/image) 组件 | _string_ | `cover` |
 | upload-icon `v2.5.4` | 上传区域[图标名称](#/zh-CN/icon)或图片链接 | _string_ | `photograph` |
@@ -229,9 +254,10 @@ export default {

 ### Slots

-| 名称    | 说明           |
-| ------- | -------------- |
-| default | 自定义上传区域 |
+| 名称 | 说明 | SlotProps |
+| --- | --- | --- |
+| default | 自定义上传区域 | - |
+| preview-cover `v2.9.1` | 自定义覆盖在预览区域上方的内容 | `item: FileListItem` |

 ### 回调参数

@@ -239,7 +265,7 @@ before-read、after-read、before-delete 执行时会传递以下回调参数：

 | 参数名 | 说明                              | 类型     |
 | ------ | --------------------------------- | -------- |
-| file   | 文件解析后的 file 对象            | _object_ |
+| file   | file 对象                         | _object_ |
 | detail | 额外信息，包含 name 和 index 字段 | _object_ |

 ### ResultType  可选值