跳至主要內容

上传下载 request

上传下载 request

导入模块

import request from '@system.request'

API

download

方法

通过 HTTP/HTTPS 协议下载文件，options 参数的各字段功能为：

  • url：要访问的网站的网址 URL；
  • header：一个包含 HTTP 请求头信息的对象，键和值为字符串。典型的 HTTP 头部字段可以是 Authorization、Content-Type 等；
  • filename：存储下载文件的 URI，如：internal://files/download.txt；
  • callback：下载进度回调函数，下载时会多次调用此函数，progress 为下载的进度值，范围为 [0,100][0, 100]。

download() 方法返回一个 DownloadTask 对象，可用于等待下载完成或控制下载任务。

注意

请不要在 callback 函数中以下载进度达到 100%100\% 作为下载完成后的操作触发条件，详情请参考等待下载完成。

当前实现没有自动根据 url 解析 filename 参数属性，请务必填写 filename。

类型

DownloadTask

DownloadTask 是 download 方法的返回类型，它的签名为：

interface DownloadTask {
  complete: Promise<void>,
  cancel(): void
}

complete 属性是一个 Promise 对象，可用于等待下载完成。cancel() 方法用于取消正在进行的下载任务，如果下载已经完成，cancel() 方法没有效果。

等待下载完成

使用 DownloadTask.complete 等待下载完成，该 Promise 兑现（fulfilled）时会保证文件已写入完成，因此可以安全地进行下一步操作。相比之下，callback 的下载进度达到 100%100\% 也并不意味着文件写入完成，它仅适合用于 UI 进度显示等需求。

示例

这是从网络中下载一个文件的简单示例：

request.download({
  url: "http://www.rt-thread.com/service/rt-thread.txt",
  filename: "internal://tmp/rt-thread.txt",
})

可以通过 download() 方法返回值的 complete 属性来等待下载完成：

await request.download({
  url: "http://www.rt-thread.com/service/rt-thread.txt",
  filename: "internal://tmp/rt-thread.txt"
}).complete
console.log('download finished.')
Glyphix framework