uni.downloadFile(options) @downloadfile

uni.downloadFile(options)

参数

注意事项

返回值

DownloadTask 的方法

abort()

onProgressUpdate(callback)

downloadFile 兼容性

参见

示例

展示全部

# uni.downloadFile(options)

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

下载文件常见场景是apk的下载更新，app升级中心是一个现成的开源项目，实现下载进度在通知栏显示等复杂交互，可直接使用。

# 参数

名称类型必填默认值描述

options DownloadFileOptions 是 -

名称	类型	必备	默认值	描述
url	string	是	-	下载资源的 url
header	UTSJSONObject \| null	否	null	HTTP 请求 Header，header 中不能设置 Referer
filePath	string \| null	否	null	指定文件下载路径支持相对路径与绝对路径，例： `/imgs/pic.png`、`/storage/emulated/0/Android/data/io.dcloud.HBuilder/apps/HBuilder/temp/imgs/pic.png` 并且支持指定下载目录，例： `/imgs/` 支持uni.env的平台兼容性：Android自3.9开始支持uni.env，iOS自4.13开始支持uni.env
timeout	number \| null	否	120000	超时时间，单位 ms
success	(result: DownloadFileSuccess) => void \| null	否	null	下载成功后以 tempFilePath 的形式传给页面，res = {tempFilePath: '文件的临时路径'}
fail	(result: DownloadFileFail) => void \| null	否	null	失败的回调函数
complete	(result: any) => void \| null	否	null	结束的回调函数（调用成功、失败都会执行）

# DownloadFileSuccess 的属性值

名称	类型	必备	默认值	描述
tempFilePath	string	是	-	临时文件路径，下载后的文件会存储到一个临时文件
statusCode	number	是	-	开发者服务器返回的 HTTP 状态码

# DownloadFileFail 的属性值

名称	类型	必备	默认值	描述
errCode	5 \| 1000 \| 100001 \| 100002 \| 600003 \| 600009 \| 602001	是	-	错误码 - 5 接口超时 - 1000 服务端系统错误 - 100001 json数据解析错误 - 100002 错误信息json解析失败 - 600003 网络中断 - 600009 URL格式不合法 - 602001 request系统错误
errSubject	string	是	-	统一错误主题（模块）名称
data	any \| null	否	-	错误信息中包含的数据
cause	Error \| null	否	-	源错误信息，可以包含多个错误，详见SourceError
errMsg	string	是	-	-

# 注意事项

当目录下有同名文件时，文件名会增加数字后缀，例如：目录下abc.txt已经存在，此时下载此文件名的文件到此目录时，下载后的文件会命名为abc(1).txt。
App-Android下载的默认目录为外置应用沙盒目录下的cache目录。如果手机磁盘空间不足，系统清理工具会清理cache目录。
- 如需主动删除下载文件，使用uni.getFileSystemManager。
- 默认下载路径为外置应用沙盒目录uni.env.CACHE_PATH/cache/uni-download。但在HBuilderX 3.99前有过几次变更，3.98的目录是uni.env.CACHE_PATH/cache/uniDownloads，而3.98之前则不在cache目录下。

# 返回值

类型
DownloadTask

# DownloadTask 的方法

# abort()

中断下载任务。

# abort 兼容性

Android	iOS	web
3.9	4.11	4.0

# 参见

参见uni-app相关文档

# onProgressUpdate(callback)

监听下载进度变化。

# 参数

名称	类型	必填	默认值	描述
callback	(result: OnProgressDownloadResult) => void	是	-

# OnProgressDownloadResult 的属性值

名称	类型	必备	默认值	描述
progress	number	是	-	下载进度百分比
totalBytesWritten	number	是	-	已经下载的数据长度，单位 Bytes
totalBytesExpectedToWrite	number	是	-	预期需要下载的数据总长度，单位 Bytes

# onProgressUpdate 兼容性

Android	iOS	web
3.9	4.11	4.0

# 参见

参见uni-app相关文档

# downloadFile 兼容性

Android	iOS	web
3.9	4.11	4.0

# 参见

参见uni-app相关文档

# 示例

hello uni-app x

Template

Script

<template>
  <!-- #ifdef APP -->
  <scroll-view style="flex: 1">
  <!-- #endif -->
    <view>
      <page-head :title="title"></page-head>
      <view>
        <view v-if="imageSrc">
          <image class="img" :src="imageSrc" mode="aspectFit" />
        </view>
        <view v-else style="margin: 10px;">
          <text class="uni-hello-text">点击按钮下载服务端示例图片（下载网络文件到本地临时目录）</text>
          <button type="primary" @tap="downloadImage">下载</button>
        </view>
      </view>
    </view>
  <!-- #ifdef APP -->
  </scroll-view>
  <!-- #endif -->
</template>


<style>
  .img {
    margin: 0 auto;
  }
</style>