简体中文
简体中文
# uni.downloadFile(options) GitCodeGitHub
下载文件资源到本地，客户端直接发起一个 HTTP GET 请求，返回文件的本地临时路径。
# downloadFile 兼容性
| Web | 微信小程序 | Android | iOS | iOS uni-app x UTS 插件 | HarmonyOS |
|---|---|---|---|---|---|
| 4.0 | 4.41 | 3.91 | 4.11 | 4.11 | 4.61 |
下载文件常见场景是apk的下载更新，app升级中心是一个现成的开源项目，实现下载进度在通知栏显示等复杂交互，可直接使用。
# 参数
| 名称 | 类型 | 必填 | 默认值 | 兼容性 | 描述 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| options | DownloadFileOptions | 是 | - | - | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
# DownloadFileSuccess 的属性值
| 名称 | 类型 | 必备 | 默认值 | 兼容性 | 描述 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| tempFilePath | string | 是 | - | 临时文件路径，下载后的文件会存储到一个临时文件 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| statusCode | number | 是 | - | 开发者服务器返回的 HTTP 状态码 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| filePath | string | 否 | - | 用户文件路径 (本地路径)。传入 filePath 时会返回，跟传入的 filePath 一致 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| profile | DownloadFileSuccessProfile | 否 | - | 需要基础库： 2.10.4网络请求过程中一些调试信息，查看详细说明 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
# DownloadFileFail 的属性值
| 名称 | 类型 | 必备 | 默认值 | 兼容性 | 描述 | ||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| errCode | number | 是 | - | - | 错误码 | ||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||
| errSubject | string | 是 | - | - | 统一错误主题（模块）名称 | ||||||||||||||||||||||||||||||
| data | any | 否 | - | - | 错误信息中包含的数据 | ||||||||||||||||||||||||||||||
| cause | Error | 否 | - | - | 源错误信息，可以包含多个错误，详见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(): 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: DownloadFileProgressUpdateCallback): 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: OnProgressDownloadResult) => void | 是 | - | - |
# OnProgressDownloadResult 的属性值
| 名称 | 类型 | 必备 | 默认值 | 兼容性 | 描述 |
|---|---|---|---|---|---|
| progress | number | 是 | - | 下载进度百分比 | |
| totalBytesWritten | number | 是 | - | 已经下载的数据长度，单位 Bytes | |
| totalBytesExpectedToWrite | 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 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 style="margin: 10px;">
<text class="uni-hello-text">下载接口的Content-Disposition中的filename非法值例子</text>
<button type="primary" @tap="downloadErrorFilename">下载</button>
</view>
</view>
</view>
<!-- #ifdef APP -->
</scroll-view>
<!-- #endif -->
</template>
<script>
// #ifdef APP-ANDROID || APP-IOS || APP-HARMONY
import {
testInovkeDownloadFile,
CommonOptions
} from '@/uni_modules/test-invoke-network-api'
// #endif
export default {
data() {
return {
title: 'downloadFile',
imageSrc: '',
task: null as DownloadTask | null,
//自动化测试例专用
jest_result: false,
jest_callback_triggred: 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://qiniu-web-assets.dcloud.net.cn/unidoc/zh/uni-app.png",
success: (res) => {
console.log('downloadFile success, res is', res.tempFilePath)
self.imageSrc = res.tempFilePath;
},
fail: (err) => {
console.log('downloadFile fail, err is:', err)
},
complete: (res) => {
uni.hideLoading();
this.task = null;
}
});
this.task?.onProgressUpdate((update) => {
console.log("progress : ", update.progress);
})
},
downloadErrorFilename(){
uni.downloadFile({
url:"https://qiniu-web-assets.dcloud.net.cn/uni-app-x/static/file/test9.txt",
success: (res) => {
console.log('downloadFile success, res is', res.tempFilePath)
},
fail: (err) => {
console.log('downloadFile fail, err is:', err)
}
})
},
//自动化测试例专用
jest_downloadFile() {
uni.downloadFile({
url: "https://qiniu-web-assets.dcloud.net.cn/unidoc/zh/uni-app.png",
success: () => {
this.jest_result = true
this.jest_callback_triggred = true
},
fail: () => {
this.jest_result = false
this.jest_callback_triggred = true
}
});
},
jest_downloadFile_with_uni_env() {
uni.downloadFile({
url: "https://qiniu-web-assets.dcloud.net.cn/unidoc/zh/uni-app.png",
filePath: `${uni.env.CACHE_PATH}/a/b/`,
success: () => {
this.jest_result = true
this.jest_callback_triggred = true
},
fail: () => {
this.jest_result = false
this.jest_callback_triggred = true
}
});
},
jest_set_cookie() {
uni.request({
url: "https://request.dcloud.net.cn/api/http/header/setCookie",
method: "GET",
timeout: 6000,
sslVerify: false,
withCredentials: true,
firstIpv4: false,
success: () => {
this.jest_cookie_download(true)
},
fail: () => {
this.jest_result = false;
this.jest_callback_triggred = true
},
});
},
jest_delete_cookie() {
uni.request({
url: "https://request.dcloud.net.cn/api/http/header/deleteCookie",
method: "GET",
timeout: 6000,
sslVerify: false,
withCredentials: true,
firstIpv4: false,
success: () => {
this.jest_cookie_download(false)
},
fail: () => {
this.jest_result = false;
this.jest_callback_triggred = true
},
});
},
jest_cookie_download(needCookie : boolean) {
uni.downloadFile({
url: "https://request.dcloud.net.cn/api/http/header/download",
success: () => {
this.jest_result = needCookie ? true : false;
this.jest_callback_triggred = true
},
fail: () => {
this.jest_result = needCookie ? false : true;
}
});
},
jest_uts_module_invoked() {
// #ifdef APP-ANDROID || APP-IOS || APP-HARMONY
testInovkeDownloadFile({
success: (res : any) => {
this.jest_result = true
this.jest_callback_triggred = true
},
fail: (err : any) => {
this.jest_result = false
this.jest_callback_triggred = true
}
} as CommonOptions)
// #endif
},
jest_special_characters_download() {
uni.downloadFile({
url: "https://web-ext-storage.dcloud.net.cn/hello-uni-app-x/1789834995055525889-你好%23你好.png",
success: (res : DownloadFileSuccess) => {
this.jest_result = true;
this.jest_callback_triggred = true
},
fail: () => {
this.jest_result = false;
this.jest_callback_triggred = true
}
});
},
jest_download_call_timeout() {
uni.downloadFile({
url: "https://web-assets.dcloud.net.cn/video/sample/2minute-demo-10k.mp4",
timeout: 3000,
fail: () => {
this.jest_result = false;
}
})
setTimeout(() => {
this.jest_result = true;
}, 4000)
}
}
}
</script>
<style>
.img {
margin: 0 auto;
}
</style>
# 参见
- 相关 Bug
- 参见uni-app相关文档
- 微信小程序文档
- 支付宝小程序文档
- 百度小程序文档
- 抖音小程序文档
- 飞书小程序文档
- 钉钉小程序文档
- QQ小程序文档
- 快手小程序文档
- 京东小程序文档
- 华为快应用文档
- 360小程序文档
# 通用类型
# GeneralCallbackResult
| 名称 | 类型 | 必备 | 默认值 | 兼容性 | 描述 |
|---|---|---|---|---|---|
| errMsg | string | 是 | - | 错误信息 |
# tips
- 下载后的文件，如需分享或使用三方应用打开，在Android7上需要使用FileProvider。
- web端并不会将文件下载到文件系统内，而是保存在js的File对象内，以供其他接口（如canvas、uploadFile）使用
