Upload 图片上传 
概述
Upload 图片上传，用于选择或拍照进行上传图片。
# 支持平台
| App-vue | App-Nvue | 微信小程序 | 支付宝小程序 | 百度小程序 | 字节小程序 | QQ小程序 | H5 | PC | 快手小程序 | 钉钉小程序 |
|---|---|---|---|---|---|---|---|---|---|---|
| ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
温馨提示
组件内部使用了 fui-icon（字体图标）组件，非 easycom 组件模式下需要手动引入组件（打开组件内部注释的引入内容，引入路径按实际调整）。
小程序端若无法唤起选择图片弹框 (opens new window)，可检查是否更新了 隐私策略 (opens new window)。
# 引入
以下介绍两种常用的引入方式。
第一种：在页面中引用、注册
import fuiUpload from "@/components/firstui/fui-upload/fui-upload.vue"
export default {
components:{
fuiUpload
}
}
1
2
3
4
5
6
2
3
4
5
6
第二种：easycom组件规范
传统vue组件，需要安装、引用、注册，三个步骤后才能使用组件。easycom将其精简为一步。
First UI easycom配置请查看 快速上手。
如果不了解easycom，可先查看 官网文档 (opens new window)。
# 代码演示
部分示例演示，完整使用请参考示例程序以及文档API。
自动上传
通过 immediate 属性设置是否自动上传，url 属性设置上传接口地址。
通过 ref 属性来注册组件引用信息。注册完成后，我们可以通过this.$refs.XXX访问到对应的组件实例，并调用上面的实例方法。
<fui-upload immediate :url="url" ref="upload" @success="success" @error="error" @complete="complete"></fui-upload>
1
data() {
return {
//上传接口地址
url: 'https://ffa.firstui.cn/api/example/upload-file',
//上传状态，用于保存或其他操作时做判断
status: '',
//上传的图片地址列表
urls: []
}
},
methods: {
//上传成功时触发
success(e) {
console.log(e)
//e.res 为服务器返回数据
//上传成功回调，处理服务器返回数据【此处根据实际返回数据进行处理】
let res = JSON.parse(e.res.data.replace(/\ufeff/g, "") || "{}")
this.status = e.status
if (res.data.url) {
//处理结果返回给组件
//res.data.url为上传成功后返回的图片地址
//e.index为图片索引值
this.$refs.upload.result(res.data.url, e.index)
}
},
//上传失败时触发
error(e) {
this.status = e.status
},
//选择图片或上传完成时触发
complete(e) {
this.status = e.status
this.urls = e.urls
if (this.status === 'success' && e.action === 'upload') {
this.fui.toast('上传完成！')
//已上传完成的图片列表 this.urls
console.log(this.urls)
}
}
}
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
30
31
32
33
34
35
36
37
38
39
40
41
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
30
31
32
33
34
35
36
37
38
39
40
41
调用 start 方法上传
通过 background 属性设置选择框背景色，addColor 属性设置加号颜色，fileList 属性设置默认展示的图片列表，url 属性设置上传接口地址。
通过 ref 属性来注册组件引用信息。注册完成后，我们可以通过this.$refs.XXX访问到对应的组件实例，并调用上面的实例方法。
<view class="fui-btn__box">
<fui-button type="gray" width="400rpx" height="84rpx" text="开始上传" bold @click="startUpload">
</fui-button>
</view>
<fui-upload background="#333" addColor="#d1d1d1" :fileList="fileList" :url="url" ref="upload" @success="success" @error="error" @complete="complete"></fui-upload>
1
2
3
4
5
2
3
4
5
data() {
return {
//上传接口地址
url: 'https://ffa.firstui.cn/api/example/upload-file',
//上传状态，用于保存或其他操作时做判断
status: '',
//初始化已上传的图片列表
fileList: ['https://res.firstui.cn/static/images/common/logo.png'],
//上传的图片地址列表
urls: []
}
},
onLoad() {
this.urls = this.fileList
},
methods: {
success(e) {
console.log(e)
//上传成功回调，处理服务器返回数据【此处根据实际返回数据进行处理】
let res = JSON.parse(e.res.data.replace(/\ufeff/g, "") || "{}")
this.status = e.status
if (res.data.url) {
//处理结果返回给组件
//data.url为上传成功后返回的图片地址
//e.index为图片索引值
this.$refs.upload.result(res.data.url, e.index)
}
},
error(e) {
this.status = e.status
uni.showModal({
content: JSON.stringify(e)
})
},
complete(e) {
this.status = e.status
this.urls = e.urls
if (this.status === 'success' && e.action === 'upload') {
this.fui.toast('上传完成！')
//已上传完成的图片列表 this.urls
console.log(this.urls)
}
},
//点击按钮触发上传操作
startUpload() {
if (!this.status || this.status !== 'preupload') {
this.fui.toast('请选择需要上传的图片！')
return
}
//开始上传
this.$refs.upload.start()
}
}
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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
调用 upload 方法上传 V1.9.8+
通过 call-upload 属性设置是否调用 upload 方法进行上传，@reupload 方法为点击重新上传按钮时触发事件。
通过 ref 属性来注册组件引用信息。注册完成后，我们可以通过this.$refs.XXX访问到对应的组件实例，并调用上面的实例方法。
<fui-upload call-upload ref="uploader" @reupload="reUpload" @complete="complete">
</fui-upload>
<view class="fui-btn__box">
<fui-button :margin="['48rpx','0']" type="gray" btn-size="medium" text="调用upload方法上传" bold
@click="callUpload">
</fui-button>
</view>
1
2
3
4
5
6
7
2
3
4
5
6
7
data() {
return {
//上传接口地址
url: 'https://ffa.firstui.cn/api/example/upload-file',
//上传状态，用于保存或其他操作时做判断
status: '',
//上传的图片地址列表
urls: []
}
},
methods: {
/*
以下为调用upload方法手动上传的所有方法内容
*/
//调用upload方法上传时传入的回调函数
uploadFile(file) {
//上传的文件信息
console.log('upload file', file)
// 文件上传的函数，返回一个promise
//上传成功后返回上传后的图片地址，上传失败则返回false即可
return new Promise((resolve, reject) => {
//调用api上传，所有需要参数自行补充
uni.uploadFile({
url: this.url,
name: 'file',
// header: {},
// formData:{},
filePath: file.path,
success: (res) => {
//以下成功或失败逻辑根据接口自行处理
const data = JSON.parse(res.data.replace(/\ufeff/g, "") || "{}")
if (data.statusCode === 200) {
//返回上传成功后的图片
resolve(data.data.url)
} else {
//上传失败
reject(false)
}
},
fail: (err) => {
//上传失败
reject(false)
}
})
})
},
callUpload() {
//注意：此方法上传函数需要页面自行实现，如上 uploadFile（当组件内部方法无法满足时使用该方法自行去实现上传）
if (!this.status || this.status !== 'preupload') {
this.fui.toast('请选择需要上传的图片！')
return
}
//调用upload 方法上传，并传入函数，此时请勿传入index值
this.$refs.uploader.upload(this.uploadFile)
},
//重新上传
reUpload(e) {
/*
callUpload 中上传失败时会出现重新上传按钮
点击重新上传按钮触发（仅call-upload 为true 时有效）
*/
//当前上传按钮索引值
console.log(e.index)
//调用upload 方法上传，并传入函数，且此时需要传入index值
this.$refs.uploader.upload(this.uploadFile, e.index)
},
complete(e) {
console.log(e)
this.status = e.status
this.urls = e.urls
if (this.status === 'success' && e.action === 'upload') {
this.fui.toast('上传完成！')
//已上传完成的图片列表 this.urls
// console.log(this.urls)
}
}
}
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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
start 方法与 upload 方法区别？
start 方法上传，url、name、header、formData等属性需要通过props传入，且使用组件内内置的方法进行上传。
upload 方法上传，需要传入一个返回Promise的文件上传的函数，上传方法需在页面自行实现，更方便扩展，用于满足更多场景需求。
# Slots
| 插槽名称 | 说明 |
|---|---|
| default V1.8.0+ | 用于自定义上传加号图标 |
# Props
| 属性名 | 类型 | 说明 | 默认值 | 平台差异说明 |
|---|---|---|---|---|
| width | Number, String | 选择框或图片宽度，单位rpx | 200 | - |
| height | Number, String | 选择框或图片高度，单位rpx | 200 | - |
| fileList | Array | 初始化默认展示的图片列表，仅初始化使用 | [ ] | - |
| max | Number, String | 最多可上传的图片张数 | 9 | - |
| isAdd | Boolean | 是否显示选择框，仅做展示时使用 | true | - |
| addColor | String | 选择框加号颜色 | #333 | - |
| addSize V1.9.5+ | Number, String | 选择框加号大小，单位rpx | 88 | - |
| background | String | 选择框背景颜色 | #eee | - |
| radius V1.9.5+ | Number, String | 选择框圆角值，单位rpx | 0 | - |
| borderColor V1.9.5+ | String | 选择框边框颜色，设置颜色则边框生效，默认边框宽度1px | - | - |
| borderSytle V1.9.5+ | String | 选择框边框样式，可选值：solid、dashed、dotted | solid | - |
| isDel | Boolean | 是否显示删除图标，仅做展示时使用 | true | - |
| delColor | String | 删除图标颜色 | rgba(0,0,0,.6) | - |
| confirmDel V1.4.0+ | Boolean | 删除图片时是否弹框确认 | false | - |
| url | String | 图片上传接口地址，调用 upload 方法上传时无效 | - | - |
| immediate | Boolean | 是否立即/自动上传，为false时需要调用start或upload方法手动上传 | false | - |
| callUpload V1.9.8+ | Boolean | 是否调用 upload 方法进行上传操作，调用upload方法上传时务必传 true | false | - |
| sizeType | Array | original 原图，compressed 压缩图，默认二者都有 | ['original', 'compressed'] | App、微信小程序、支付宝小程序、百度小程序 |
| sourceType | Array | album 从相册选图，camera 使用相机，默认二者都有 | ['album', 'camera'] | - |
| suffix | Array | 图片后缀名范围列表，为空则不限制，如：['jpg','png']，则仅可上传jpg与png图片 | [ ] | - |
| size | Number, String | 单张图片大小限制，单位MB | 4 | - |
| name | String | 文件对应的 key , 开发者在服务器端通过这个 key 可以获取到文件二进制内容 | file | - |
| header | Object | HTTP 请求 Header, header 中不能设置 Referer | { } | - |
| formData | Object | HTTP 请求中其他额外的 form data | { } | - |
| param | Number, String | 自定义参数，事件中回传 | 0 | - |
# Events
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| @success | 图片上传成功时触发 | { status:上传状态 index:图片索引 res:服务器返回数据 param:自定义参数 } |
| @error | 图片上传失败时触发 | { status:上传状态 index:图片索引 res:错误信息 param:自定义参数 } |
| @complete | 图片选择、上传完成、删除时触发 | { status:上传状态 urls:上传的图片列表 action:当前动作,见下方说明 param:自定义参数 } |
| @preview | 点击图片时触发，预览大图，仅百度小程序使用 | { index:当前索引值 urls:预览图片列表 } |
| @reupload V1.9.8+ | 点击重新上传按钮时触发，仅调用upload方法上传时有效且属性 callUpload 必须设为true | { index:当前索引值 } |
// status：上传状态说明
preupload：尚有等待上传的图片
uploading：尚有正在上传的图片
success：全部上传成功
error：尚有上传失败的图片
//@complete 事件action参数说明：
action有效值为：choose、upload、delete。分别代表选择图片、上传、删除图片。
//温馨提示：图片上传后触发@success 事件（非调用upload方法上传时），回调参数中包含服务器返回数据，
//根据接口返回数据处理，并将上传后的图片地址回传给组件。
1
2
3
4
5
6
7
8
9
10
11
2
3
4
5
6
7
8
9
10
11
# Methods
通过 ref 属性来注册组件引用信息。注册完成后，我们可以通过this.$refs.XXX访问到对应的组件实例，并调用上面的实例方法。
| 方法名 | 说明 | 传入参数 |
|---|---|---|
| result | 上传成功触发@success后，处理服务器返回数据，将图片地址返回给组件 | (url, index) (图片地址,图片索引) |
| start | 选择完图片后调用 start 方法进行上传 | - |
| upload V1.9.8+ | 选择完图片后调用 upload 方法进行上传，且传入返回Promise的文件上传的函数 | (callback, index) (上传函数,图片索引) |
特别说明
调用 upload 方法上传时，属性
callUpload必须设为true（用于触发 @reupload 事件）。upload 方法有两个参数，初始上传时请勿传入第二个参数（index），如果传入第二个参数，则判定为点击重新上传按钮进行上传。
// upload 方法 callback 参数详细说明，以下为示例中提供函数方法（必须传入一个返回Promise的文件上传的函数）
//传入该方法后，组件内调用并回传图片文件信息 file（包含 path（本地文件路径），size（本地文件大小，单位：B），name（包含扩展名的文件名称，仅H5支持），type（文件类型，仅H5支持））等信息。
uploadFile(file) {
//上传的文件信息
console.log('upload file', file)
// 文件上传的函数，返回一个promise
//上传成功后返回上传后的图片地址，上传失败则返回false即可
return new Promise((resolve, reject) => {
//调用api上传，所有需要参数自行补充
uni.uploadFile({
url: this.url,
name: 'file',
// header: {},
// formData:{},
filePath: file.path,
success: (res) => {
//以下成功或失败逻辑根据接口自行处理
const data = JSON.parse(res.data.replace(/\ufeff/g, "") || "{}")
if (data.statusCode === 200) {
//返回上传成功后的图片，约定的返回参数，不可更改格式
resolve(data.data.url)
} else {
//上传失败，约定的返回参数，不可更改格式
reject(false)
}
},
fail: (err) => {
//上传失败，约定的返回参数，不可更改格式
reject(false)
}
})
})
}
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
30
31
32
33
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
30
31
32
33
示例预览
# 示例代码地址
VIP内容代码请查看订单页下载的组件库示例源码。# 特别说明
该组件为付费组件，UNI-APP版VIP用户可免费使用 。