抖音开放平台Logo
开发者文档
“/”唤起搜索
控制台
  • API 概览
  • C# API
  • 开放接口
  • 收藏
  • 群聊
  • 广告
  • 关注
  • 数据分析
  • 基础
  • 渲染
  • 设备
  • 文件
  • 位置
  • 媒体
  • 网络
  • 发起请求
  • 下载
  • tt.downloadFile
  • DownloadTask
  • 上传
  • Websocket
  • 转发
  • 数据缓存
  • 广告
  • 界面
  • 支付
  • Worker
  • tt.downloadFile
    收藏
    我的收藏

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

    客户端直接发起一个 HTTPS GET 请求,下载网络文件到本地临时目录。​

    前提条件

    网络相关的 API 在使用前需要配置域名白名单,详细说明。​

    业务背景
    使用限制
    • header 不支持设置 refereruser-agent 字段。
    • 目前 tt.downloadFile 暂不支持多文件下载,一次只能下载一个文件。​
    注意事项
    • ​iOS系统从 2.21.0(包含)版本开始, 单次下载允许的最大文件为 50MB 提升到 200M,安卓侧依然是50MB。​
    • 请在服务端响应的 header 中指定合理的 Content-Type 字段,以保证客户端正确处理文件类型。​
    相关教程

    语法

    tt.downloadFile(options)

    参数说明

    options 为 object 类型,属性如下:

    属性名类型默认值必填说明最低支持版本
    urlstring
    文件地址
    1.0.0
    headerobject
    请求 Header
    1.0.0
    timeoutnumber

    接口超时时间,单位为毫秒,不传默认取 game.json 中的 networkTimeout 配置

    3.83.0
    enableProfilebooleantrue

    是否开启 profile,默认开启。开启后可在接口回调的 res.profile 中查看性能调试信息。PC 未支持该能力,请使用真机调试。

    3.83.0
    successfunction
    接口调用成功的回调函数
    1.0.0
    failfunction
    接口调用失败的回调函数
    1.0.0
    completefunction
    接口调用结束的回调函数(调用成功、失败都会执行)
    1.0.0

    header 参数说明

    referer

    请求 header 中的 referer 不可设置。

    其固定格式为:https://tmaservice.developer.toutiao.com?appid={appid}&version={appVersion},其中 appid为小游戏的 APPID,appVersion为小游戏的版本号。

    user-agent

    请求 header 中的 user-agent 不可设置。

    其固定格式分为:

    • IOS 系统:[系统user-agent] [宿主标识]/[宿主app版本] ToutiaoMicroApp/[基础库版本] webview/[插件版本]
    • Android 系统:[系统user-agent] [宿主标识]/[宿主app版本] ToutiaoMicroApp/[基础库版本] PluginVersion/[插件版本]

    回调成功

    object 类型,属性如下:

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

    文件本地路径,下载的文件会存放在临时目录

    1.0.0
    statusCodenumber

    返回 HTTP 状态码

    1.0.0

    返回值

    类型说明最低支持版本
    object1.0.0

    扫码体验

    请使用字节宿主APP扫码

    代码示例

    开发者工具中预览

    let task = tt.downloadFile({ url: "somefileurl", success(res) { if (res.statusCode === 200) { console.log(`${res.tempFilePath}`); } }, fail(res) { console.log(`downloadFile调用失败`); }, }); task.onProgressUpdate((res) => { this.setData({ progress: res.progress, }); }); if (someReason) { task.abort(); }