tt.downloadFile

基础库版本 1.0.0 开始支持

客户端直接发起一个 HTTPS GET 请求,下载网络文件到本地临时目录。单次下载允许的最大文件为 50MB。网络相关的 API 在使用前需要配置域名白名单。请参考网络请求使用说明

注意:请在服务端响应的 header 中指定合理的 Content-Type 字段,以保证客户端正确处理文件类型。

语法

tt.downloadFile(options)

参数说明

options 为 Object 类型,属性如下:

属性名类型默认值必填说明最低支持版本
urlstring--文件地址1.0.0
headerobject--请求 Header1.0.0
successfunction--接口调用成功的回调函数1.0.0
failfunction--接口调用失败的回调函数1.0.0
completefunction--接口调用结束的回调函数(成功、失败都会执行)1.0.0

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

回调失败

Object 类型,属性如下:

参数参数类型说明最低支持版本
errMsgstring错误信息1.0.0

返回值

DownloadTask(下载任务对象),调用 tt.downloadFile 后返回的请求对象。

效果示例

扫码体验

请使用字节宿主APP扫码

代码示例

开发者工具中预览

<!-- index.ttml -->
<view>
  <progress percent="{{progress}}" />
  <button tt:else type="primary" bindtap="downloadImage">下载图片</button>
  <image tt:if="{{filePath}}" src="{{filePath}}" mode="aspectFit"></image>
</view>
Page({
  data: {
    progress: 0,
    filePath: "",
  },
  downloadImage() {
    let task = tt.downloadFile({
      url: "someurl",
      success: (res) => {
        if (res.statusCode === 200) {
          // 下载的图片存到本地的地址
          console.log("下载成功", res.tempFilePath);
          this.setData({
            filePath: res.tempFilePath,
          });
        }
      },
      fail: (res) => {
        console.log("下载失败", res.errMsg);
      },
    });

    task.onProgressUpdate((res) => {
      this.setData({
        // 更新下载的进度
        progress: res.progress,
      });
    });

    // 某些条件下中断请求
    if (someReason) {
      task.abort();
    }
  },
});

Bug & Tip

  • Tip:header 不支持设置 refereruser-agent 字段。
  • Tip:目前 tt.downloadFile 下载文件大小限制为 50M。
  • Tip:目前 tt.downloadFile 暂不支持多文件下载,一次只能下载一个文件。
  • Tip:线上版本只支持 HTTPS 协议的请求,测试版同时支持 HTTP 和 HTTPS 协议,请注意提审版本中的协议配置。
点击纠错
评价此篇文档