request部件主要给应用提供上传下载文件、后台传输代理的基础能力。
request的cacheDownload子组件主要给应用提供应用资源提前缓存的基础能力。
cacheDownload组件使用HTTP和HTTPS协议进行数据下载,并将数据资源缓存至应用内存或应用沙箱目录的指定文件中。
这些缓存数据可以被特定的ArkUI组件(例如:Image组件)使用,从而提升资源加载效率。请查看ArkUI组件文档确定组件是否支持该功能。
本模块首批接口从API version 18开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
表示安全通信协议的枚举。
系统能力:SystemCapability.Request.FileTransferAgent
| 名称 | 值 | 说明 |
|---|---|---|
| TLS | 'TLS' | 使用TLS安全通信协议。 |
| TLCP | 'TLCP' | 使用TLCP安全通信协议。 |
表示错误返回信息的特定类型枚举。
系统能力:SystemCapability.Request.FileTransferAgent
| 名称 | 值 | 说明 |
|---|---|---|
| OTHERS | 0xFF | 表示未分类的其他类型错误。 |
| DNS | 0x00 | 表示DNS相关错误。 |
| TCP | 0x10 | 表示TCP相关错误。 |
| SSL | 0x20 | 表示SSL相关错误。 |
| HTTP | 0x30 | 表示HTTP相关错误。 |
表示缓存刷新策略的枚举。
系统能力:SystemCapability.Request.FileTransferAgent
| 名称 | 值 | 说明 |
|---|---|---|
| FORCE | 0 | 强制更新缓存,无论缓存是否已经存在。 |
| LAZY | 1 | 延迟更新缓存,只有当缓存不存在时才会更新。 |
任务超时配置选项。包括检查网络可用的超时时间和完成HTTP请求的超时时间。
起始版本: 26.0.0
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.Request.FileTransferAgent
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| networkCheckTimeout | number | 否 | 是 | 检查网络可用的超时时间,单位为秒。默认值为20,最小值为0(取值为0时表示不进行网络可用检查),最大值为20,超出取值范围时抛出异常。 检查网络需要权限:ohos.permission.GET_NETWORK_INFO,无权限时网络检查失败直到超时。 |
| httpTotalTimeout | number | 否 | 是 | 完成HTTP请求的超时时间,单位为秒。默认值为60,最小值为1,最大值为4294967 |
任务重试配置选项。设置任务的最大重试次数。
起始版本: 26.0.0
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.Request.FileTransferAgent
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| maxRetryCount | number | 否 | 是 | 任务失败时的最大重试次数。默认值为1,最小值为0,最大值为10,超出取值范围时抛出异常。 |
缓存下载的配置选项。包括HTTP选项、传输选项和任务选项。
系统能力:SystemCapability.Request.FileTransferAgent
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| headers | Record<string, string> | 否 | 是 | 缓存下载任务在HTTP传输时使用的请求头。默认值为空。 |
| sslType21+ | SslType | 否 | 是 | 使用安全通信协议TLS或TLCP,默认使用TLS。当前TLS和TLCP均不支持双向认证。 |
| caPath21+ | string | 否 | 是 | CA证书路径。目前仅支持.pem格式证书,默认使用系统预设的CA证书。 |
| cacheStrategy23+ | CacheStrategy | 否 | 是 | 使用缓存刷新策略FORCE或LAZY,默认使用FORCE。 |
| retry | RetryOptions | 否 | 是 | 任务的重试配置,用于为单个任务自定义重试行为。当需要为该任务单独指定重试次数时设置;不设置时回退到全局重试配置(setGlobalRetryOptions),再回退到默认值(maxRetryCount默认为1)。 起始版本: 26.0.0 模型约束: 此接口仅可在Stage模型下使用 |
| timeout | TimeoutOptions | 否 | 是 | 任务的超时配置,用于为单个任务自定义超时行为。当需要为该任务单独指定网络检查超时或HTTP请求超时时设置;不设置时回退到全局超时配置(setGlobalTimeoutOptions),再回退到默认值(networkCheckTimeout默认为20、httpTotalTimeout默认为60)。 起始版本: 26.0.0 模型约束: 此接口仅可在Stage模型下使用 |
预下载的资源信息。
系统能力:SystemCapability.Request.FileTransferAgent
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| size | number | 是 | 否 | 预下载资源解压后的大小,单位为字节(B)。当值为正整数时表示资源下载成功,-1表示下载失败。 |
预下载的网络信息。
系统能力:SystemCapability.Request.FileTransferAgent
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| dnsServers | string[] | 是 | 否 | 下载资源时使用的DNS服务器列表。 |
| ip23+ | string | 是 | 是 | 下载资源时url的IP地址。当DNS解析失败时,IP为undefined。 |
预下载的性能信息。
系统能力:SystemCapability.Request.FileTransferAgent
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| dnsTime | number | 是 | 否 | 从启动到DNS解析完成所需的时间,单位:毫秒(ms)。 |
| connectTime | number | 是 | 否 | 从启动到TCP连接完成所需的时间,单位:毫秒(ms)。 |
| tlsTime | number | 是 | 否 | 从启动到TLS连接完成所需的时间,单位:毫秒(ms)。 |
| firstSendTime | number | 是 | 否 | 从启动到开始发送第一个字节所需的时间,单位:毫秒(ms)。 |
| firstReceiveTime | number | 是 | 否 | 从启动到接收第一个字节所需的时间,单位:毫秒(ms)。 |
| totalTime | number | 是 | 否 | 从启动到完成请求所需的时间,单位:毫秒(ms)。 |
| redirectTime | number | 是 | 否 | 从启动到完成所有重定向步骤所需的时间,单位:毫秒(ms)。 |
预下载的下载信息。
系统能力:SystemCapability.Request.FileTransferAgent
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| resource | ResourceInfo | 是 | 否 | 预下载的资源信息。 |
| network | NetworkInfo | 是 | 否 | 预下载的网络信息。 |
| performance | PerformanceInfo | 是 | 否 | 预下载的性能信息。 |
download(url: string, options: CacheDownloadOptions): void
启动一个缓存下载任务,若传输成功,则将数据下载到内存缓存和文件缓存中。
目标资源经过HTTP传输自动解压后的大小不能超过20971520B(即20MB),否则不会保存到内存缓存或文件缓存中。
在缓存下载数据时,缓存刷新行为由cacheStrategy决定:使用FORCE(默认)策略时,如果在该url下已存在缓存内容,新的缓存内容会覆盖旧缓存内容;使用LAZY策略时,仅当缓存不存在时才会更新缓存。
目标资源在存储到内存缓存或文件缓存中时,依照缓存下载组件的各类型缓存大小上限决定文件是否存储到指定位置,并默认使用“LRU”(最近最少使用)方式替换已有缓存内容。
该方法为同步方法,不阻塞调用线程。
需要权限:ohos.permission.INTERNET
系统能力:SystemCapability.Request.FileTransferAgent
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| url | string | 是 | 目标资源的地址。支持HTTP和HTTPS协议,长度不超过8192字节。 |
| options | CacheDownloadOptions | 是 | 目标资源的缓存下载选项。 |
错误码:
以下错误码的详细介绍请参见通用错误码说明文档。
| 错误码ID | 错误信息 |
|---|---|
| 201 | permission denied. |
| 401 | parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |
示例:
import { cacheDownload, BusinessError } from '@kit.BasicServicesKit';
// 提供缓存下载任务的配置选项。
let options: cacheDownload.CacheDownloadOptions = {
headers: { 'Accept': 'application/json' },
sslType: cacheDownload.SslType.TLS,
caPath: '/path/to/ca.pem',
cacheStrategy: cacheDownload.CacheStrategy.FORCE,
retry: { maxRetryCount: 1 },
timeout: {
networkCheckTimeout: 20,
httpTotalTimeout: 60,
}
};
try {
// 进行缓存下载,资源若下载成功会被缓存到应用内存或应用沙箱目录的特定文件中。
cacheDownload.download("https://www.example.com", options);
} catch (error) {
let err: BusinessError = error as BusinessError;
console.error(`Failed to download the resource. err code: ${err.code}, err message: ${err.message}`);
} cancel(url: string): void
根据url移除一个正在执行的缓存下载任务,已保存的内存缓存和文件缓存不会受到影响。
当不存在对应url的任务时无其他效果。
使用该方法同步执行时,不阻塞调用线程。
系统能力:SystemCapability.Request.FileTransferAgent
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| url | string | 是 | 目标资源的地址。支持HTTP和HTTPS协议,长度不超过8192字节。 |
错误码:
以下错误码的详细介绍请参见通用错误码说明文档。
| 错误码ID | 错误信息 |
|---|---|
| 401 | parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |
示例:
import { cacheDownload, BusinessError } from '@kit.BasicServicesKit';
// 提供缓存下载任务的配置选项。
let options: cacheDownload.CacheDownloadOptions = {};
try {
// 进行缓存下载,资源若下载成功会被缓存到应用内存或应用沙箱目录的特定文件中。
cacheDownload.download("https://www.example.com", options);
} catch (error) {
let err: BusinessError = error as BusinessError;
console.error(`Failed to download the resource. err code: ${err.code}, err message: ${err.message}`);
}
// 处理其他业务逻辑。
try {
// 在不需要特定任务缓存时,移除缓存下载任务,已缓存的内容不受影响。
cacheDownload.cancel("https://www.example.com");
} catch (error) {
let err: BusinessError = error as BusinessError;
console.error(`Failed to cancel the task. err code: ${err.code}, err message: ${err.message}`);
} setMemoryCacheSize(bytes: number): void
设置缓存下载组件能够保存的内存缓存上限。
使用该接口调整缓存大小时,默认使用"LRU"(最近最少使用)方式清除多余的已缓存的内存缓存内容。使用该接口时,若bytes设置为0,将清除所有已缓存的内存缓存内容。
该方法为同步方法,不阻塞调用线程。
系统能力:SystemCapability.Request.FileTransferAgent
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| bytes | number | 是 | 设置的缓存上限。默认值为0B,最小值为0,最大值不超过1073741824B(即1GB)。若bytes设置为0,将清除所有已缓存的内存缓存内容。 |
错误码:
以下错误码的详细介绍请参见通用错误码说明文档。
| 错误码ID | 错误信息 |
|---|---|
| 401 | parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |
示例:
import { cacheDownload, BusinessError } from '@kit.BasicServicesKit';
try {
// 设置内存缓存大小上限。
cacheDownload.setMemoryCacheSize(10 * 1024 * 1024);
} catch (error) {
let err: BusinessError = error as BusinessError;
console.error(`Failed to set memory cache size. err code: ${err.code}, err message: ${err.message}`);
} setFileCacheSize(bytes: number): void
设置缓存下载组件能够保存的文件缓存的上限。
使用该接口调整缓存大小时,默认使用“LRU”(最近最少使用)方式清除多余的已缓存的文件缓存内容。
使用该接口时,若bytes设置为0,将会删除所有缓存文件。
该方法为同步方法,不会阻塞调用线程。
系统能力:SystemCapability.Request.FileTransferAgent
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| bytes | number | 是 | 设置的缓存上限。默认值为104857600B(即100MB),最小值为0,最大值不超过4294967296B(即4GB)。 |
错误码:
以下错误码的详细介绍请参见通用错误码说明文档。
| 错误码ID | 错误信息 |
|---|---|
| 401 | parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. |
示例:
import { cacheDownload, BusinessError } from '@kit.BasicServicesKit';
try {
// 设置文件缓存大小上限。
cacheDownload.setFileCacheSize(100 * 1024 * 1024);
} catch (error) {
let err: BusinessError = error as BusinessError;
console.error(`Failed to set file cache size. err code: ${err.code}, err message: ${err.message}`);
}
>
setDownloadInfoListSize(size: number): void
设置下载信息列表的大小。
下载信息列表用于存储预下载信息。
下载信息和url一一对应,每次预下载都会生成一个下载信息,相同url下只会保存最新的下载信息。
使用该接口调整列表大小时,若size增大,列表中原有的信息不变;若size减小,默认使用"LRU"(最近最少使用)方式清除多余的已缓存信息。
系统能力:SystemCapability.Request.FileTransferAgent
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| size | number | 是 | 设置的下载信息列表大小。取值范围:[0, 8192],默认为0,表示不会存储任何下载信息。超出取值范围时抛出异常。 |
示例:
import { cacheDownload, BusinessError } from '@kit.BasicServicesKit';
try {
// 设置下载信息列表大小。
cacheDownload.setDownloadInfoListSize(2048);
} catch (error) {
let err: BusinessError = error as BusinessError;
console.error(`Failed to set download information list size. err code: ${err.code}, err message: ${err.message}`);
} getDownloadInfo(url: string): DownloadInfo | undefined
基于url获取预下载的下载信息。信息存储在内存中的下载信息列表,当应用程序退出时清除。需先调用setDownloadInfoListSize设置列表大小(大于0)后,预下载信息才会被存储到列表中,否则列表默认大小为0,不存储任何下载信息,getDownloadInfo将返回undefined。
如果下载信息列表中能够找到指定url,返回该url对应的最新DownloadInfo。
如果下载信息列表中找不到指定url,返回undefined。
在缓存下载信息时,如果在该url下已存在缓存信息,新的缓存内容会覆盖旧缓存。
目标信息在存储到内存时,使用“LRU”(最近最少使用)方式替换已存在的缓存数据。
需要权限:ohos.permission.GET_NETWORK_INFO
系统能力:SystemCapability.Request.FileTransferAgent
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| url | string | 是 | 待查询的url,支持HTTP和HTTPS协议,最大长度为8192字节,超出长度限制时抛出异常。 |
返回值:
| 类型 | 说明 |
|---|---|
| DownloadInfo | undefined | 返回对应url的下载信息,url未记录时返回undefined。 |
错误码:
以下错误码的详细介绍请参见通用错误码说明文档。
| 错误码ID | 错误信息 |
|---|---|
| 201 | permission denied. |
示例:
import { cacheDownload, BusinessError } from '@kit.BasicServicesKit';
try {
// 设置下载信息列表大小。
cacheDownload.setDownloadInfoListSize(2048);
} catch (error) {
let err: BusinessError = error as BusinessError;
console.error(`Failed to set download information list size. err code: ${err.code}, err message: ${err.message}`);
}
// 提供缓存下载任务的配置选项。
let options: cacheDownload.CacheDownloadOptions = {};
try {
// 进行缓存下载,资源若下载成功会被缓存到应用内存或应用沙箱目录的特定文件中。
cacheDownload.download("https://www.example.com", options);
} catch (error) {
let err: BusinessError = error as BusinessError;
console.error(`Failed to download the resource. err code: ${err.code}, err message: ${err.message}`);
}
// 处理其他业务逻辑。
try {
// 在缓存下载完成后,获取缓存下载的信息。
let downloadInfo = cacheDownload.getDownloadInfo("https://www.example.com");
if (downloadInfo == undefined) {
console.error(`CacheDownload get download info undefined.`);
} else {
console.info(`CacheDownload get download info : ${JSON.stringify(downloadInfo)}`);
}
} catch (error) {
let err: BusinessError = error as BusinessError;
console.error(`Failed to get download info. err code: ${err.code}, err message: ${err.message}`);
} clearMemoryCache(): void
清除缓存下载内容的内存缓存。
系统能力:SystemCapability.Request.FileTransferAgent
示例:
import { cacheDownload } from '@kit.BasicServicesKit';
cacheDownload.clearMemoryCache(); clearFileCache(): void
清除保存下载内容的文件缓存。
系统能力:SystemCapability.Request.FileTransferAgent
示例:
import { cacheDownload } from '@kit.BasicServicesKit';
cacheDownload.clearFileCache(); onDownloadSuccess(url: string, callback: Callback<void>): void
订阅预下载的完成事件。使用callback异步回调。与offDownloadSuccess()方法配合使用,在不再需要接收完成事件时应调用offDownloadSuccess()取消订阅,以避免不必要的回调开销。
系统能力:SystemCapability.Request.FileTransferAgent
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| url | string | 是 | 待注册回调的url,支持HTTP和HTTPS协议,url字符串的最大长度为8192字节,超出长度限制时抛出异常。 |
| callback | Callback<void> | 是 | 下载成功时触发的回调函数,无回调参数。 |
示例:
import { cacheDownload, BusinessError } from '@kit.BasicServicesKit';
try {
const successCallback = () => {
console.info("Succeeded in getting callback from cacheDownload");
};
// 订阅预下载的完成事件,当下载完成时执行回调
cacheDownload.onDownloadSuccess("https://www.example.com", successCallback);
// 进行缓存下载,资源若下载成功会被缓存到应用内存或应用沙箱目录的特定文件中。
cacheDownload.download("https://www.example.com", {});
} catch (error) {
let err: BusinessError = error as BusinessError;
console.error(`Failed to download the resource. err code: ${err.code}, err message: ${err.message}`);
} onDownloadError(url: string, callback: Callback<DownloadError>): void
订阅预下载的错误事件。使用callback异步回调。与offDownloadError()方法配合使用,在不再需要接收错误事件时应调用offDownloadError()取消订阅,以避免不必要的回调开销。
系统能力:SystemCapability.Request.FileTransferAgent
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| url | string | 是 | 待注册回调的url,支持HTTP和HTTPS协议,url字符串的最大长度为8192字节,超出长度限制时抛出异常。 |
| callback | Callback<DownloadError> | 是 | 回调函数,返回预下载的错误信息。 |
示例:
import { cacheDownload, BusinessError } from '@kit.BasicServicesKit';
try {
const errorCallback = (error: cacheDownload.DownloadError) => {
console.error(`Error callback from cacheDownload. error code: ${error.errorCode}, error message: ${error.message}`);
};
// 订阅预下载的错误事件,当下载错误时执行回调,返回错误信息
cacheDownload.onDownloadError("https://www.example.com", errorCallback);
// 进行缓存下载,资源若下载成功会被缓存到应用内存或应用沙箱目录的特定文件中。
cacheDownload.download("https://www.example.com", {});
} catch (error) {
let err: BusinessError = error as BusinessError;
console.error(`Failed to download the resource. err code: ${err.code}, err message: ${err.message}`);
} offDownloadSuccess(url: string, callback?: Callback<void>): void
取消订阅预下载的完成事件。
系统能力:SystemCapability.Request.FileTransferAgent
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| url | string | 是 | 待注册回调的url,支持HTTP和HTTPS协议,url字符串的最大长度为8192字节,超出长度限制时抛出异常。 |
| callback | Callback<void> | 否 | 需要取消订阅的回调函数。若不填该参数,表示取消该url下的所有完成回调函数。 |
示例:
import { cacheDownload, BusinessError } from '@kit.BasicServicesKit';
try {
const successCallback = () => {
console.info("Succeeded in getting callback from cacheDownload");
};
// 订阅预下载的完成事件,当下载完成时执行回调
cacheDownload.onDownloadSuccess("https://www.example.com", successCallback);
// 取消订阅预下载的完成事件
cacheDownload.offDownloadSuccess("https://www.example.com", successCallback);
// 进行缓存下载,资源若下载成功会被缓存到应用内存或应用沙箱目录的特定文件中。
cacheDownload.download("https://www.example.com", {});
} catch (error) {
let err: BusinessError = error as BusinessError;
console.error(`Failed to download the resource. err code: ${err.code}, err message: ${err.message}`);
} offDownloadError(url: string, callback?: Callback<DownloadError>): void
取消订阅预下载的错误事件。
系统能力:SystemCapability.Request.FileTransferAgent
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| url | string | 是 | 待注册回调的url,支持HTTP和HTTPS协议,url字符串的最大长度为8192字节,超出长度限制时抛出异常。 |
| callback | Callback<DownloadError> | 否 | 需要取消订阅的回调函数。若不填该参数,表示取消该url下的所有错误回调函数。 |
示例:
import { cacheDownload, BusinessError } from '@kit.BasicServicesKit';
try {
const errorCallback = (error: cacheDownload.DownloadError) => {
console.error(`Error callback from cacheDownload. error code: ${error.errorCode}, error message: ${error.message}`);
};
// 订阅预下载的错误事件,当下载错误时执行回调,返回错误信息
cacheDownload.onDownloadError("https://www.example.com", errorCallback);
// 取消订阅预下载的错误事件
cacheDownload.offDownloadError("https://www.example.com", errorCallback);
// 进行缓存下载,资源若下载成功会被缓存到应用内存或应用沙箱目录的特定文件中。
cacheDownload.download("https://www.example.com", {});
} catch (error) {
let err: BusinessError = error as BusinessError;
console.error(`Failed to download the resource. err code: ${err.code}, err message: ${err.message}`);
} setGlobalRetryOptions(options?: RetryOptions): void
设置全局的任务重试配置。当任务未设置特定的重试配置时此配置生效。重试配置优先级:任务设置 > 全局设置 > 默认设置。
起始版本: 26.0.0
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.Request.FileTransferAgent
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| options | RetryOptions | 否 | 任务重试配置,用于自定义全局任务的重试行为。当需要调整全局重试次数等策略时传入此参数;不传入时保持当前全局重试配置不变。 |
示例:
import { cacheDownload, BusinessError } from '@kit.BasicServicesKit';
try {
// 设置全局的任务最大重试次数
cacheDownload.setGlobalRetryOptions({
maxRetryCount: 1
});
cacheDownload.download("https://www.example.com", {});
} catch (error) {
let err: BusinessError = error as BusinessError;
console.error(`Failed to download the resource. err code: ${err.code}, err message: ${err.message}`);
} setGlobalTimeoutOptions(options?: TimeoutOptions): void
设置全局的任务超时配置。当任务未设置特定的超时配置时此配置生效。超时配置优先级:任务设置 > 全局设置 > 默认设置。
起始版本: 26.0.0
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.Request.FileTransferAgent
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| options | TimeoutOptions | 否 | 任务超时配置,用于自定义全局任务的超时行为。当需要调整全局网络检查超时或HTTP请求超时时传入此参数;不传入时保持当前全局超时配置不变。 |
示例:
import { cacheDownload, BusinessError } from '@kit.BasicServicesKit';
try {
// 设置全局任务超时配置
cacheDownload.setGlobalTimeoutOptions({
networkCheckTimeout: 20,
httpTotalTimeout: 60,
});
cacheDownload.download("https://www.example.com", {});
} catch (error) {
let err: BusinessError = error as BusinessError;
console.error(`Failed to download the resource. err code: ${err.code}, err message: ${err.message}`);
}