uni.uploadFile(options)

展示全部

# uni.uploadFile(options) GitCode GitHub

将本地资源上传到开发者服务器。

# uploadFile 兼容性

Web	微信小程序	Android	iOS	iOS uni-app x UTS 插件	HarmonyOS
4.0	4.41	3.91	4.11	4.11	4.61

推荐上传到uniCloud，uniCloud提供了更便宜CDN和更好的易用性，详见

# 参数

名称类型必填默认值兼容性描述

options

UploadFileOptions

是

名称类型必备默认值兼容性描述

url

string

是

开发者服务器 url

filePath

string

否

null

要上传文件资源的路径, 支持uni.env

name

string

否

null

文件对应的 key , 开发者在服务器端通过这个 key 可以获取到文件二进制内容

files

Array<UploadFileOptionFiles>

否

null

需要上传的文件列表。

名称

类型

必备

默认值

兼容性

描述

name

string

否

"file"

multipart 提交时，表单的项目名，默认为 file，如果 name 不填或填的值相同，可能导致服务端读取文件时只能读取到一个文件。

uri

string

是

要上传文件资源的路径

file

any

否

要上传的文件对象

header

UTSJSONObject

否

null

HTTP 请求 Header, header 中不能设置 Referer

formData

UTSJSONObject

否

null

HTTP 请求中其他额外的 form data

timeout

number

否

120000

超时时间，单位 ms

success

(result: UploadFileSuccess) => void

否

null

成功返回的回调函数

fail

(result: UploadFileFail) => void

否

null

失败的回调函数

complete

(result: any) => void

否

null

结束的回调函数（调用成功、失败都会执行）

enableHttp2

boolean

否

需要基础库： 2.10.4

是否开启 http2

enableProfile

boolean

否

是否开启 profile，默认开启。开启后可在接口回调的 res.profile 中查看性能调试信息。目前仅 iOS 端支持。

enableQuic

boolean

否

需要基础库： 2.10.4

是否开启 Quic/h3 协议（iOS 微信目前使用 gQUIC-Q43；Android 微信在 v8.0.54 前使用 gQUIC-Q43，v8.0.54 开始使用 IETF QUIC，即 h3 协议；PC微信使用 IETF QUIC，即 h3 协议）

useHighPerformanceMode

boolean

否

需要基础库： 3.4.1

使用高性能模式，暂仅支持 Android，默认关闭。该模式下有更优的网络性能表现。

# UploadFileSuccess 的属性值

名称

类型

必备

默认值

兼容性

描述

data

string

是

开发者服务器返回的数据

statusCode

number

是

开发者服务器返回的 HTTP 状态码

# UploadFileFail 的属性值

名称

类型

必备

默认值

兼容性

描述

errCode

number

是

错误码

合法值

兼容性

描述

接口超时

1000

服务端系统错误

100001

json数据解析错误

100002

错误信息json解析失败

100003

json解析类型转换失败

600003

网络中断

600008

data参数类型不合法

600009

URL格式不合法

602001

request系统错误

errSubject

string

是

统一错误主题（模块）名称

data

any

否

错误信息中包含的数据

cause

Error

否

源错误信息，可以包含多个错误，详见SourceError

errMsg

string

是

# 返回值

类型
UploadTask

# UploadTask 的方法

# abort(): void,

abort 中断上传任务。

# abort 兼容性

Web	微信小程序	Android	iOS	iOS uni-app x UTS 插件	HarmonyOS
4.0	4.41	3.91	4.11	4.11	4.61

# onProgressUpdate(callback: UploadFileProgressUpdateCallback): void,

onProgressUpdate 监听上传进度变化。

# onProgressUpdate 兼容性

Web	微信小程序	Android	iOS	iOS uni-app x UTS 插件	HarmonyOS
4.0	4.41	3.91	4.11	4.11	4.61

# 参数

名称

类型

必填

默认值

兼容性

描述

callback

(result: OnProgressUpdateResult) => void

是

# OnProgressUpdateResult 的属性值

名称

类型

必备

默认值

兼容性

描述

progress

number

是

上传进度百分比

totalBytesSent

number

是

已经上传的数据长度，单位 Bytes

totalBytesExpectedToSend

number

是

预期需要上传的数据总长度，单位 Bytes

注意事项

在4.25版本iOS平台增加了Task原生对象自动销毁的逻辑，即上传完成后自动释放原生的Task对象，建议开发者在complete回调中置空Task对象，例

complete: () => {
            this.task = null
          },

如不释放，在调用Task对象的方法将导致控制台报错： error: instance object does not exist: id:15

# 示例

示例为hello uni-app x alpha分支，与最新HBuilderX Alpha版同步。与最新正式版同步的master分支示例另见

示例

<template>
  <!-- #ifdef APP -->
  <scroll-view class="page-scroll-view">
  <!-- #endif -->
    <view>
      <page-head :title="title"></page-head>
      <view class="uni-padding-wrap uni-common-mt">
        <view class="demo">
          <image v-if="imageSrc" :src="imageSrc" class="image" mode="widthFix"></image>
          <text v-else class="uni-hello-addfile" @click="chooseImage">+ 选择图片</text>
        </view>
      </view>
    </view>
  <!-- #ifdef APP -->
  </scroll-view>
  <!-- #endif -->
</template>
<script>
  // #ifdef APP-ANDROID || APP-IOS || APP-HARMONY
  import {
    testInovkeUploadFile,
    CommonOptions
  } from '@/uni_modules/test-invoke-network-api'
  // #endif

  export default {
    data() {
      return {
        title: 'uploadFile',
        imageSrc: '',
        task: null as UploadTask | null,
        //自动化测试例专用
        jest_result: false,
      }
    },
    onLoad() {
    },
    onUnload() {
      this.imageSrc = '';
      uni.hideLoading();
      this.task?.abort();
    },
    methods: {
      chooseImage: function () {
        uni.chooseImage({
          count: 1,
          sizeType: ['compressed'],
          sourceType: ['album'],
          success: (res) => {
            console.log('chooseImage success, temp path is', res.tempFilePaths[0])
            var imageSrc = res.tempFilePaths[0]
            uni.showLoading({
              title: '上传中'
            })
            this.task = uni.uploadFile({
              url: 'https://unidemo.dcloud.net.cn/upload', //仅为示例，非真实的接口地址
              filePath: imageSrc,
              name: 'file',
              formData: {
                'user': 'test'
              },
              success: (res) => {
                console.log('uploadImage success, res is:', res)
                uni.showToast({
                  title: '上传成功',
                  icon: 'success',
                  duration: 1000
                })
                this.imageSrc = imageSrc
              },
              fail: (err) => {
                console.log('uploadImage fail', err);
                uni.showModal({
                  content: err.errMsg,
                  showCancel: false
                });
              },
              complete: (res) => {
                uni.hideLoading();
                this.task = null
              }
            });
          },
          fail: (err) => {
            console.log('chooseImage fail', err)
          }
        })
      },
      //自动化测试例专用
      jest_uploadFile() {
        const imageSrc = "/static/uni.png";
        uni.uploadFile({
          url: 'https://unidemo.dcloud.net.cn/upload', //仅为示例，非真实的接口地址
          filePath: imageSrc,
          name: 'file',
          formData: {
            'user': 'test'
          },
          success: () => {
            this.jest_result = true;
          },
          fail: () => {
            this.jest_result = false;
          },
        })
      },
      jest_uploadFile_with_uni_env() {
        /**
         * 微信小程序只支持USER_DATA_PATH，且子目录未创建的情况下不能直接下载到子目录内
         */
        const filePath = `${uni.env.USER_DATA_PATH}/uni-app.png`
        uni.downloadFile({
          url: "https://qiniu-web-assets.dcloud.net.cn/unidoc/zh/uni-app.png",
          filePath: filePath,
          success: () => {
            uni.uploadFile({
              url: 'https://unidemo.dcloud.net.cn/upload', //仅为示例，非真实的接口地址
              filePath: filePath,
              name: 'file',
              success: () => {
                this.jest_result = true;
              },
              fail: () => {
                this.jest_result = false;
              },
            })
          },
          fail: () => {
            this.jest_result = false
          }
        });
      },
      jest_set_cookie() {
        uni.request({
          url: "https://request.dcloud.net.cn/api/http/header/setCookie",
          method: "GET",
          timeout: 6000,
          sslVerify: false,
          withCredentials: false,
          firstIpv4: false,
          success: () => {
            this.jest_cookie_upload(true)
          },
          fail: () => {
            this.jest_result = false;
          },
        });
      },

      jest_delete_cookie() {
        uni.request({
          url: "https://request.dcloud.net.cn/api/http/header/deleteCookie",
          method: "GET",
          timeout: 6000,
          sslVerify: false,
          withCredentials: false,
          firstIpv4: false,
          success: () => {
            this.jest_cookie_upload(false)
          },
          fail: () => {
            this.jest_result = false;
          },
        });
      },
      jest_cookie_upload(needCookie : boolean) {
        const imageSrc = "/static/uni.png";
        uni.uploadFile({
          url: 'https://request.dcloud.net.cn/api/http/header/upload',
          filePath: imageSrc,
          name: 'file',
          success: (res : UploadFileSuccess) => {
            const data = JSON.parseObject(res.data)
            const errCode = data?.getNumber("errCode")
            if (errCode != null && errCode == 1000) {
              this.jest_result = needCookie ? false : true;
            } else {
              this.jest_result = needCookie ? true : false;
            }
          },
          fail: () => {
            this.jest_result = false;
          },
        })
      },
      jest_files_upload() {
        const imageSrc = "/static/uni.png";
        uni.uploadFile({
          url: 'https://unidemo.dcloud.net.cn/upload',
          files: [
            {
              name: "file1",
              uri: imageSrc
            } as UploadFileOptionFiles,
            {
              name: "file2",
              uri: imageSrc
            } as UploadFileOptionFiles
          ],
          success: (res : UploadFileSuccess) => {
            if (res.statusCode == 200) {
              this.jest_result = true;
            }
          },
          fail: () => {
            this.jest_result = false;
          },
        })
      },
      jest_uts_module_invoked() {
        // #ifdef APP-ANDROID || APP-IOS || APP-HARMONY
        testInovkeUploadFile({
          success: (res : any) => {
            this.jest_result = true
          },
          fail: (err : any) => {
            this.jest_result = false
          }
        } as CommonOptions)
        // #endif
      }
    }
  }
</script>

<style>
  .image {
    width: 100%;
  }

  .demo {
    background: #fff;
    padding: 25px;
    justify-content: center;
    align-items: center;
  }

  .uni-hello-addfile {
    text-align: center;
    background: #fff;
    padding: 25px;
    margin-top: 10px;
    font-size: 19px;
    color: #808080;
  }
</style>