# 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目录),由系统清理管理。