qg.downloadFile

基础信息说明

功能概述：下载文件资源到本地，获取下载进度、响应头与结果

项目	说明
版本要求	无
前提条件	目标 URL 可访问、网络权限已配置
使用限制	Header 中不能设置 Referer；客户端直接发起 HTTPS GET 请求
相关教程	无

参数说明

qg.downloadFile(option)

属性名	类型	默认值（如有）	必填	说明
url	String	-	是	下载资源的 URL
header	Object	-	否	HTTP 请求 Header，Header 中不能设置 Referer
filePath	String	-	否	指定文件下载后存储的路径（未传入参数时保存为临时路径；内部映射为 savedUri）
success	Function	-	否	下载成功回调，参数详见“回调结果说明”
fail	Function	-	否	下载失败回调，参数详见“回调结果说明”
complete	Function	-	否	下载完成回调（成功或失败都会执行）

返回值说明

qg.downloadFile() 为同步接口，调用后立即返回 QGDownloadTask 实例。

属性名	类型	说明
downloadTask	QGDownloadTask	下载任务对象，用于监听进度、响应头与取消任务

QGDownloadTask 对象方法

方法名	类型	同步/异步	说明
abort()	Function	同步	中断下载任务
onProgressUpdate(cb)	Function	异步回调	订阅下载进度事件，回调参数为 { progress, totalBytesWritten, totalBytesExpectedToWrite }
offProgressUpdate(cb)	Function	同步	取消订阅对应的进度事件
onHeadersReceived(cb)	Function	异步回调	订阅响应头事件，回调参数为 { header }，比完成事件更早触发
offHeadersReceived(cb)	Function	同步	取消订阅对应的响应头事件

回调结果说明

success、fail、complete 以及 onProgressUpdate、onHeadersReceived 注册的回调均为异步事件，由底层下载任务在流程中触发。
触发时机如下：

success：下载完成后触发
fail：下载过程中发生错误触发
complete：下载流程结束后触发（成功或失败都会执行）
onProgressUpdate：下载过程中多次触发进度更新
onHeadersReceived：收到 HTTP 响应头时触发，早于完成事件

回调成功

success / complete 成功形态

属性名	类型	说明
statusCode	Number	HTTP 状态码（来自底层 data.code）
tempFilePath	String	下载文件的本地临时路径（来自底层 savedUri）

onProgressUpdate 回调

属性名	类型	说明
progress	Number	下载进度百分比（0-100）
totalBytesWritten	Number	已下载字节数
totalBytesExpectedToWrite	Number	预计需要下载的总字节数

onHeadersReceived 回调

属性名	类型	说明
header	Object	响应头字典（底层返回的 headers）

回调失败
fail / complete 失败形态

属性名	类型	说明
errMsg	String	错误描述（来自底层 data.data）

示例代码

// 基本下载示例
const task = qg.downloadFile({
  url: 'https://example.com/assets/sprite.png',
  header: { 'Accept': 'application/octet-stream' },
  success(res) {
    console.log('下载成功', res.statusCode, res.tempFilePath)
  },
  fail(err) {
    console.error('下载失败', err)
  },
  complete(res) {
    console.log('下载完成', res)
  }
})

// 如需中断下载
// task.abort()

注意事项

Header 中禁止设置 Referer。
并发下载时，建议通过不同任务分别绑定监听，避免回调交叉。

上一篇:数据请求

下一篇:上传

文档内容是否有帮助？

有帮助

无帮助