1# @ohos.request.cacheDownload (缓存下载) 2 3request部件主要给应用提供上传下载文件、后台传输代理的基础能力。 4 5- request的cacheDownload子组件主要给应用提供应用资源提前缓存的基础能力。 6 7- cacheDownload组件使用HTTP协议进行数据下载，并将数据资源缓存至应用内存或应用沙箱目录的文件中。 8 9- 这些缓存数据可以被部分ArkUI相关组件使用(例如：Image组件)，从而提升资源加载效率。请查看ArkUI组件文档确定组件是否支持该功能。 10 11> **说明：** 12> 13> 本模块首批接口从API version 18开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 14 15## 导入模块 16 17```js 18import { cacheDownload } from '@kit.BasicServicesKit'; 19``` 20 21## CacheDownloadOptions 22 23缓存下载的配置选项。例如：HTTP选项、传输选项、任务选项等。 24 25**系统能力**：SystemCapability.Request.FileTransferAgent 26 27| 名称 | 类型 | 必填 | 说明 | 28|---------|--------------------------|----|-----------------------| 29| headers | Record\<string, string\> | 否 | 缓存下载任务在HTTP传输时使用的请求头。 | 30 31## cacheDownload.download 32 33download(url: string, options: CacheDownloadOptions) 34 35启动一个缓存下载任务，若传输成功，则将数据下载到内存缓存和文件缓存中。 36 37- 目标资源经过HTTP传输自动解压后的大小不能超过20971520B(即20MB)，否则不会保存到内存缓存或文件缓存中。 38 39- 在缓存下载数据时，如果在该URL下已存在缓存内容，新的缓存内容会覆盖旧缓存内容。 40 41- 目标资源在存储到内存缓存或文件缓存中时，依照缓存下载组件的各类型缓存大小上限决定文件是否存储到指定位置，并默认使用“LRU”(最近最少使用)方式替换已有缓存内容。 42 43- 该方法为同步方法，不阻塞调用线程。 44 45**需要权限**：ohos.permission.INTERNET 46 47**系统能力**：SystemCapability.Request.FileTransferAgent 48 49**参数：** 50 51| 参数名 | 类型 | 必填 | 说明 | 52|---------|------------------------------------------------------------|----|--------------------------------| 53| url | string | 是 | 目标资源的地址。仅支持HTTP协议，长度不超过8192字节。 | 54| options | [CacheDownloadOptions](#cachedownloadoptions) | 是 | 目标资源的缓存下载选项。 | 55 56**错误码：** 57 58以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 59 60| 错误码ID | 错误信息 | 61|----------|-------------------------------------------------------------------------------------------------------------------------------------------| 62| 201 | permission denied. | 63| 401 | parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. | 64 65**示例：** 66 67 ```ts 68 import { cacheDownload, BusinessError } from '@kit.BasicServicesKit'; 69 70 // 提供缓存下载任务的配置选项。 71 let options: cacheDownload.CacheDownloadOptions = {}; 72 73 try { 74 // 进行缓存下载，资源若下载成功会被缓存到应用内存或应用沙箱目录的特定文件中。 75 cacheDownload.download("https://www.example.com", options); 76 } catch (err) { 77 console.error(`Failed to download the resource. err: ${JSON.stringify(err)}`); 78 } 79 ``` 80 81## cacheDownload.cancel 82 83cancel(url: string) 84 85根据URL移除一个正在执行的缓存下载任务，已保存的内存缓存和文件缓存不会受到影响。 86 87- 如果不存在对应URL的任务则无其他效果。 88 89- 该方法为同步方法，不阻塞调用线程。 90 91**系统能力**：SystemCapability.Request.FileTransferAgent 92 93**参数：** 94 95| 参数名 | 类型 | 必填 | 说明 | 96|------|--------|----|--------------------------------| 97| url | string | 是 | 目标资源的地址。仅支持HTTP协议，长度不超过8192字节。 | 98 99**错误码：** 100 101以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 102 103| 错误码ID | 错误信息 | 104|----------|-------------------------------------------------------------------------------------------------------------------------------------------| 105| 401 | parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. | 106 107**示例：** 108 109 ```ts 110 import { cacheDownload, BusinessError } from '@kit.BasicServicesKit'; 111 112 // 提供缓存下载任务的配置选项。 113 let options: cacheDownload.CacheDownloadOptions = {}; 114 115 try { 116 // 进行缓存下载，资源若下载成功会被缓存到应用内存或应用沙箱目录的特定文件中。 117 cacheDownload.download("https://www.example.com", options); 118 } catch (err) { 119 console.error(`Failed to download the resource. err: ${JSON.stringify(err)}`); 120 } 121 122 // 处理其他业务逻辑。 123 124 try { 125 // 在不需要特定任务缓存时，移除缓存下载任务，已缓存的内容不受影响。 126 cacheDownload.cancel("https://www.example.com"); 127 } catch (err) { 128 console.error(`Failed to cancel the task. err: ${JSON.stringify(err)}`); 129 } 130 ``` 131 132## cacheDownload.setMemoryCacheSize 133 134setMemoryCacheSize(bytes: number) 135 136设置缓存下载组件能够保存的内存缓存上限。 137 138- 使用该接口调整缓存大小时，默认使用“LRU”(最近最少使用方式)清除多余的已缓存的内存缓存内容。 139 140- 该方法为同步方法，不阻塞调用线程。 141 142**系统能力**：SystemCapability.Request.FileTransferAgent 143 144**参数：** 145 146| 参数名 | 类型 | 必填 | 说明 | 147|-------|--------|----|-----------------------------------------| 148| bytes | number | 是 | 设置的缓存上限。默认值为0B，最大值不超过1073741824B(即1GB)。 | 149 150**错误码：** 151 152以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 153 154| 错误码ID | 错误信息 | 155|----------|-------------------------------------------------------------------------------------------------------------------------------------------| 156| 401 | parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. | 157 158**示例：** 159 160 ```ts 161 import { cacheDownload, BusinessError } from '@kit.BasicServicesKit'; 162 163 try { 164 // 设置内存缓存大小上限。 165 cacheDownload.setMemoryCacheSize(10 * 1024 * 1024); 166 } catch (err) { 167 console.error(`Failed to set memory cache size. err: ${JSON.stringify(err)}`); 168 } 169 ``` 170 171## cacheDownload.setFileCacheSize 172 173setFileCacheSize(bytes: number) 174 175设置缓存下载组件能够保存的文件缓存上限。 176 177- 使用该接口调整缓存大小时，默认使用“LRU”(最近最少使用方式)清除多余的已缓存的文件缓存内容。 178 179- 该方法为同步方法，不阻塞调用线程。 180 181**系统能力**：SystemCapability.Request.FileTransferAgent 182 183**参数：** 184 185| 参数名 | 类型 | 必填 | 说明 | 186|-------|--------|----|------------------------------------------------------------| 187| bytes | number | 是 | 设置的缓存上限。默认值为104857600B(即100MB)，最大值不超过4294967296B(即4GB)。 | 188 189**错误码：** 190 191以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 192 193| 错误码ID | 错误信息 | 194|----------|-------------------------------------------------------------------------------------------------------------------------------------------| 195| 401 | parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. | 196 197**示例：** 198 199 ```ts 200 import { cacheDownload, BusinessError } from '@kit.BasicServicesKit'; 201 202 try { 203 // 设置文件缓存大小上限。 204 cacheDownload.setFileCacheSize(100 * 1024 * 1024); 205 } catch (err) { 206 console.error(`Failed to set file cache size. err: ${JSON.stringify(err)}`); 207 } 208 ```