tt.downloadFile
收藏我的收藏
收藏基础库 1.0.0 开始支持本方法，这是一个异步方法。
下载文件资源到本地。客户端直接发起一个 HTTPS GET 请求，返回文件的本地临时路径 (本地路径）。
| 前提条件 | 无 |
| 业务背景 | 无 |
| 使用限制 | 基础库 2.42.0 开始，单次下载允许的最大文件为 200MB，此前版本下载最大上限为 50MB。 网络相关的 API 在使用前需要配置域名白名单。请参考网络请求。 |
| 注意事项 |
|
| 支持沙盒 | 否 |
| 相关教程 | 无 |
语法
tt.downloadFile(options)
参数说明
options 为 object 类型，属性如下：
| 属性名 | 类型 | 默认值 | 必填 | 说明 | 最低支持版本 |
|---|---|---|---|---|---|
| header | object | 否 | HTTP 请求的 header，详情见 header 说明 | 1.0.0 | |
| filePath | string | 否 | 指定文件下载后存储的路径 (本地路径)，如果不传下载后的文件会存储到一个临时文件 | 2.42.0 | |
| timeout | number | 否 | 指的是连接和获取数据的超时时间，单位为毫秒 | 2.42.0 | |
| url | string | 是 | 下载资源的 url | 1.0.0 | |
| success | function | 否 | 接口调用成功的回调函数 | 1.0.0 | |
| fail | function | 否 | 接口调用失败的回调函数 | 1.0.0 | |
| complete | function | 否 | 接口调用结束的回调函数（调用成功、失败都会执行） | 1.0.0 |
header 参数说明
- 网络请求 header 中的 referer 不可设置。 其固定格式为：https://tmaservice.developer.toutiao.com/?appid={appid}&version={appVersion}，其中 appid为小程序的 APPID，appVersion为小程序的版本号。
- 网络请求 header 中的 user-agent 不可设置。 其固定格式分为：
- iOS 系统：[系统user-agent] [宿主标识]/[宿主app版本] ToutiaoMicroApp/[基础库版本] webview/[插件版本]。
- Android 系统：[系统user-agent] [宿主标识]/[宿主app版本] ToutiaoMicroApp/[基础库版本] PluginVersion/[插件版本]。
回调成功
object 类型，属性如下：
| 属性名 | 类型 | 说明 | 最低支持版本 |
|---|---|---|---|
| tempFilePath | string | 临时文件路径 (本地 路径)。只在没传入 filePath 指定文件存储路径时返回 | 1.0.0 |
| filePath | string | 用户文件路径 (本地路径)。只有传入 filePath 时会返回，跟传入的 filePath 一致 | 2.42.0 |
| header | object | 开发者服务器返回的 HTTP Response Header | 1.0.0 |
| errMsg | string | "downloadFile:ok" | 1.0.0 |
| statusCode | string | 开发者服务器返回的 HTTP 状态码 | 1.0.0 |
| profile | object | 网络请求过程中一些调试信息，详情见 Profile 类型说明 | 2.42.0 |
profile 类型说明
object 类型，属性如下：
| 属性名 | 类型 | 说明 | 最低支持版本 |
|---|---|---|---|
| domainLookupStart | number | DNS 域名查询开始的时间，如果使用了本地缓存（即无 DNS 查询）或持久连接，则与 fetchStart 值相等 | 2.42.0 |
| domainLookupEnd | number | DNS 域名查询完成的时间，如果使用了本地缓存（即无 DNS 查询）或持久连接，则与 fetchStart 值相等 | 2.42.0 |
| connectStart | number | HTTP（TCP） 开始建立连接的时间，如果是持久连接，则与 fetchStart 值相等。注意如果在传输层发生了错误且重新建立连接，则这里显示的是新建立的连接开始的时间 | 2.42.0 |
| connectEnd | number | HTTP（TCP） 完成建立连接的时间（完成握手），如果是持久连接，则与 fetchStart 值相等。注意如果在传输层发生了错误且重新建立连接，则这里显示的是新建立的连接完成的时间。注意这里握手结束，包括安全连接建立完成、SOCKS 授权通过 | 2.42.0 |
| sslConnectionStart | number | SSL 建立连接的时间，如果不是安全连接，则值为 0 | 2.42.0 |
| sslConnectionEnd | number | SSL 建立完成的时间，如果不是安全连接，则值为 0 | 2.42.0 |
| requestStart | number | HTTP 请求读取真实文档开始的时间（完成建立连接），包括从本地读取缓存。连接错误重连时，这里显示的也是新建立连接的时间 | 2.42.0 |
| requestEnd | number | HTTP 请求读取真实文档结束的时间 | 2.42.0 |
| rtt | number | 当次请求连接过程中实时 rtt | 2.42.0 |
| estimateNetType | string | 评估的网络状态 unknown, offline, slow 2g, 2g, 3g, 4g, last/0, 1, 2, 3, 4, 5, 6 | 2.42.0 |
| throughputKbps | number | 当前网络的实际下载 kbps | 2.42.0 |
| port | number | 当前请求的端口 | 2.42.0 |
| socketReused | boolean | 是否复用连接 | 2.42.0 |
| sentBytesCount | number | 发送的字节数 | 2.42.0 |
| receivedBytesCount | number | 收到的字节数 | 2.42.0 |
回调失败
object 类型，属性如下：
| 属性名 | 类型 | 说明 | 最低支持版本 |
|---|---|---|---|
| errMsg | string | "downloadFile:fail" + 详细错误信息 | 1.0.0 |
返回值
| 类型 | 说明 | 最低支持版本 |
|---|---|---|
| object | 1.0.0 |
错误码
| errorCode | errMsg | errorType | 说明 | 最低支持版本 |
|---|---|---|---|---|
| 121599 | url use invalid protocol, url == %s, url support protocol is %s | D | url协议无效 | 1.0.0 |
| 121599 | url is invalid, url == %s | D | url不合法 | 1.0.0 |
| 121591 | network error:%s | F | 小程序框架内部错误，有需要请拉客服咨询 | 1.0.0 |
| 121501 | url not in domain list, url == %s | D | url域名不在download域名列表中 | 1.0.0 |
| 121502 | no such file or directory, '%s' | D | 文件不存在 | 1.0.0 |
| 121530 | user dir saved file size limit exceeded | D | user目录超出限制 | 1.0.0 |
| 121521 | file size exceeds 200MB | D | 下载文件超出限制 | 1.0.0 |
| 121520 | request time out | D | 请求超时 | 1.0.0 |
| 121503 | file path permission denied, open '%s' | D | 文件路径没有写权限 | 1.0.0 |
| 121507 | %s | F | 小程序框架内部错误，有需要请拉客服咨询 | 1.0.0 |
| 121508 | destination path has error | D | 目标路经有误 | 1.0.0 |
| 121585 | network unavailable | U | 用户无网 | 1.0.0 |
| 121585 | network unavailable | U | 用户无网或抖音没有网络权限 | 1.0.0 |
| 121522 | download file abort | U | 主动中断请求 | 1.0.0 |
| 121523 | network changed | U | 用户网络波动 | 1.0.0 |
| 121524 | dns error | U | 用户网络波动 | 1.0.0 |
| 121525 | ssl error | U | 用户网络波动 | 1.0.0 |
| 121526 | connection error | U | 用户网络波动 | 1.0.0 |
| 121527 | interrupted | U | 用户网络波动 | 1.0.0 |
| 121528 | certificate error | D | url证书错误 | 1.0.0 |
| 121529 | url error | D | url无效 | 1.0.0 |
| 121594 | app in background | U | 小程序已进入后台 | 1.0.0 |
| 121592 | %s | F | 小程序框架内部错误，有需要请拉客服咨询 | 1.0.0 |
| 121503 | request:fail abort | D | 主动中断 | 1.0.0 |
扫码体验
代码示例
<button bindtap="downloadImage" type="primary">下载图片</button> <image tt:if="{{imageSrc}}" src="{{imageSrc}}" mode="center" />
Page({ data: { imageSrc: "", }, downloadImage() { tt.downloadFile({ url: "https://s3.pstatp.com/toutiao/static/img/logo.201f80d.png", header: { "content-type": "application/json", }, success: (res) => { console.log("downloadFile success", res); tt.showToast({ title: res.errMsg, icon: "success", }); this.setData({ imageSrc: res.tempFilePath, }); }, fail: (res) => { console.log("downloadFile fail", res); tt.showToast({ title: res.errMsg, icon: "none", }); }, complete: (res) => { console.log("downloadFile complete", res); }, }); }, });
