1# @ohos.file.cloudSync (端云同步能力) 2 3该模块向应用提供端云同步能力，包括启动/停止端云同步以及启动/停止原图下载功能。 4 5> **说明：** 6> 7> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9## 导入模块 10 11```ts 12import { cloudSync } from '@kit.CoreFileKit'; 13``` 14 15## State<sup>11+</sup> 16 17云文件下载状态，为枚举类型。 18 19**系统能力**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 20 21| 名称 | 值| 说明 | 22| ----- | ---- | ---- | 23| RUNNING | 0 | 云文件正在下载中 | 24| COMPLETED | 1 | 云文件下载完成 | 25| FAILED | 2 | 云文件下载失败 | 26| STOPPED | 3 | 云文件下载已停止 | 27 28## DownloadProgress<sup>11+</sup> 29 30云文件下载过程。 31 32**系统能力**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 33 34| 名称 | 类型 | 必填 | 说明 | 35| ---------- | ------ | ---- | ---- | 36| state | [State](#state11) | 是 | 枚举值，云文件下载状态| 37| processed | number | 是 | 已下载数据大小| 38| size | number | 是 | 当前云文件大小| 39| uri | string | 是 | 当前云文件uri| 40| error | [DownloadErrorType](#downloaderrortype11) | 是 | 下载的错误类型| 41 42## CloudFileCache<sup>11+</sup> 43 44云盘文件缓存对象，用来支撑文件管理应用原文件下载流程。 45 46**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 47 48### construct<sup>11+</sup> 49 50constructor() 51 52云盘文件缓存流程的构造函数，用于获取CloudFileCache类的实例。 53 54**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 55 56**错误码：** 57 58| 错误码ID | 错误信息 | 59| ---------------------------- | ---------- | 60| 401 | The input parameter is invalid. Possible causes:Incorrect parameter types. | 61 62**示例：** 63 64 ```ts 65 let fileCache = new cloudSync.CloudFileCache(); 66 ``` 67 68### on<sup>11+</sup> 69 70on(event: 'progress', callback: Callback\<DownloadProgress>): void 71 72添加云盘文件缓存过程事件监听。 73 74**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 75 76**参数：** 77 78| 参数名 | 类型 | 必填 | 说明 | 79| ---------- | ------ | ---- | ---- | 80| event | string | 是 | 订阅的事件类型，取值为'progress'（下载过程事件）| 81| callback | Callback\<[DownloadProgress](#downloadprogress11)> | 是 | 云文件下载过程事件回调。 | 82 83**错误码：** 84 85以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 86 87| 错误码ID | 错误信息 | 88| ---------------------------- | ---------- | 89| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 90| 13600001 | IPC error. | 91 92**示例：** 93 94 ```ts 95 import { BusinessError } from '@kit.BasicServicesKit'; 96 let fileCache = new cloudSync.CloudFileCache(); 97 let callback = (pg: cloudSync.DownloadProgress) => { 98 console.info("download state：" + pg.state); 99 }; 100 101 try { 102 fileCache.on('progress', callback); 103 } catch (e) { 104 const error = e as BusinessError; 105 console.error(`Error code: ${error.code}, message: ${error.message}`); 106 } 107 ``` 108 109### off<sup>11+</sup> 110 111off(event: 'progress', callback?: Callback\<DownloadProgress>): void 112 113移除云盘文件缓存过程事件监听。 114 115**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 116 117**参数：** 118 119| 参数名 | 类型 | 必填 | 说明 | 120| ---------- | ------ | ---- | ---- | 121| event | string | 是 | 取消订阅的事件类型，取值为'progress'（同步过程事件）| 122| callback | Callback\<[DownloadProgress](#downloadprogress11)> | 否 | 云文件下载过程事件回调，若填写，将视为取消指定的回调函数，否则为取消当前订阅的所有回调函数。 | 123 124**错误码：** 125 126以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 127 128| 错误码ID | 错误信息 | 129| ---------------------------- | ---------- | 130| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 131| 13600001 | IPC error. | 132 133**示例：** 134 135 ```ts 136 import { BusinessError } from '@kit.BasicServicesKit'; 137 let fileCache = new cloudSync.CloudFileCache(); 138 139 let callback = (pg: cloudSync.DownloadProgress) => { 140 console.info("download state：" + pg.state); 141 } 142 143 try { 144 fileCache.on('progress', callback); 145 fileCache.off('progress', callback); 146 } catch (e) { 147 const error = e as BusinessError; 148 console.error(`Error code: ${error.code}, message: ${error.message}`); 149 } 150 ``` 151 152### start<sup>11+</sup> 153 154start(uri: string): Promise<void> 155 156异步方法启动云盘文件缓存, 以Promise形式返回结果。 157 158**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 159 160**参数：** 161 162| 参数名 | 类型 | 必填 | 说明 | 163| ---------- | ------ | ---- | ---- | 164| uri | string | 是 | 待下载文件uri。 | 165 166**返回值：** 167 168| 类型 | 说明 | 169| --------------------- | ---------------- | 170| Promise<void> | 使用Promise形式返回启动云文件下载的结果。 | 171 172**示例：** 173 174 ```ts 175 import { BusinessError } from '@kit.BasicServicesKit'; 176 import { fileUri } from '@kit.CoreFileKit'; 177 let fileCache = new cloudSync.CloudFileCache(); 178 let path = "/data/storage/el2/cloud/1.txt"; 179 let uri = fileUri.getUriFromPath(path); 180 181 try { 182 fileCache.on('progress', (pg: cloudSync.DownloadProgress) => { 183 console.info("download state:" + pg.state); 184 }); 185 } catch (e) { 186 const error = e as BusinessError; 187 console.error(`Error code: ${error.code}, message: ${error.message}`); 188 } 189 190 fileCache.start(uri).then(() => { 191 console.info("start download successfully"); 192 }).catch((err: BusinessError) => { 193 console.error("start download failed with error message: " + err.message + ", error code: " + err.code); 194 }); 195 ``` 196 197**错误码：** 198 199以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 200 201| 错误码ID | 错误信息 | 202| ---------------------------- | ---------- | 203| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 204| 13600001 | IPC error. | 205| 13900002 | No such file or directory. | 206| 13900025 | No space left on device. | 207| 14000002 | Invalid uri. | 208 209### start<sup>11+</sup> 210 211start(uri: string, callback: AsyncCallback<void>): void 212 213异步方法启动云盘文件缓存, 以callback形式返回结果。 214 215**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 216 217**参数：** 218 219| 参数名 | 类型 | 必填 | 说明 | 220| ---------- | ------ | ---- | ---- | 221| uri | string | 是 | 待下载文件uri。 | 222| callback | AsyncCallback<void> | 是 | 异步启动云文件下载的回调。 | 223 224**错误码：** 225 226以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 227 228| 错误码ID | 错误信息 | 229| ---------------------------- | ---------- | 230| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 231| 13600001 | IPC error. | 232| 13900002 | No such file or directory. | 233| 13900025 | No space left on device. | 234| 14000002 | Invalid uri. | 235 236**示例：** 237 238 ```ts 239 import { BusinessError } from '@kit.BasicServicesKit'; 240 import { fileUri } from '@kit.CoreFileKit'; 241 let fileCache = new cloudSync.CloudFileCache(); 242 let path = "/data/storage/el2/cloud/1.txt"; 243 let uri = fileUri.getUriFromPath(path); 244 245 fileCache.start(uri, (err: BusinessError) => { 246 if (err) { 247 console.error("start download failed with error message: " + err.message + ", error code: " + err.code); 248 } else { 249 console.info("start download successfully"); 250 } 251 }); 252 ``` 253 254### stop<sup>11+</sup> 255 256stop(uri: string, needClean?: boolean): Promise<void> 257 258异步方法停止云盘文件缓存, 以Promise形式返回结果。 259 260调用stop接口, 当前文件下载流程会终止, 缓存文件会被删除, 再次调用start接口会重新开始下载。 261 262**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 263 264**参数：** 265 266| 参数名 | 类型 | 必填 | 说明 | 267| ---------- | ------ | ---- | ---- | 268| uri | string | 是 | 待下载文件uri。 | 269| needClean<sup>12+</sup> | boolean | 否 | 是否删除已下载的文件，默认删除。<br>从API version12开始支持该参数。 | 270 271**返回值：** 272 273| 类型 | 说明 | 274| --------------------- | ---------------- | 275| Promise<void> | 使用Promise形式返回停止云文件下载的结果。 | 276 277**错误码：** 278 279以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 280 281| 错误码ID | 错误信息 | 282| ---------------------------- | ---------- | 283| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 284| 13600001 | IPC error. | 285| 13900002 | No such file or directory. | 286| 14000002 | Invalid URI. | 287 288**示例：** 289 290 ```ts 291 import { BusinessError } from '@kit.BasicServicesKit'; 292 import { fileUri } from '@kit.CoreFileKit'; 293 let fileCache = new cloudSync.CloudFileCache(); 294 let path = "/data/storage/el2/cloud/1.txt"; 295 let uri = fileUri.getUriFromPath(path); 296 297 fileCache.stop(uri, true).then(() => { 298 console.info("stop download successfully"); 299 }).catch((err: BusinessError) => { 300 console.error("stop download failed with error message: " + err.message + ", error code: " + err.code); 301 }); 302 ``` 303 304### stop<sup>11+</sup> 305 306stop(uri: string, callback: AsyncCallback<void>): void 307 308异步方法停止云盘文件缓存, 以callback形式返回结果。 309 310调用stop接口, 当前文件下载流程会终止, 缓存文件会被删除, 再次调用start接口会重新开始下载。 311 312**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 313 314**参数：** 315 316| 参数名 | 类型 | 必填 | 说明 | 317| ---------- | ------ | ---- | ---- | 318| uri | string | 是 | 待下载文件uri。 | 319| callback | AsyncCallback<void> | 是 | 异步停止云文件下载的回调。 | 320 321**错误码：** 322 323以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 324 325| 错误码ID | 错误信息 | 326| ---------------------------- | ---------- | 327| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 328| 13600001 | IPC error. | 329| 13900002 | No such file or directory. | 330| 14000002 | Invalid URI. | 331 332**示例：** 333 334 ```ts 335 import { BusinessError } from '@kit.BasicServicesKit'; 336 import { fileUri } from '@kit.CoreFileKit'; 337 let fileCache = new cloudSync.CloudFileCache(); 338 let path = "/data/storage/el2/cloud/1.txt"; 339 let uri = fileUri.getUriFromPath(path); 340 341 fileCache.stop(uri, (err: BusinessError) => { 342 if (err) { 343 console.error("stop download failed with error message: " + err.message + ", error code: " + err.code); 344 } else { 345 console.info("stop download successfully"); 346 } 347 }); 348 ``` 349 350## DownloadErrorType<sup>11+</sup> 351 352端云下载错误类型，为枚举类型。 353 354**系统能力**: SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 355 356| 名称 | 值| 说明 | 357| ----- | ---- | ---- | 358| NO_ERROR | 0 | 没有错误 | 359| UNKNOWN_ERROR | 1 | 未知错误 | 360| NETWORK_UNAVAILABLE | 2 | 网络不可用 | 361| LOCAL_STORAGE_FULL | 3 | 本地空间不足 | 362| CONTENT_NOT_FOUND | 4 | 云端空间未找到对应文件 | 363| FREQUENT_USER_REQUESTS | 5 | 用户请求过于频繁 |