PIUI 高质量开源组件库

# UploadImg 图片上传

常用于表单，头像等需要上传图片的场景

重要

  1. 当配置了action的情况，组件使用 uni.uploadFile (opens new window)] 来进行文件上传，headers可以在图片上传时候携带额外的信息，比如token 等授权信息。

  2. parseResultFn 为了兼容不同的接口方案，需要提供一个解析结果的函数，该函数接受一个 result 参数（该参数是调用服务器上传接口返回的对象），函数需要返回v-model数组中的一项，参考：parseResultFn默认配置

  3. 服务器鉴权，这种情况需要在接口中处理，比如token失效，token刷新，这时候应该使用 onProgress 参数自行处理图片上传，以下例子使用了 luch-request (opens new window) 进行自定义上传

  • 通常我们会在 全局配置 中重写 onProgress 和 parseResultFn，方便使用
import Vue from 'vue';
import piui from "sadais-piui";
import request from "luch-request";

// 使用 request 库进行上传，在 interceptors 中处理授权相关逻辑

Vue.use(piui, {
  uploadImg: {
    async onProgress(params) {
      const result = await request.upload('/api/canteen/file/uploadfile', params)
      return result.data
    },
    parseResultFn(result) {
      return result.data.url
    }
  }
})
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 平台差异说明

App H5 微信小程序 支付宝小程序 百度小程序 字节小程序 QQ小程序
√ √ √ √ √ √ √

# 示例

# 基本用法

v-model 绑定上传图片的数组

<template>
  <pi-upload-img
    v-model="baseUsed"
    size="120"
    max-count="3"
    action="https://api-canteen.sadaiscloud.com/api/canteen/file/uploadfile"
  />
</template>

<script>
export default {
  data() {
    return {
      baseUsed: []
    }
  }
}
</script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# 对象数组格式

v-model 绑定上传图片的数组 imgField: '', 图片img字段，默认为''

提示

  1. 当imgField为空的时候, v-model/value应该传入字符串数组结构
  2. 当imgField不为空的时候, v-model/value应该传入对象数组数组结构
  3. 当imgField不为空的时候, 应自定义设置parseResultFn
<template>
  <pi-upload-img
    v-model="objectValue"
    img-field="url"
    size="120"
    max-count="3"
    action="https://api-canteen.sadaiscloud.com/api/canteen/file/uploadfile"
    :parse-result-fn="parseResultFn"
  />
</template>

<script>
export default {
  data() {
    return {
      objectValue: [
        {
          url: 'https://m.sadais.com/img/file/20210816/7eda5c19-6da8-4c99-965e-7403f6ee8169.png'
        }
      ]
    }
  },
  methods: {
    parseResultFn(result) {
      return JSON.parse(result.data)?.data
    }
  }
}
</script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# 显示上传文字

可通过uploadText设置上传文字

<template>
  <pi-upload-img
    v-model="uploadText"
    size="120"
    max-count="3"
    upload-text="图片上传"
    action="https://api-canteen.sadaiscloud.com/api/canteen/file/uploadfile"
  />
</template>

<script>
export default {
  data() {
    return {
      uploadText: []
    }
  }
}
</script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# 上传头像

  1. 当max-count = 1 的时候，v-model可传入字符串
  2. 可通过itemStyle 和 uploadBtnStyle 改变上传按钮以及图片样式
<template>
  <pi-upload-img
    v-model="avatar"
    size="120"
    max-count="1"
    action="https://api-canteen.sadaiscloud.com/api/canteen/file/uploadfile"
    :item-style="{
      borderRadius: '50%'
    }"
    :upload-btn-style="{
      borderRadius: '50%'
    }"
  />
</template>

<script>
export default {
  data() {
    return {
      avatar: ''
    }
  }
}
</script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

# 自定义上传按钮样式

可通过uploadIcon改变上传icon配置

<template>
  <pi-upload-img
    v-model="uploadIcon"
    size="120"
    max-count="3"
    action="https://api-canteen.sadaiscloud.com/api/canteen/file/uploadfile"
    :upload-icon="{
      name: 'camerafill',
      size: '42'
    }"
  />
</template>

<script>
export default {
  data() {
    return {
      uploadIcon: []
    }
  }
}
</script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

# 自定义上传按钮样式

可通过uploadBtn slot 自定义上传按钮背景

<template>
  <pi-upload-img
    v-model="uploadBtnSlot"
    size="120"
    max-count="1"
    action="https://api-canteen.sadaiscloud.com/api/canteen/file/uploadfile"
    :upload-btn-style="{
      padding: 0,
      padding: '24rpx',
      borderRadius: '50%'
    }"
  >
    <pi-img
      slot="uploadBtn"
      src="https://sadais-oss.oss-cn-hangzhou.aliyuncs.com/piui/%E5%95%86%E5%8A%A1%E5%A4%B4%E5%83%8F%EF%BC%8C%E7%94%B7%E5%A3%AB.png"
    />
  </pi-upload-img>
</template>

<script>
export default {
  data() {
    return {
      uploadBtnSlot: []
    }
  }
}
</script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

# Props

Name Description Type Required Default
value 初始值 Array false []
customStyle 自定义样式 Object false -
customClass 自定义样式类 String false -
itemStyle 上传按钮样式 Object false -
uploadBtnStyle 上传按钮样式 Object false -
imageMode 显示的图片模式 String false -
action 上传接口地址，字符串形式（默认值：''） String false -
headers 请求头，对象形式 Object false {}
formData 上传表单额外数据，对象形式 Object false {}
name 上传的文件字段名 String false -
size 上传区域尺寸（半径） String / Number false -
previewFullImage 是否在点击预览图后展示全屏图片预览 Boolean false -
deletable 是否可以删除上传的文件 Boolean false -
disabled 是否禁用上传 Boolean false -
maxCount 上传文件的最大数量 String / Number false -
uploadText 上传区域文字提示 String false -
uploadIcon 上传区域图标 Object false uploadIcon配置项
chooseImageOpts 调用 uniapp.chooseImageOpts 进行图片选择 Object false chooseImageOpts配置项
crop v1.2.0 当maxCount设置为1的时候，可开启裁剪 Boolean false false
cropOption v1.2.0 裁剪参数参考 pi-img-cropper 配置项 Object false false
parseResultFn 上传成功解析对象方法 Function false parseResultFn默认配置
beforeUpload 上传文件之前的钩子，参数为上传的文件，若返回 false 或者返回 Promise 且被 reject，则停止上传。 Function(filePath) false -
onProgress v1.2.0 文件上传时的钩子 Function(params:{url, filePath, name, formData, header}) false -
beforeRemove 删除之前的钩子 Function(index) false -

# UploadIcon Props

提示

以下属性覆盖pi-icon配置，其余属性参考icon配置项

名称 描述 类型 必选 默认值
name 图标名称或图片链接 String false 'add'
color 图标颜色 String false '#999999'
size 图标字体大小，单位rpx String | Number false '60'

# ChooseImageOpts Props

提示

以下属性覆盖chooseImageOpts配置，其余属性参考uniapp.chooseImageOpts (opens new window)

名称 描述 类型 必选 默认值
sizeType original 原图，compressed 压缩图 Array true ['original','compressed']
sourceType 图像来源方式，album 从相册选图，camera 使用相机，默认二者都有。如需直接开相机或直接选相册，请只使用一个选项 Array true ['album', 'camera']
crop 图像裁剪参数，设置后 sizeType 失效 Object false {}

# Default ParseResultFn

parseResultFn: function(result) {
  try {
    return JSON.parse(result.data)?.data.url
  } catch (error) {
    console.error('解析上传结果失败，请使用自定义解析函数 parseResultFn ', error)
  }
}
1
2
3
4
5
6
7

# Events

Event Name Description Parameters
preview 预览 -
uploaded v1.2.5 上传完毕 服务端返回数据
fail v1.2.5 上传失败 -
remove v1.2.5 删除 当前删除索引
crop v1.2.5 开始剪裁 图片路径
cancelCrop v1.2.5 取消剪裁 -
croped v1.2.5 完成剪裁 -

# Slots

Name Description Default Slot Content
uploadBtn - 添加按钮
Last updated: 2022/4/25 下午3:40:34

← Stepper 步进器 →

10:44