uni.downloadFile(options)

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

Parameters

name	type	required	default	description
options	DownloadFileOptions	YES	-	-

DownloadFileOptions Values

name	type	optinal	default	description
url	string	YES	-	下载资源的 url
header	UTSJSONObject	NO	null	HTTP 请求 Header，header 中不能设置 Referer
filePath	string	NO	null	指定文件下载路径 支持相对路径与绝对路径，例： /imgs/pic.png、/storage/emulated/0/Android/data/io.dcloud.HBuilder/apps/HBuilder/temp/imgs/pic.png 并且支持指定下载目录，例： /imgs/
timeout	number	NO	120000	超时时间，单位 ms
success	(result: DownloadFileSuccess) => void	NO	null	下载成功后以 tempFilePath 的形式传给页面，res = {tempFilePath: '文件的临时路径'}
fail	(result: DownloadFileFail) => void	NO	null	失败的回调函数
complete	(result: any) => void	NO	null	结束的回调函数（调用成功、失败都会执行）

DownloadFileSuccess Values

name	type	optinal	default	description
tempFilePath	string	YES	-	临时文件路径，下载后的文件会存储到一个临时文件
statusCode	number	YES	-	开发者服务器返回的 HTTP 状态码

DownloadFileFail Values

name	type	optinal	default	description
errCode	5 | 1000 | 100001 | 100002 | 600003 | 600009 | 602001	YES	-	错误码 - 5 接口超时 - 1000 服务端系统错误 - 100001 json数据解析错误 - 100002 错误信息json解析失败 - 600003 网络中断 - 600009 URL格式不合法 - 602001 request系统错误
errSubject	string	YES	-	统一错误主题（模块）名称
data	any	NO	-	错误信息中包含的数据
errMsg	string	YES	-	-

Return value

Type	optinal
DownloadTask	NO

DownloadTask Values

name	type	optinal	default	description
abort	() => void	YES	-	中断下载任务。
onProgressUpdate	(callback: (result: OnProgressDownloadResult) => void) => void	YES	-	监听下载进度变化。

OnProgressDownloadResult Values

name	type	optinal	default	description
progress	number	YES	-	下载进度百分比
totalBytesWritten	number	YES	-	已经下载的数据长度，单位 Bytes
totalBytesExpectedToWrite	number	YES	-	预期需要下载的数据总长度，单位 Bytes

DownloadTask Compatibility

	Android version	Android uni-app	Android uni-app-x	iOS version	iOS uni-app	iOS uni-app-x
abort	4.4	√	3.9+	9.0	√	x
onProgressUpdate	4.4	√	3.9+	9.0	√	x

downloadFile Compatibility

Android version	Android uni-app	Android uni-app-x	iOS version	iOS uni-app	iOS uni-app-x
4.4	√	3.9+	9.0	√	x

See also

downloadFile

Related Bug

Example

hello uni-app x

<template>
 <!-- #ifdef APP -->
 <scroll-view style="flex: 1">
 <!-- #endif -->
   <view>
     <page-head :title="title"></page-head>
     <view class="uni-padding-wrap uni-common-mt">
       <view v-if="imageSrc" class="image-container">
         <image class="img" :src="imageSrc" mode="center" />
       </view>
       <view v-else style="margin-top: 50px">
         <text class="uni-hello-text">点击按钮下载服务端示例图片（下载网络文件到本地临时目录）</text>
         <view class="uni-btn-v">
           <button type="primary" @tap="downloadImage">下载</button>
         </view>
       </view>
     </view>
   </view>
 <!-- #ifdef APP -->
 </scroll-view>
 <!-- #endif -->
</template>
<script>
 export default {
   data() {
     return {
       title: 'downloadFile',
       imageSrc: '',
       task: null as DownloadTask | null,
       //自动化测试例专用
       jest_result: false
     }
   },
   onLoad() {
   },
   onUnload() {
     this.imageSrc = '';
     uni.hideLoading();
     this.task?.abort();
   },
   methods: {
     downloadImage: function () {
       uni.showLoading({
         title: '下载中'
       })
       var self = this
       this.task = uni.downloadFile({
         url: "https://web-assets.dcloud.net.cn/unidoc/zh/uni-app.png",
         success: (res) => {
           console.log('downloadFile success, res is', res)
           self.imageSrc = res.tempFilePath;
           uni.hideLoading();
         },
         fail: (err) => {
           console.log('downloadFile fail, err is:', err)
           uni.hideLoading();
         }
       });
       this.task?.onProgressUpdate((update) => {
         console.log("progress : ", update.progress);
       })
     },
     //自动化测试例专用
     jest_downloadFile() {
       uni.downloadFile({
         url: "https://web-assets.dcloud.net.cn/unidoc/zh/uni-app.png",
         success: () => {
           this.jest_result = true
         },
         fail: () => {
           this.jest_result = false
         }
       });
     }
   }
 }
</script>

<style>
 .img {
   width: 500rpx;
   height: 500rpx;
   margin: 0 auto;
 }

 .image-container {
   display: flex;
   justify-content: center;
   align-items: center;
 }
</style>

General type

GeneralCallbackResult

name	type	optinal	default	description
errMsg	string	YES	-	错误信息

Tips

• 3.98以下版本，下载的文件存放在应用沙盒非cache目录，不会自动删除。3.98及以上版本迁移到应用临时目录（Android原生应用沙盒目录下的cache目录），由系统清理管理。