上传

使用 uni.uploadFile 将本地资源上传到开发者服务器，客户端发起一个 POST 请求，其中 content-type 为 multipart/form-data。
如页面通过 uni.chooseImage 等接口获取到一个本地资源的临时文件路径后，可通过此接口将本地资源上传到指定服务器。

OBJECT 参数说明

参数名 类型 必填 说明 平台支持
url String 是 开发者服务器 url
files Array 否 需要上传的文件列表。使用 files 时，filePath 和 name 不生效。 5+App
filePath String 是 要上传文件资源的路径。
name String 是 文件对应的 key , 开发者在服务器端通过这个 key 可以获取到文件二进制内容
header Object 否 HTTP 请求 Header, header 中不能设置 Referer
formData Object 否 HTTP 请求中其他额外的 form data
success Function 否 接口调用成功的回调函数
fail Function 否 接口调用失败的回调函数
complete Function 否 接口调用结束的回调函数（调用成功、失败都会执行）

files参数说明
files 参数是一个 file 对象的数组，file 对象的结构如下：

参数名 类型 必填 说明
name String 否 multipart 提交时，表单的项目名，默认为 file
uri String 是 文件的本地地址

success 返回参数说明

参数 类型 说明
data String 开发者服务器返回的数据
statusCode Number 开发者服务器返回的 HTTP 状态码

示例

  1. uni.chooseImage({
  2.   success: (chooseImageRes) => {
  3.     const tempFilePaths = chooseImageRes.tempFilePaths;
  4.     uni.uploadFile({
  5.       url: 'https://www.example.com/upload', //仅为示例，非真实的接口地址
  6.       filePath: tempFilePaths[0],
  7.       name: 'file',
  8.       formData: {
  9.         'user': 'test'
  10.       },
  11.       success: (uploadFileRes) => {
  12.         console.log(uploadFileRes.data);
  13.       }
  14.     });
  15.   }
  16. });

返回值
返回一个 uploadTask 对象。

上传任务

通过 uploadTask 可监听上传进度变化事件，以及取消上传任务。

uploadTask 对象的方法列表

方法 参数 说明
onProgressUpdate callback 监听上传进度变化
abort 中断上传任务

onProgressUpdate 返回参数说明

参数 类型 说明
progress Number 上传进度百分比
totalBytesSent Number 已经上传的数据长度，单位 Bytes
totalBytesExpectedToSend Number 预期需要上传的数据总长度，单位 Bytes

示例

  1. uni.chooseImage({
  2.   success: (chooseImageRes) => {
  3.     const tempFilePaths = chooseImageRes.tempFilePaths;
  4.     const uploadTask = uni.uploadFile({
  5.       url: 'https://www.example.com/upload', //仅为示例，非真实的接口地址
  6.       filePath: tempFilePaths[0],
  7.       name: 'file',
  8.       formData: {
  9.         'user': 'test'
  10.       },
  11.       success: (uploadFileRes) => {
  12.         console.log(uploadFileRes.data);
  13.       }
  14.     });
  16.     uploadTask.onProgressUpdate((res) => {
  17.       console.log('上传进度' + res.progress);
  18.       console.log('已经上传的数据长度' + res.totalBytesSent);
  19.       console.log('预期需要上传的数据总长度' + res.totalBytesExpectedToSend);
  21.       // 测试条件，取消上传任务。
  22.       if (res.progress > 50) {
  23.         uploadTask.abort();
  24.       }
  25.     });
  26.   }
  27. });

上传到OSS

上传到 OSS 仍然使用 uni.uploadFile

在 formData 中指定以下内容：

  • url (endpoint)
  • filePath (本地文件的路径, 比如通过录制、选取文件获取临时路径)
  • key (上传路径)
  • policy
  • OSSAccessKeyId
  • signature

其中 policy、OSSAccessKeyId、signature 的获取参考 阿里云 OSS 使用笔记

  1. const url = 'https://xxx.oss-cn-shenzhen.aliyuncs.com'
  2. const policy = 'xxx'
  3. const OSSAccessKeyId = 'xxx'
  4. const signature = 'xxx'
  6. let path = '_temp/test.mp3'
  8. uni.showLoading({ title: '上传中..', mask: true })
  9. uni.uploadFile({
  10.   url,
  11.   filePath: path,
  12.   name: 'file',
  13.   formData: {
  14.     'key' : `test/${path}`,
  15.     'success_action_status' : '200',
  16.     policy, OSSAccessKeyId, signature
  17.   },
  18.   success (uploadFileRes) {
  19.     uni.hideLoading()
  20.     let filepath = `${url}/test/${path}`
  21.     vm.voicePath = filepath
  22.     if (uploadFileRes.statusCode) {
  23.       uni.showToast({ title: '上传成功' })
  24.       vm.source = filepath
  25.     } else {
  26.       uni.showToast({ title: '上传失败: ' + uploadFileRes })
  27.     }
  28.   },
  29.   fail (e) {
  30.     uni.hideLoading()
  31.   }
  32. });

下载

使用 uni.downloadFile 下载文件资源到本地，客户端直接发起一个 HTTP GET 请求，返回文件的本地临时路径。

OBJECT 参数说明

参数名 类型 必填 说明
url String 是 下载资源的 url
header Object 否 HTTP 请求 Header, header 中不能设置 Referer
success Function 否 下载成功后以 tempFilePath 的形式传给页面，res = {tempFilePath: ‘文件的临时路径’}
fail Function 否 接口调用失败的回调函数
complete Function 否 接口调用结束的回调函数（调用成功、失败都会执行）

:::info 文件的临时路径，在应用本次启动期间可以正常使用，如需持久保存，需在主动调用 uni.saveFile，才能在应用下次启动时访问得到。 :::

success 返回参数说明

参数 类型 说明
tempFilePath String 临时文件路径，下载后的文件会存储到一个临时文件
statusCode Number 开发者服务器返回的 HTTP 状态码

示例

  1. uni.downloadFile({
  2.   url: 'https://www.example.com/file/test', //仅为示例，并非真实的资源
  3.   success: (res) => {
  4.     if (res.statusCode === 200) {
  5.       console.log('下载成功');
  6.     }
  7.   }
  8. });

返回值
返回一个 downloadTask 对象。

下载任务

通过 downloadTask，可监听下载进度变化事件，以及取消下载任务。

downloadTask 对象的方法列表

方法 参数 说明 最低版本
onProgressUpdate callback 监听下载进度变化 *
abort 中断下载任务 *

onProgressUpdate 返回参数说明

参数 类型 说明
progress Number 下载进度百分比
totalBytesWritten Number 已经下载的数据长度，单位 Bytes
totalBytesExpectedToWrite Number 预期需要下载的数据总长度，单位 Bytes

示例

  1. const downloadTask = uni.downloadFile({
  2.   url: 'http://www.example.com/file/test', //仅为示例，并非真实的资源
  3.   success: (res) => {
  4.     if (res.statusCode === 200) {
  5.       console.log('下载成功');
  6.     }
  7.   }
  8. });
  10. downloadTask.onProgressUpdate((res) => {
  11.   console.log('下载进度' + res.progress);
  12.   console.log('已经下载的数据长度' + res.totalBytesWritten);
  13.   console.log('预期需要下载的数据总长度' + res.totalBytesExpectedToWrite);
  15.   // 测试条件，取消下载任务。
  16.   if (res.progress > 50) {
  17.     downloadTask.abort();
  18.   }
  19. });

参考资料