antd-mini
Version:
antd-mini 是支付宝小程序 UI 组件库，遵循 Ant Design 规范。
281 lines (246 loc) • 16.2 kB
Markdown
---
nav:
path: /components
group:
title: 数据录入
toc: 'content'
---
用于将图片上传到服务器，并简略展示上传文件的信息及提供预览功能。需要将本地图片或拍照后上传到服务器时使用。
在 `index.json` 中引入组件
```json
"usingComponents": {
"ant-uploader": "antd-mini/es/ImageUpload/index"
"ant-uploader": "antd-mini/ImageUpload/index"
}
```
> `onBeforeUpload`、`onUpload` 函数接收 `LocalFile`，可以定制上传相关业务逻辑。`preview` 事件是点击已上传图片触发，可以配合 [my.previewimage](https://opendocs.alipay.com/mini/api/media/image/my.previewimage) 实现图片预览。`change` 事件则将在已上传的文件列表变化时触发。
```xml
<ant-uploader
defaultFileList="{{defaultFileList}}"
uploadingText="上传中……"
uploadfailedText="上传失败"
onBeforeUpload="onBeforeUpload"
onUpload="onUpload"
onPreview="onPreview"
onChange="onChange"
onBeforeUpload="{{onBeforeUpload}}"
onUpload="{{onUpload}}"
bindchange="onChange"
bindpreview="onPreview"
/>
```
```js
Page({
data: {
defaultFileList: [{ url: 'https://gw.alipayobjects.com/mdn/rms_226d75/afts/img/A*znK_ToIL8rQAAAAAAAAAAAAAARQnAQ', status: 'done' }],
#if WECHAT
onUpload(file) {
return new Promise((resolve) => {
console.log('上传的图片为：', file);
setTimeout(() => {
resolve(
'https://gw.alipayobjects.com/mdn/rms_226d75/afts/img/A*5m0ZQYhxhjEAAAAAAAAAAAAAARQnAQ'
);
}, 2000);
});
},
onBeforeUpload(localFileList) {
console.log('即将上传的图片列表为：', localFileList);
localFileList = localFileList.filter((item) => item.size < 10000);
console.log('修改上传的图片列表为：', localFileList);
return localFileList;
},
},
onChange(fileList) {
console.log('图片列表：', fileList);
},
onPreview(file) {
console.log('preview', file);
},
onUpload(file) {
return new Promise((resolve) => {
console.log('上传的图片为：', file);
setTimeout(() => {
resolve(
'https://gw.alipayobjects.com/mdn/rms_226d75/afts/img/A*5m0ZQYhxhjEAAAAAAAAAAAAAARQnAQ'
);
}, 2000);
});
},
onBeforeUpload(localFileList) {
console.log('即将上传的图片列表为：', localFileList);
localFileList = localFileList.filter((item) => item.size < 10000);
console.log('修改上传的图片列表为：', localFileList);
return localFileList;
},
});
```
> `fileList`和 `change` 事件配合实现受控模式。想要组件外部触发上传逻辑，通过 `ref` 的方式拿到组件实例，并调用组件中的 `chooseImage` 方法即可。
```xml
<ant-uploader
ref="handleUploaderRef"
fileList="{{fileList}}"
onChange="handleControlledChange"
onUpload="onUpload"
bindchange="handleControlledChange"
onUpload="{{onUpload}}"
/>
<ant-button
size="medium"
onTap="upload"
type="primary">
组件外部触发上传逻辑
</ant-button>
```
```js
Page({
data: {
fileList: [{ url: 'https://gw.alipayobjects.com/mdn/rms_226d75/afts/img/A*znK_ToIL8rQAAAAAAAAAAAAAARQnAQ', status: 'done' }],
#if WECHAT
onUpload(file) {
return new Promise((resolve) => {
console.log('上传的图片为：', file);
setTimeout(() => {
resolve(
'https://gw.alipayobjects.com/mdn/rms_226d75/afts/img/A*5m0ZQYhxhjEAAAAAAAAAAAAAARQnAQ'
);
}, 2000);
});
},
},
onUpload(file) {
return new Promise((resolve) => {
console.log('上传的图片为：', file);
setTimeout(() => {
resolve(
'https://gw.alipayobjects.com/mdn/rms_226d75/afts/img/A*5m0ZQYhxhjEAAAAAAAAAAAAAARQnAQ'
);
}, 2000);
});
},
handleControlledChange(fileList) {
this.setData({
fileList: fileList.detail,
});
this.setData({
fileList,
});
},
handleUploaderRef(ref) {
console.log('handleUploaderRef', ref);
this.handleUploaderRef = ref.detail;
this.handleUploaderRef = ref;
},
upload() {
this.handleUploaderRef.chooseImage();
},
});
```
<code src='../../demo/pages/ImageUpload/index'></code>
| 属性 | 说明 | 类型 | 默认值 |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------- |
| className | 类名 | string | - |
| maxCount | 上传图片限制的最大数量。详见 [maxCount](
| defaultFileList | 文件列表初始值 | [File](
| sourceType | 上传选择的来源。可选 `['album']`、`['camera']` 或 `['album', 'camera']` | string[] | ['album', 'camera'] |
| style | 样式 | string | - |
| uploadingText | 上传中提示文案 | string | '上传中……' |
| uploadfailedText | 上传失败提示文案 | string | '上传失败' |
| fileList | 文件列表（受控） | [File](
| imageMode | 图片缩放模式和裁剪模式。详见 [图片 mode 说明](https://opendocs.alipay.com/mini/component/image#mode) | string | scaleToFill |
| onBeforeUpload | 上传文件之前的钩子。参数为上传的文件列表，若返回 false 则停止上传。支持返回一个 Promise 对象，Promise 对象 reject 时则停止上传，resolve 时开始上传（resolve 传入修改后的 localFileList） | (localFileList: [localFile](
| onChooseImageError | 选择图片失败回调。详见 [onChooseImageError](
| onUpload | 图片上传方法。详见 [onUpload](
| onRemove | 点击移除文件时的回调。返回值为 false 时不移除。支持返回一个 Promise 对象，Promise 对象 resolve(false) 或 reject 时不移除 | (file: [File](
|
|
|
|
| 参数 | 说明 | 类型 | 默认值 |
| ------ | ------------------------------------------------------------------------------ | ------ | ------ |
| url | 图片 url | string | - |
| status | 上传状态。可选 `uploading`（上传中）、`done`（上传完成）或 `error`（上传失败） | string | - |
| uid | 唯一标识符。不设置时会自动生成 | string | - |
| path | 本地图片路径 | string | - |
| size | 本地图片大小。有的机型可能没有返回这个属性 | number | - |
| 参数 | 说明 | 类型 | 默认值 |
| ---- | ------------------------------------------ | ------ | ------ |
| path | 本地图片路径 | string | - |
| size | 本地图片大小。有的机型可能没有返回这个属性 | number | - |
`onUpload` 方法接收 `LocalFile`，在 Promise 里返回 `File`。以下是调用 [my.uploadFile](https://opendocs.alipay.com/mini/api/kmq4hc) 进行上传的示例代码：
```js
onUpload(localFile) {
return new Promise((resolve, reject) => {
my.uploadFile({
url: 'https://...', // 请替换成有效的服务端 url
fileType: 'image',
name: 'userfile', // 根据后台服务需求替换
filePath: localFile.path, // 传入 localFile.path
formData: { extra: '其他信息' }, // 根据后台服务需求替换
success: res => {
// 根据后台返回，得到上传成功的图片 url
const { url } = JSON.parse(res.data);
resolve(url); // 调用 resolve 传入图片 url
},
fail: err => {
reject(); // 上传错误调用 reject
},
});
});
}
```
选择图片可能会失败，`onChooseImageError` 可获取错误，可以查看 [my.chooseImage 错误码](https://opendocs.alipay.com/mini/api/media/image/my.chooseimage#%E9%94%99%E8%AF%AF%E7%A0%81)。
```js
onChooseImageError(err) {
console.log(err);
}
```
1. `maxCount` 表示最多可以上传的图片数量，不传表示无限制。由于小程序选择图片界面有一次性选择图片的上限，如果 `maxCount` 大于此上限，则需要多次上传。例如，`maxCount="{{10}}"`，允许上传 10 张图片，用户需先上传 9 张，之后再上传 1 张。
2. `maxCount` 不限制 `defaultFileList` 和 `fileList`。例如，`maxCount` 为 1，而 `defaultFileList` 包含 2 张图片，不会减少 `defaultFileList` 里的图片。上传按钮则会隐藏。
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 变量名 | 默认值 | 深色模式默认值 | 备注 |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
| --image-upload-cover-background | <div style="width: 150px; height: 40px; background-color: rgba(0, 0, 0, 0.4); color: #ffffff;">rgba(0, 0, 0, 0.4)</div> | <div style="width: 150px; height: 40px; background-color: rgba(0, 0, 0, 0.4); color: #ffffff;">rgba(0, 0, 0, 0.4)</div> | 图片上传封面背景颜色（覆盖） |
| --image-upload-wrapper-background | <div style="width: 150px; height: 40px; background-color: #f5f5f5; color: #333333;">
| --image-upload-text-color | <div style="width: 150px; height: 40px; background-color: #ffffff; color: #333333;">
| --image-upload-background-color | <div style="width: 150px; height: 40px; background-color: rgba(0, 0, 0, 0.4); color: #ffffff;">rgba(0, 0, 0, 0.4)</div> | <div style="width: 150px; height: 40px; background-color: #1a1a1a; color: #ffffff;">