图片上传
WdUploadImage
适用场景
用于上传保存本地图片
基础能力
绑定「图片、数组」字段
- 单张图片上传：表单容器绑定数据模型后，模型中的「图片」字段会自动渲染为图片上传组件，实现对单张图片上传的支持
- 多张图片上传：表单容器绑定数据模型后，模型中元素类型为图片的「数组」字段会自动渲染为图片上传组件，实现对多张图片上传的支持
扩展场景
获取用户上传图片后的图片文件 ID
通过图片上传组件上传图片后，会触发「文件上传」事件，通过该事件的出参 event.detail.value 获取上传图片的 cloudID，可通过打印日志的方式，查看到该 ID，示例如下
创建一个自定义方法，写入打印日志代码 console.log(event.detail.value) ，具体内容格式如下图所示：
页面中拖入「图片上传」组件，配置「值改变」事件触发该打印日志方法
预览配置效果，会发现当选择图片进行上传后，会将上传图片的 cloudID 打印在控制台中（注意：组件的「上传单张图片属性关闭时，支持多图片上传，打印内容会是 array 类型的数据；该属性开启时，限制仅可上传一个图片，打印内容会是 string 类型数据）
上传单张图片属性关闭时打印结果
上传单张图片属性开启时打印结果
在日常使用中，您可以通过组件的上传成功事件，将该 ID 存入变量，或通过其他方式进行使用
其他场景实践
查阅表单场景实践指南，可学习了解关于表单的各类支持场景和实现方案
注意事项
图片上传后，用户可通过该图片的 https 地址下载/查看图片。如需限制所有文件/图片资源仅当前上传用户可下载，请在微搭环境的云开发-云存储模块中调整存储桶访问权限为「仅创建者及管理员可读写」
示例
交互式预览
组件输入状态
样式 API 示例
#wd-page-root .wd-form-item.wd-pc-upload-image-root .wd-upload-image__label {
color: #05c3c3;
display: flex;
justify-content: center;
align-items: center;
}
属性
组件接收的外部传入的属性
属性名 | 属性标识 | 类型 | 说明 |
|---|
| 显示标题 | labelVisible | boolean | 默认值：true |
| 标题对齐 | labelAlign | string | 表单场景下默认会跟随表单容器的标题对齐配置 |
| 标题换行 | labelWrap | boolean | 如果标题内容过长关闭时只显示一行、溢出省略；开启时换行展示。表单场景下默认会跟随表单容器的标题换行配置 |
| 标题位置 | layout | string | 设置标题在表单组件的展示位置，表单场景下默认会跟随表单容器的标题的位置配置 |
| 标题宽度 | labelWidth | string | 您可以输入数值 + px、%等单位，示例：200px 表单场景下默认会跟随表单容器的标题宽度配置 |
| 标题提示 | labelTips | string | PC/H5端生效 配置标题的工具提示内容 |
| 图片来源 | sourceType | string | 受各端浏览器特性限制，选择「拍照」时，PC端将禁用上传；选择「相册」时，H5端将禁用上传；安卓端微信浏览器不支持批量选择照片。 图片选择的来源 默认值："both" |
| 小程序端获取微信头像 | isChooseAvatar | boolean | 开启后小程序用户可选择直接上传微信头像；仅小程序端生效 |
| 下方提示 | extra | string | 配置后提示内容常显在输入框下方 |
| 图片形状 | showShape | string | 只影响图片的展示效果，不会对图片进行裁剪 默认值："ectangle" |
| 移动端显示下划线 | borderedH5 | boolean | 关闭后移动端不显示底部下划线 默认值：true |
callbacks | object | 配置相关的函数 | |
| 上传前压缩图片 | isCompressBeforeUpload | boolean | iOS小程序端仅支持压缩JPG格式图片 |
| 压缩质量 | compressQuality | number | 该属性仅对JPG格式图片有效，范围0~100，数值越小，质量越低，压缩率越高 默认值：70 |
| 压缩后图片宽度（px） | compressedWidth | number | 若为空则以「压缩后图片高度」为准等比缩放；两个属性均为空时，保持图片原尺寸 |
| 压缩后图片高度（px） | compressedHeight | number | 若为空则以「压缩后图片宽度」为准等比缩放；两个属性均为空时，保持图片原尺寸 |
| 图片类型 | acceptTypes | array | 绑定表达式示例：[".jpg",".png", "image/gif"]，该属性暂不支持小程序 支持上传的图片类型格式 默认值：["image/*"] |
| 单张图片大小上限(M) | maxSize | number | 单张图片大小上限 默认值：10 |
| 图片数量上限 | maxUploadCount | number | 允许上传的最大数量 默认值：9 |
| 状态 | status | string | 示例："edit" |
| 必填 | required | boolean | |
| 必填标识 | requiredFlag | boolean | 启用后，组件若要求必填，则会显示必填星号标记 默认值：true |
| 必填校验提示 | requiredMsg | string | 示例："该项为必填项" |
| 绑定字段 | name | string | 图片上传后，图片 https 链接默认仅可在微搭应用中访问，有效期 2 小时，可在云存储权限设置中调整访问权限。 表单字段的Key值，用于提交数据时，匹配数据模型字段标识。表单内需保证唯一。 |
| 标题内容 | label | string | 示例："图片上传" |
| 图片值 | value | array | 支持以数组格式写入文件的https地址或cloudID；上传单个时支持字符串类型，上传多个时支持数组类型 |
| 上传单个图片 | single | boolean | 如需上传多张图片，可关闭该属性，但需绑定数组-图片字段，以保证表单的正常提交 了解详情 开启小程序端获取微信头像后，仅能上传1张图片 |
上传前处理函数属性
可以通过上传前处理函数来对上传的图片做预处理： 如压缩，裁剪等。
函数入参类型：
type BeforeUploadParams0 = {
// base64 uri
base64Uri: string[];
// 小程序端独有, 临时文件地址数组
tempFilePaths?: string[];
// web 端独有, File对象
files: File[];
};
Web 端可以调用引用外部库如 compressorjs 处理 File 对象， 小程序可以使用小程序提供的 API 如，wx.compressImage, wx.cropImage 处理临时文件地址。
函数返回值类型：
boolean | File[] | string[]
- 返回 true，继续默认上传逻辑。
- 返回 false，禁用默认上传逻辑。
- web 端返回 File数组。web 端接收函数返回的 file[]作为上传对象，完成上传逻辑。
- 小程序端返回 string[]临时文件地址数组。小程序端接收函数返回的临时文件地址数组作为上传对象，完成上传逻辑。
应用运行端可以通过平台 API进行判断，从而完善多端自定义上传逻辑。
示例：自定义上传
比如，想要自定义上传到别的地方例如 COS 下面使用微搭环境内的云开发云存储做示例：
async (result) => {
console.log('beforeUpload', result);
// 上传前可以做处理，例如压缩等
// result.files[0] = FAKE_COMPRESS（result.files[0])
const tcb = await $w.cloud.getCloudInstance();
const res = await tcb.uploadFile({
cloudPath: 'ttt/abc.jpg',
filePath: result.files[0],
});
console.log(res.download_url); // 图片HTTP 地址
$w.uploadImage1.setValue({ value: [res.download_url] }); // 将得到的http地址设置到图片上传组件中
return false; // 中止上传
};
事件
组件暴露的事件，可以监听组件的事件来触发一些外部的动作
事件名 | 事件code | 事件出参 event.detail | 适用情况 | 说明 |
|---|
| 值改变 | change | object
| 兼容三端 | 用户修改组件值时触发 |
| 上传成功 | success | object
| 兼容三端 | - |
| 上传失败 | error | 兼容三端 | - |
属性 API
通过属性 API，可以获取组件内部的状态和属性值，可以通过$w.componentId.propertyName 来访问组件内部的值，如 $w.input1.value ，详请请参考 属性 API
只读属性名 | 属性标识 | 类型 | 说明 |
|---|
| 绑定字段 | name | string | 表单字段的Key值，用于提交数据时，匹配数据模型字段标识。表单内需保证唯一。 |
| 标题内容 | label | string | |
| 图片值 | value | array | 支持以数组格式写入文件的https地址或cloudID；上传单个时支持字符串类型，上传多个时支持数组类型 |
| 必填 | required | boolean | |
| 是否展示 | visible | boolean | 组件是否展示 |
| 是否禁用 | disabled | boolean | 组件是否禁用 |
| 是否只读 | readOnly | boolean | 组件是否只读 |
方法 API
通过方法 API，可以通过程序触发组件内部的方法，比如提交表单，显示弹窗等, 可以通过$w.componentId.methodName来调用组件方法，如 $w.form1.submit()
方法名 | 方法标识 | 参数 | 方法说明 |
|---|
| 设置值 | setValue | object
| 通过 $w.id1.setValue("weda") 设置组件值 |
| 设置显隐 | setVisible | boolean显示 | 通过 $w.id1.setVisible(false) 设置组件为隐藏 |
| 设置禁用 | setDisabled | boolean禁用 | 通过 $w.id1.setDisabled(true) 设置组件为禁用 |
| 清空值 | clearValue | 通过 $w.id1.clearValue() 清空组件值 | |
| 设置只读 | setReadOnly | boolean只读 | 通过 $w.id1.setReadOnly(true) 设置组件为只读 |
| 触发校验 | handleValidate | 通过 $w.id1.handleValidate() 校验组件值 | |
| 清除校验 | clearValidate | 通过 $w.id1.clearValidate() 清除组件校验 |
样式 API
通过样式 API，可以覆盖组件中内部元素的样式来实现自定义，例如在低代码编辑器中中通过 #wd-page-root .wd-btn 即可为所有的按钮组件编写样式，通过 :scope 可以控制单个组件样式， 详细说明请参考样式 API
名称 | 类名 | 说明和示例 |
|---|
| 根元素 | .wd-upload-image-root | 组件最外层元素 |
| H5 端根元素 | .wd-h5-upload-image-root | 可设定 H5 端的根元素样式 |
| PC 端根元素 | .wd-pc-upload-image-root | 可设定 PC 端的根元素样式 |
| 小程序端根元素 | .wd-mp-upload-image-root | 可设定小程序端的根元素样式 |
| 无边框状态 | .wd-upload-image-root.is-borderless | 设置组件无边框状态样式 |
| 必填状态 | .wd-upload-image-root.is-required | 设置组件必填状态样式 |
| 标题 | .wd-upload-image__label | 组件标题元素 |
| 标题禁用状态 | .wd-upload-image__label.is-disabled | 设置组件标题禁用状态样式 |
| 标题不换行 | .wd-upload-image__label.is-nowrap | 设置组件标题不换行时状态样式 |
| 提示文字 | .wd-upload-image__help | 设置组件提示文字样式 |
| 校验信息 | .wd-upload-image__error | 设置组件校验信息样式 |
| 图片上传前的容器样式 | .weui-uploader__input-box | 图片上传前的背景框样式 |
| 图片上传的 + 号竖线样式 | .weui-uploader__input-box::before | 图片上传的 + 号竖线样式 |
| 图片上传的 + 号横线样式 | .weui-uploader__input-box::after | 图片上传的 + 号横线样式 |
| 图片上传后的容器样式 | weui-uploader__file | 图片上传后的容器样式 |
版本变化
- 属性变化
- 样式变化
- widget api 变化