For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt, and this page is available as Markdown at /apps-plugin/docs/js-api/network/downloadFile.md.

downloadFile

下载文件,并返回可取消、可监听进度的 DownloadTask。

扫码预览

扫码预览 downloadFile

支持版本

前端库版本不低于 0.0.40。

支持平台

平台支持情况
Android支持
iOS支持
PC不支持
HarmonyOS不支持

支持场景

场景支持情况
页面支持
卡片不支持

接入准备

前置条件

  • 下载地址需通过豆包配置的下载域名白名单校验,单个文件不得超过 200 MB,单个应用插件同时最多执行 10 个下载任务;指定 filePath 时仅支持临时目录或用户目录

使用说明

  • 下载使用 GET 请求。

  • HTTP 传输完成且文件写入成功后,无论 statusCode 是 2xx、4xx 还是 5xx,Promise 都会 resolve。

  • 域名校验失败、路径非法、超时、取消、网络异常、写入失败会使 Promise reject。

  • 未指定 filePath 时文件写入临时目录,并通过 Promise resolve 结果的 tempFilePath 返回;临时文件的生命周期由豆包客户端管理。

  • 不跟随 HTTP 重定向,3xx 响应使 Promise reject;4xx、5xx 响应在文件写入成功后仍使 Promise resolve。

调用方式

异步 API

downloadFile(params: DownloadFileParams): DownloadTask

入参

名称类型必填默认值约束说明
filePathstring否由系统创建临时下载文件-目标文件路径,仅支持 `appletfile://temp/...` 或 `appletfile://user/...`。
headerRecord<string, string>否--请求 Header。`referer` 和 `user-agent` 由豆包客户端管理,业务传入值不会透传。
timeoutnumber否60000有效范围为 1-300000下载任务超时时间,单位 ms;不传或传入非正数时使用 60000,超过 300000 时按 300000 处理。
urlstring是--下载资源地址,需为完整 HTTPS URL,并通过豆包配置的下载域名白名单校验。

调用示例

import { downloadFile } from '@doubao-dev/framework/api';

const downloadTask = downloadFile({
  url: 'https://example.com/files/report.pdf'
});

downloadTask
  .then((result) => {
    console.log(result.statusCode, result.tempFilePath ?? result.filePath);
  })
  .catch((error) => {
    console.error(error);
  })
  .finally(() => {
    console.log('download finished');
  });

downloadTask.onProgressUpdate((event) => {
  console.log(`downloaded ${event.progress}%`);
});

downloadTask.onHeadersReceived((event) => {
  console.log(event.header);
});

成功返回

名称类型必返说明
filePathstring否指定 `filePath` 时返回的目标文件路径。
headerRecord<string, string>是HTTP 响应头。
statusCodenumber是HTTP 状态码。非 2xx 响应也会在下载写入成功后返回。
tempFilePathstring否未指定 `filePath` 时返回的临时文件路径。

返回示例

{
  "statusCode": 200,
  "header": {
    "content-type": "application/pdf"
  },
  "tempFilePath": "appletfile://temp/report.pdf"
}