抖音开放平台Logo
控制台

tt.downloadFile
收藏
我的收藏

基础库 1.0.0 开始支持本方法，这是一个异步方法。

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

前提条件无
业务背景无
使用限制

基础库 2.42.0 开始，单次下载允许的最大文件为 200MB，此前版本下载最大上限为 50MB。

网络相关的 API 在使用前需要配置域名白名单。请参考网络请求。

注意事项
  • Tip：请在服务端响应的 header 中指定合理的 Content-Type 字段，以保证客户端正确处理文件类型；
  • Tip：header 不支持设置 referer、user-agent 字段；
  • Tip：基础库 2.42.0 开始，单次下载允许的最大文件为 200MB，此前版本下载最大上限为 50MB；
  • Tip：目前 tt.downloadFile 暂不支持多文件下载，一次只能下载一个文件；
  • Tip：线上版本只支持 HTTPS 协议的请求，测试版同时支持 HTTP 和 HTTPS 协议，请注意提审版本中的协议配置；
  • Tip：网络请求 referer 请参考小程序网络请求特性。
支持沙盒
否
相关教程无

语法

tt.downloadFile(options)

参数说明

options 为 object 类型，属性如下：

属性名类型默认值必填说明最低支持版本
headerobject否
HTTP 请求的 header，详情见 header 说明
1.0.0
filePathstring否

指定文件下载后存储的路径 (本地路径)，如果不传下载后的文件会存储到一个临时文件​

2.42.0
timeoutnumber否

指的是连接和获取数据的超时时间，单位为毫秒​

2.42.0
urlstring是
下载资源的 url
1.0.0
successfunction否
接口调用成功的回调函数
1.0.0
failfunction否
接口调用失败的回调函数
1.0.0
completefunction否
接口调用结束的回调函数（调用成功、失败都会执行）
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 类型，属性如下：

属性名类型说明最低支持版本
tempFilePathstring

临时文件路径 (本地路径)。只在没传入 filePath 指定文件存储路径时返回​

1.0.0
filePathstring

用户文件路径 (本地路径)。只有传入 filePath 时会返回，跟传入的 filePath 一致

2.42.0
headerobject

开发者服务器返回的 HTTP Response Header​

1.0.0
errMsgstring
"downloadFile:ok"
1.0.0
statusCodestring

开发者服务器返回的 HTTP 状态码

1.0.0
profileobject

网络请求过程中一些调试信息，详情见 Profile 类型说明

2.42.0

profile 类型说明

object 类型，属性如下：

属性名类型说明最低支持版本
domainLookupStartnumber

DNS 域名查询开始的时间，如果使用了本地缓存（即无 DNS 查询）或持久连接，则与 fetchStart 值相等​

2.42.0
domainLookupEndnumber

DNS 域名查询完成的时间，如果使用了本地缓存（即无 DNS 查询）或持久连接，则与 fetchStart 值相等​

2.42.0
connectStartnumber

HTTP（TCP） 开始建立连接的时间，如果是持久连接，则与 fetchStart 值相等。注意如果在传输层发生了错误且重新建立连接，则这里显示的是新建立的连接开始的时间​

2.42.0
connectEndnumber

HTTP（TCP） 完成建立连接的时间（完成握手），如果是持久连接，则与 fetchStart 值相等。注意如果在传输层发生了错误且重新建立连接，则这里显示的是新建立的连接完成的时间。注意这里握手结束，包括安全连接建立完成、SOCKS 授权通过​

2.42.0
sslConnectionStartnumber

SSL 建立连接的时间，如果不是安全连接，则值为 0​

2.42.0
sslConnectionEndnumber

SSL 建立完成的时间，如果不是安全连接，则值为 0​

2.42.0
requestStartnumber

HTTP 请求读取真实文档开始的时间（完成建立连接），包括从本地读取缓存。连接错误重连时，这里显示的也是新建立连接的时间​

2.42.0
requestEndnumber

HTTP 请求读取真实文档结束的时间​

2.42.0
rttnumber

当次请求连接过程中实时 rtt​

2.42.0
estimateNetTypestring

评估的网络状态 unknown, offline, slow 2g, 2g, 3g, 4g, last/0, 1, 2, 3, 4, 5, 6​

2.42.0
throughputKbpsnumber

当前网络的实际下载 kbps​

2.42.0
portnumber

当前请求的端口​

2.42.0
socketReusedboolean

是否复用连接​

2.42.0
sentBytesCountnumber

发送的字节数

2.42.0
receivedBytesCountnumber

收到的字节数​

2.42.0

回调失败

object 类型，属性如下：

属性名类型说明最低支持版本
errMsgstring
"downloadFile:fail" + 详细错误信息
1.0.0

返回值

类型说明最低支持版本
object

DownloadTask

1.0.0

错误码

errorCodeerrMsgerrorType说明最低支持版本
121599url use invalid protocol, url == %s, url support protocol is %sD
url协议无效
1.0.0
121599url is invalid, url == %sD
url不合法
1.0.0
121591network error:%sF
小程序框架内部错误，有需要请拉客服咨询
1.0.0
121501url not in domain list, url == %sD
url域名不在download域名列表中
1.0.0
121502no such file or directory, '%s'D
文件不存在
1.0.0
121530user dir saved file size limit exceededD
user目录超出限制
1.0.0
121521file size exceeds 200MBD
下载文件超出限制
1.0.0
121520request time outD
请求超时
1.0.0
121503file path permission denied, open '%s'D
文件路径没有写权限
1.0.0
121507%s F
小程序框架内部错误，有需要请拉客服咨询
1.0.0
121508destination path has errorD
目标路经有误
1.0.0
121585network unavailableU
用户无网
1.0.0
121585network unavailableU
用户无网或抖音没有网络权限
1.0.0
121522download file abortU
主动中断请求
1.0.0
121523network changedU
用户网络波动
1.0.0
121524dns errorU
用户网络波动
1.0.0
121525ssl errorU
用户网络波动
1.0.0
121526connection errorU
用户网络波动
1.0.0
121527interruptedU
用户网络波动
1.0.0
121528certificate errorD
url证书错误
1.0.0
121529url errorD
url无效
1.0.0
121594app in backgroundU
小程序已进入后台
1.0.0
121592%sF
小程序框架内部错误，有需要请拉客服咨询
1.0.0
121503request:fail abortD
主动中断
1.0.0

扫码体验

请使用字节宿主APP扫码

代码示例

开发者工具中预览

<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);
      },
    });
  },
});