1# @ohos.file.cloudSync (端云同步能力)(系统接口) 2<!--Kit: Core File Kit--> 3<!--Subsystem: FileManagement--> 4<!--Owner: @zsyztt; @Hermits; @reminder2352--> 5<!--Designer: @yunlanying--> 6<!--Tester: @liuhonggang123--> 7<!--Adviser: @foryourself--> 8 9该模块向应用提供端云同步能力，包括启动/停止端云同步以及启动/停止原图下载功能。 10 11> **说明：** 12> 13> - 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 14> - 当前页面仅包含本模块的系统接口，其他公开接口参见[@ohos.file.cloudSync (端云同步能力)](js-apis-file-cloudsync.md)。 15 16## 导入模块 17 18```ts 19import { cloudSync } from '@kit.CoreFileKit'; 20``` 21 22## GallerySync 23 24云图同步对象，用来支撑图库应用媒体资源端云同步流程。在使用前，需要先创建GallerySync实例。 25 26### constructor 27 28constructor() 29 30端云同步流程的构造函数，用于获取GallerySync类的实例。 31 32**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 33 34**系统接口**：该接口为系统接口。 35 36**示例：** 37 38 ```ts 39 let gallerySync = new cloudSync.GallerySync() 40 ``` 41 42### on 43 44on(evt: 'progress', callback: (pg: SyncProgress) => void): void 45 46添加同步过程事件监听。 47 48**需要权限**：ohos.permission.CLOUDFILE_SYNC 49 50**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 51 52**系统接口**：该接口为系统接口。 53 54**参数：** 55 56| 参数名 | 类型 | 必填 | 说明 | 57| ---------- | ------ | ---- | ---- | 58| evt | string | 是 | 订阅的事件类型，取值为'progress'（同步过程事件）。 | 59| callback | (pg: SyncProgress) => void | 是 | 同步过程事件回调，回调入参为[SyncProgress](./js-apis-file-cloudsync.md#syncprogress12)，返回值为void。| 60 61**错误码：** 62 63以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 64 65| 错误码ID | 错误信息 | 66| ---------------------------- | ---------- | 67| 201 | Permission verification failed. | 68| 202 | The caller is not a system application. | 69| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 70| 13600001 | IPC error. | 71 72**示例：** 73 74 ```ts 75 let gallerySync = new cloudSync.GallerySync(); 76 77 gallerySync.on('progress', (pg: cloudSync.SyncProgress) => { 78 console.info("syncState：" + pg.state); 79 }); 80 ``` 81 82### off 83 84off(evt: 'progress', callback: (pg: SyncProgress) => void): void 85 86移除同步过程事件监听。 87 88**需要权限**：ohos.permission.CLOUDFILE_SYNC 89 90**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 91 92**系统接口**：该接口为系统接口。 93 94**参数：** 95 96| 参数名 | 类型 | 必填 | 说明 | 97| ---------- | ------ | ---- | ---- | 98| evt | string | 是 | 取消订阅的事件类型，取值为'progress'（同步过程事件）。| 99| callback | (pg: SyncProgress) => void | 是 | 同步过程事件回调，回调入参为[SyncProgress](./js-apis-file-cloudsync.md#syncprogress12)，返回值为void。| 100 101**错误码：** 102 103以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 104 105| 错误码ID | 错误信息 | 106| ---------------------------- | ---------- | 107| 201 | Permission verification failed. | 108| 202 | The caller is not a system application. | 109| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 110| 13600001 | IPC error. | 111 112**示例：** 113 114 ```ts 115 let gallerySync = new cloudSync.GallerySync(); 116 117 let callback = (pg: cloudSync.SyncProgress) => { 118 console.info("gallery sync state：" + pg.state + "error type:" + pg.error); 119 } 120 121 gallerySync.on('progress', callback); 122 123 gallerySync.off('progress', callback); 124 ``` 125 126### off 127 128off(evt: 'progress'): void 129 130移除同步过程事件监听。 131 132**需要权限**：ohos.permission.CLOUDFILE_SYNC 133 134**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 135 136**系统接口**：该接口为系统接口。 137 138**参数：** 139 140| 参数名 | 类型 | 必填 | 说明 | 141| ---------- | ------ | ---- | ---- | 142| evt | string | 是 | 取消订阅的事件类型，取值为'progress'（同步过程事件）。| 143 144**错误码：** 145 146以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 147 148| 错误码ID | 错误信息 | 149| ---------------------------- | ---------- | 150| 201 | Permission verification failed. | 151| 202 | The caller is not a system application. | 152| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 153| 13600001 | IPC error. | 154 155**示例：** 156 157 ```ts 158 let gallerySync = new cloudSync.GallerySync(); 159 160 gallerySync.on('progress', (pg: cloudSync.SyncProgress) => { 161 console.info("syncState：" + pg.state); 162 }); 163 164 gallerySync.off('progress'); 165 ``` 166 167### start 168 169start(): Promise<void> 170 171异步方法启动端云同步，以Promise形式返回结果。 172 173**需要权限**：ohos.permission.CLOUDFILE_SYNC 174 175**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 176 177**系统接口**：该接口为系统接口。 178 179**返回值：** 180 181| 类型 | 说明 | 182| --------------------- | ---------------- | 183| Promise<void> | 使用Promise形式返回启动端云同步的结果。 | 184 185**错误码：** 186 187以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 188 189| 错误码ID | 错误信息 | 190| ---------------------------- | ---------- | 191| 201 | Permission verification failed. | 192| 202 | The caller is not a system application. | 193| 401 | The input parameter is invalid. Possible causes:Incorrect parameter types. | 194| 22400001 | Cloud status not ready. | 195| 22400002 | Network unavailable. | 196| 22400003 | Low battery level. | 197 198**示例：** 199 200 ```ts 201 import { BusinessError } from '@kit.BasicServicesKit'; 202 let gallerySync = new cloudSync.GallerySync(); 203 204 gallerySync.on('progress', (pg: cloudSync.SyncProgress) => { 205 console.info("syncState：" + pg.state); 206 }); 207 208 gallerySync.start().then(() => { 209 console.info("start sync successfully"); 210 }).catch((err: BusinessError) => { 211 console.error("start sync failed with error message: " + err.message + ", error code: " + err.code); 212 }); 213 ``` 214 215### start 216 217start(callback: AsyncCallback<void>): void 218 219异步方法启动端云同步，以callback形式返回结果。 220 221**需要权限**：ohos.permission.CLOUDFILE_SYNC 222 223**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 224 225**系统接口**：该接口为系统接口。 226 227**参数：** 228 229| 参数名 | 类型 | 必填 | 说明 | 230| ---------- | ------ | ---- | ---- | 231| callback | AsyncCallback<void> | 是 | 异步启动端云同步的回调。 | 232 233**错误码：** 234 235以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 236 237| 错误码ID | 错误信息 | 238| ---------------------------- | ---------- | 239| 201 | Permission verification failed. | 240| 202 | The caller is not a system application. | 241| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 242| 22400001 | Cloud status not ready. | 243| 22400002 | Network unavailable. | 244| 22400003 | Low battery level. | 245 246**示例：** 247 248 ```ts 249 import { BusinessError } from '@kit.BasicServicesKit'; 250 let gallerySync = new cloudSync.GallerySync(); 251 252 gallerySync.start((err: BusinessError) => { 253 if (err) { 254 console.error("start sync failed with error message: " + err.message + ", error code: " + err.code); 255 } else { 256 console.info("start sync successfully"); 257 } 258 }); 259 ``` 260 261### stop 262 263stop(): Promise<void> 264 265异步方法停止端云同步，以Promise形式返回结果。 266 267> **说明：** 268> 269> 调用stop接口，同步流程会停止。再次调用[start](#start)接口会继续同步。 270 271**需要权限**：ohos.permission.CLOUDFILE_SYNC 272 273**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 274 275**系统接口**：该接口为系统接口。 276 277**返回值：** 278 279| 类型 | 说明 | 280| --------------------- | ---------------- | 281| Promise<void> | 使用Promise形式返回停止端云同步的结果。 | 282 283**错误码：** 284 285以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 286 287| 错误码ID | 错误信息 | 288| ---------------------------- | ---------- | 289| 201 | Permission verification failed. | 290| 202 | The caller is not a system application. | 291| 401 | The input parameter is invalid. Possible causes:Incorrect parameter types. | 292 293**示例：** 294 295 ```ts 296 import { BusinessError } from '@kit.BasicServicesKit'; 297 let gallerySync = new cloudSync.GallerySync(); 298 299 gallerySync.stop().then(() => { 300 console.info("stop sync successfully"); 301 }).catch((err: BusinessError) => { 302 console.error("stop sync failed with error message: " + err.message + ", error code: " + err.code); 303 }); 304 ``` 305 306### stop 307 308stop(callback: AsyncCallback<void>): void 309 310异步方法停止端云同步，以callback形式返回结果。 311 312> **说明：** 313> 314> 调用stop接口，同步流程会停止。再次调用[start](#start)接口会继续同步。 315 316**需要权限**：ohos.permission.CLOUDFILE_SYNC 317 318**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 319 320**系统接口**：该接口为系统接口。 321 322**参数：** 323 324| 参数名 | 类型 | 必填 | 说明 | 325| ---------- | ------ | ---- | ---- | 326| callback | AsyncCallback<void> | 是 | 异步停止端云同步的回调。 | 327 328**错误码：** 329 330以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 331 332| 错误码ID | 错误信息 | 333| ---------------------------- | ---------- | 334| 201 | Permission verification failed. | 335| 202 | The caller is not a system application. | 336| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 337 338**示例：** 339 340 ```ts 341 import { BusinessError } from '@kit.BasicServicesKit'; 342 let gallerySync = new cloudSync.GallerySync(); 343 344 gallerySync.stop((err: BusinessError) => { 345 if (err) { 346 console.error("stop sync failed with error message: " + err.message + ", error code: " + err.code); 347 } else { 348 console.info("stop sync successfully"); 349 } 350 }); 351 ``` 352 353## Download 354 355云文件下载对象，用来支撑图库应用原图文件下载流程。在使用前，需要先创建Download实例。 356 357### constructor 358 359constructor() 360 361云文件下载流程的构造函数，用于获取Download类的实例。 362 363**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 364 365**系统接口**：该接口为系统接口。 366 367**示例：** 368 369 ```ts 370 let download = new cloudSync.Download() 371 ``` 372 373### on 374 375on(evt: 'progress', callback: (pg: DownloadProgress) => void): void 376 377添加云文件下载过程事件监听。 378 379**需要权限**：ohos.permission.CLOUDFILE_SYNC 380 381**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 382 383**系统接口**：该接口为系统接口。 384 385**参数：** 386 387| 参数名 | 类型 | 必填 | 说明 | 388| ---------- | ------ | ---- | ---- | 389| evt | string | 是 | 订阅的事件类型，取值为'progress'（下载过程事件）。| 390| callback | (pg: DownloadProgress) => void | 是 | 云文件下载过程事件回调，回调入参为[DownloadProgress](js-apis-file-cloudsync.md#downloadprogress11)，返回值为void。| 391 392**错误码：** 393 394以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 395 396| 错误码ID | 错误信息 | 397| ---------------------------- | ---------- | 398| 201 | Permission verification failed. | 399| 202 | The caller is not a system application. | 400| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 401| 13600001 | IPC error. | 402 403**示例：** 404 405 ```ts 406 let download = new cloudSync.Download(); 407 408 download.on('progress', (pg: cloudSync.DownloadProgress) => { 409 console.info("download state：" + pg.state); 410 }); 411 ``` 412 413### off 414 415off(evt: 'progress', callback: (pg: DownloadProgress) => void): void 416 417移除云文件下载过程事件监听。 418 419**需要权限**：ohos.permission.CLOUDFILE_SYNC 420 421**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 422 423**系统接口**：该接口为系统接口。 424 425**参数：** 426 427| 参数名 | 类型 | 必填 | 说明 | 428| ---------- | ------ | ---- | ---- | 429| evt | string | 是 | 取消订阅的事件类型，取值为'progress'（同步过程事件）。| 430| callback | (pg: DownloadProgress) => void | 是 | 云文件下载过程事件回调，回调入参为[DownloadProgress](js-apis-file-cloudsync.md#downloadprogress11)，返回值为void。| 431 432**错误码：** 433 434以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 435 436| 错误码ID | 错误信息 | 437| ---------------------------- | ---------- | 438| 201 | Permission verification failed. | 439| 202 | The caller is not a system application. | 440| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 441| 13600001 | IPC error. | 442 443**示例：** 444 445 ```ts 446 let download = new cloudSync.Download(); 447 448 let callback = (pg: cloudSync.DownloadProgress) => { 449 console.info("download state：" + pg.state); 450 } 451 452 download.on('progress', callback); 453 454 download.off('progress', callback); 455 ``` 456 457### off 458 459off(evt: 'progress'): void 460 461移除云文件下载过程事件监听。 462 463**需要权限**：ohos.permission.CLOUDFILE_SYNC 464 465**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 466 467**系统接口**：该接口为系统接口。 468 469**参数：** 470 471| 参数名 | 类型 | 必填 | 说明 | 472| ---------- | ------ | ---- | ---- | 473| evt | string | 是 | 取消订阅的事件类型，取值为'progress'（下载过程事件）。| 474 475**错误码：** 476 477以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 478 479| 错误码ID | 错误信息 | 480| ---------------------------- | ---------- | 481| 201 | Permission verification failed. | 482| 202 | The caller is not a system application. | 483| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 484| 13600001 | IPC error. | 485 486**示例：** 487 488 ```ts 489 let download = new cloudSync.Download(); 490 491 download.on('progress', (pg: cloudSync.DownloadProgress) => { 492 console.info("download state:" + pg.state); 493 }); 494 495 download.off('progress'); 496 ``` 497 498### start 499 500start(uri: string): Promise<void> 501 502异步方法启动云文件下载，以Promise形式返回结果。 503 504**需要权限**：ohos.permission.CLOUDFILE_SYNC 505 506**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 507 508**系统接口**：该接口为系统接口。 509 510**参数：** 511 512| 参数名 | 类型 | 必填 | 说明 | 513| ---------- | ------ | ---- | ---- | 514| uri | string | 是 | 待下载文件uri。 | 515 516**返回值：** 517 518| 类型 | 说明 | 519| --------------------- | ---------------- | 520| Promise<void> | 使用Promise形式返回启动云文件下载的结果。 | 521 522**示例：** 523 524 ```ts 525 import { BusinessError } from '@kit.BasicServicesKit'; 526 let download = new cloudSync.Download(); 527 let uri: string = "file:///media/Photo/1"; 528 529 download.on('progress', (pg: cloudSync.DownloadProgress) => { 530 console.info("download state:" + pg.state); 531 }); 532 533 download.start(uri).then(() => { 534 console.info("start download successfully"); 535 }).catch((err: BusinessError) => { 536 console.error("start download failed with error message: " + err.message + ", error code: " + err.code); 537 }); 538 ``` 539 540**错误码：** 541 542以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 543 544| 错误码ID | 错误信息 | 545| ---------------------------- | ---------- | 546| 201 | Permission verification failed. | 547| 202 | The caller is not a system application. | 548| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 549| 13900002 | No such file or directory. | 550| 13900025 | No space left on device. | 551 552### start 553 554start(uri: string, callback: AsyncCallback<void>): void 555 556异步方法启动云文件下载，以callback形式返回结果。 557 558**需要权限**：ohos.permission.CLOUDFILE_SYNC 559 560**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 561 562**系统接口**：该接口为系统接口。 563 564**参数：** 565 566| 参数名 | 类型 | 必填 | 说明 | 567| ---------- | ------ | ---- | ---- | 568| uri | string | 是 | 待下载文件uri。 | 569| callback | AsyncCallback<void> | 是 | 异步启动云文件下载的回调。 | 570 571**错误码：** 572 573以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 574 575| 错误码ID | 错误信息 | 576| ---------------------------- | ---------- | 577| 201 | Permission verification failed. | 578| 202 | The caller is not a system application. | 579| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 580| 13900002 | No such file or directory. | 581| 13900025 | No space left on device. | 582 583**示例：** 584 585 ```ts 586 import { BusinessError } from '@kit.BasicServicesKit'; 587 let download = new cloudSync.Download(); 588 let uri: string = "file:///media/Photo/1"; 589 590 download.start(uri, (err: BusinessError) => { 591 if (err) { 592 console.error("start download failed with error message: " + err.message + ", error code: " + err.code); 593 } else { 594 console.info("start download successfully"); 595 } 596 }); 597 ``` 598 599### stop 600 601stop(uri: string): Promise<void> 602 603异步方法停止云文件下载，以Promise形式返回结果。 604 605> **说明：** 606> 607> 调用stop接口，当前文件下载流程会终止，缓存文件会被删除，再次调用start接口会重新开始下载。 608 609**需要权限**：ohos.permission.CLOUDFILE_SYNC 610 611**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 612 613**系统接口**：该接口为系统接口。 614 615**参数：** 616 617| 参数名 | 类型 | 必填 | 说明 | 618| ---------- | ------ | ---- | ---- | 619| uri | string | 是 | 待下载文件uri。 | 620 621**返回值：** 622 623| 类型 | 说明 | 624| --------------------- | ---------------- | 625| Promise<void> | 使用Promise形式返回停止云文件下载的结果。 | 626 627**错误码：** 628 629以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 630 631| 错误码ID | 错误信息 | 632| ---------------------------- | ---------- | 633| 201 | Permission verification failed. | 634| 202 | The caller is not a system application. | 635| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 636 637**示例：** 638 639 ```ts 640 import { BusinessError } from '@kit.BasicServicesKit'; 641 let download = new cloudSync.Download(); 642 let uri: string = "file:///media/Photo/1"; 643 644 download.stop(uri).then(() => { 645 console.info("stop download successfully"); 646 }).catch((err: BusinessError) => { 647 console.error("stop download failed with error message: " + err.message + ", error code: " + err.code); 648 }); 649 ``` 650 651### stop 652 653stop(uri: string, callback: AsyncCallback<void>): void 654 655异步方法停止云文件下载，以callback形式返回结果。 656 657> **说明：** 658> 659> 调用stop接口，当前文件下载流程会终止，缓存文件会被删除，再次调用start接口会重新开始下载。 660 661**需要权限**：ohos.permission.CLOUDFILE_SYNC 662 663**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 664 665**系统接口**：该接口为系统接口。 666 667**参数：** 668 669| 参数名 | 类型 | 必填 | 说明 | 670| ---------- | ------ | ---- | ---- | 671| uri | string | 是 | 待下载文件uri。 | 672| callback | AsyncCallback<void> | 是 | 异步停止云文件下载的回调。 | 673 674**错误码：** 675 676以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 677 678| 错误码ID | 错误信息 | 679| ---------------------------- | ---------- | 680| 201 | Permission verification failed. | 681| 202 | The caller is not a system application. | 682| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 683 684**示例：** 685 686 ```ts 687 import { BusinessError } from '@kit.BasicServicesKit'; 688 let download = new cloudSync.Download(); 689 let uri: string = "file:///media/Photo/1"; 690 691 download.stop(uri, (err: BusinessError) => { 692 if (err) { 693 console.error("stop download failed with error message: " + err.message + ", error code: " + err.code); 694 } else { 695 console.info("stop download successfully"); 696 } 697 }); 698 ``` 699 700## FileSync<sup>12+</sup> 701 702云盘同步对象，用于支撑文件管理器应用完成云盘文件的端云同步流程。在使用前，需要先创建FileSync实例。 703 704### constructor<sup>12+</sup> 705 706constructor(bundleName: string) 707 708端云同步流程的构造函数，用于获取FileSync类的实例。 709 710**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 711 712**系统接口**：该接口为系统接口。 713 714**参数：** 715 716| 参数名 | 类型 | 必填 | 说明 | 717| ---------- | ------ | ---- | ---- | 718| bundleName | string | 是 | 应用包名。| 719 720**错误码：** 721 722以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 723 724| 错误码ID | 错误信息 | 725| ---------------------------- | ---------- | 726| 202 | Permission verification failed, application which is not a system application uses system API. | 727| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 728 729**示例：** 730 731 ```ts 732 let fileSync = new cloudSync.FileSync("com.ohos.demo") 733 ``` 734 735## CloudFileCache<sup>11+</sup> 736 737云盘文件缓存对象，用来支撑文件管理应用原文件下载流程。 738 739**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 740 741### cleanCache<sup>11+</sup> 742 743cleanCache(uri: string): void 744 745同步方法删除文件缓存。 746 747**需要权限**：ohos.permission.CLOUDFILE_SYNC 748 749**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 750 751**系统接口**：该接口为系统接口。 752 753**参数：** 754 755| 参数名 | 类型 | 必填 | 说明 | 756| ---------- | ------ | ---- | ---- | 757| uri | string | 是 | 待删除缓存文件的uri。| 758 759**错误码：** 760 761以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 762 763| 错误码ID | 错误信息 | 764| ---------------------------- | ---------- | 765| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 766| 202 | Permission verification failed, application which is not a system application uses system API. | 767| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 768| 13600001 | IPC error. | 769| 13900002 | No such file or directory. | 770| 14000002 | Invalid URI. | 771 772**示例：** 773 774 ```ts 775 import { BusinessError } from '@kit.BasicServicesKit'; 776 import { fileUri } from '@kit.CoreFileKit'; 777 let fileCache = new cloudSync.CloudFileCache(); 778 let path = "/data/storage/el2/cloud/1.txt"; 779 let uri = fileUri.getUriFromPath(path); 780 781 try { 782 fileCache.cleanCache(uri); 783 } catch (err) { 784 let error:BusinessError = err as BusinessError; 785 console.error("clean cache failed with error message: " + err.message + ", error code: " + err.code); 786 } 787 788 ``` 789 790## cloudSync.getFileSyncState<sup>11+</sup> 791 792getFileSyncState(uri: Array<string>): Promise<Array<FileSyncState>> 793 794异步方法获取文件同步状态，以promise形式返回结果。 795 796**需要权限**：ohos.permission.CLOUDFILE_SYNC 797 798**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 799 800**系统接口**：该接口为系统接口。 801 802**参数：** 803 804| 参数名 | 类型 | 必填 | 说明 | 805| ---------- | ------ | ---- | ---- | 806| uri | Array<string> | 是 | 待获取同步状态的uri。 | 807 808**返回值：** 809 810| 类型 | 说明 | 811| --------------------- | ---------------- | 812| Promise<Array<FileSyncState>> | 使用Promise形式返回文件同步状态的结果。 | 813 814**错误码：** 815 816以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 817 818| 错误码ID | 错误信息 | 819| ---------------------------- | ---------- | 820| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 821| 202 | Permission verification failed, application which is not a system application uses system API. | 822| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 823| 13600001 | IPC error. | 824| 13900002 | No such file or directory. | 825| 14000002 | Invalid URI. | 826 827**示例：** 828 829 ```ts 830 import { BusinessError } from '@kit.BasicServicesKit'; 831 832 let uris: Array<string> = ["file://uri"]; 833 cloudSync.getFileSyncState(uris).then((syncStates: Array<cloudSync.FileSyncState>) => { 834 for(let i = 0, len = syncStates.length; i < len; i++){ 835 console.info("get file sync state successfully" + syncStates[i]); 836 } 837 }).catch((err: BusinessError) => { 838 console.error("get file sync state failed with error message: " + err.message + ", error code: " + err.code); 839 }); 840 841 ``` 842 843## cloudSync.getFileSyncState<sup>11+</sup> 844 845getFileSyncState(uri: Array<string>, callback: AsyncCallback<Array<FileSyncState>>): void 846 847异步方法获取文件同步状态，以callback形式返回结果。 848 849**需要权限**：ohos.permission.CLOUDFILE_SYNC 850 851**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 852 853**系统接口**：该接口为系统接口。 854 855**参数：** 856 857| 参数名 | 类型 | 必填 | 说明 | 858| ---------- | ------ | ---- | ---- | 859| uri | Array<string> | 是 | 待获取同步状态的uri。 | 860| callback | AsyncCallback<Array<FileSyncState>> | 是 | 异步获取文件状态的回调。| 861 862**错误码：** 863 864以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 865 866| 错误码ID | 错误信息 | 867| ---------------------------- | ---------- | 868| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 869| 202 | Permission verification failed, application which is not a system application uses system API. | 870| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 871| 13600001 | IPC error. | 872| 13900002 | No such file or directory. | 873| 14000002 | Invalid URI. | 874 875**示例：** 876 877 ```ts 878 import { BusinessError } from '@kit.BasicServicesKit'; 879 880 let uris: Array<string> = ["file://uri"]; 881 cloudSync.getFileSyncState(uris, (err: BusinessError, syncStates: Array<cloudSync.FileSyncState>) => { 882 if (err) { 883 console.error("get file sync state with error message: " + err.message + ", error code: " + err.code); 884 } else { 885 for(let i = 0, len = syncStates.length; i < len; i++){ 886 console.info("get file sync state successfully" + syncStates[i]); 887 } 888 } 889 }); 890 ``` 891 892## cloudSync.getFileSyncState<sup>12+</sup> 893 894getFileSyncState(uri: string): FileSyncState 895 896获取文件同步状态。 897 898**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 899 900**系统接口**：该接口为系统接口。 901 902**参数：** 903 904| 参数名 | 类型 | 必填 | 说明 | 905| ---------- | ------ | ---- | ---- | 906| uri | string | 是 | 待下载文件uri。 | 907 908**返回值：** 909 910| 类型 | 说明 | 911| --------------------- | ---------------- | 912| [FileSyncState](#filesyncstate11) | 返回给定文件的同步状态。 | 913 914**错误码：** 915 916以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 917 918| 错误码ID | 错误信息 | 919| ---------------------------- | ---------- | 920| 202 | Permission verification failed, application which is not a system application uses system API. | 921| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 922| 13900002 | No such file or directory. | 923| 13900004 | Interrupted system call. | 924| 13900010 | Try again. | 925| 13900012 | Permission denied by the file system. | 926| 13900031 | Function not implemented. | 927| 13900042 | Unknown error. | 928| 14000002 | Invalid URI. | 929 930**示例：** 931 932 ```ts 933 import { BusinessError } from '@kit.BasicServicesKit'; 934 import { fileUri } from '@kit.CoreFileKit'; 935 let path = "/data/storage/el2/cloud/1.txt"; 936 let uri = fileUri.getUriFromPath(path); 937 try { 938 let state = cloudSync.getFileSyncState(uri); 939 } catch (err) { 940 let error:BusinessError = err as BusinessError; 941 console.error("getFileSyncStatefailed with error:" + JSON.stringify(error)); 942 } 943 ``` 944 945## FileSyncState<sup>11+</sup> 946 947端云文件同步状态，为枚举类型。 948 949**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 950 951**系统接口**：该接口为系统接口。 952 953| 名称 | 值| 说明 | 954| ----- | ---- | ---- | 955| UPLOADING | 0 | 上行同步中。 | 956| DOWNLOADING | 1 | 下行同步中。 | 957| COMPLETED | 2 | 同步成功。 | 958| STOPPED | 3 | 同步已停止。 | 959| TO_BE_UPLOADED<sup>12+</sup> | 4 | 正在等待上行。 | 960| UPLOAD_SUCCESS<sup>12+</sup> | 5 | 文件已成功上行。 | 961| UPLOAD_FAILURE<sup>12+</sup> | 6 | 文件上行失败。 | 962 963## cloudSync.optimizeStorage<sup>17+</sup> 964 965optimizeStorage(): Promise<void> 966 967优化图库已同步云空间的本地资源，按照本地剩余空间执行自动老化策略。使用Promise异步回调。 968 969**需要权限**：ohos.permission.CLOUDFILE_SYNC 970 971**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 972 973**系统接口**：此接口为系统接口。 974 975**返回值：** 976 977 | 类型 | 说明 | 978 | ------------------- | ---------------------------- | 979 | Promise<void> | 无返回结果的Promise对象。 | 980 981**错误码：** 982 983以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理子系统错误码](errorcode-filemanagement.md)。 984 985| 错误码ID | 错误信息 | 986| ---------------------------- | ---------- | 987| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 988| 202 | Permission verification failed, application which is not a system application uses system API. | 989| 13600001 | IPC error. | 990| 13900042 | Unknown error. | 991 992**示例：** 993 994 ```ts 995 import { BusinessError } from '@kit.BasicServicesKit'; 996 997 cloudSync.optimizeStorage().then(() => { 998 console.info("optimize storage successfully"); // 前台UX按需阻塞等待 999 }).catch((err: BusinessError) => { 1000 console.error("optimize storage failed with error message: " + err.message + ", error code: " + err.code); 1001 }); 1002 ``` 1003 1004## cloudSync.startOptimizeSpace<sup>17+</sup> 1005 1006startOptimizeSpace(optimizePara: OptimizeSpaceParam, callback?: Callback\<OptimizeSpaceProgress>): Promise<void> 1007 1008优化图库已同步云空间的本地资源，执行立即优化空间策略，对老化天数前未访问的本地图片/视频进行优化。使用Promise异步回调。 1009 1010startOptimizeSpace的使用和stopOptimizeSpace方法调用一一对应，重复开启将返回其他任务正在执行的错误信息（22400006）。 1011 1012**需要权限**：ohos.permission.CLOUDFILE_SYNC 1013 1014**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 1015 1016**系统接口**：此接口为系统接口。 1017 1018**参数：** 1019 1020| 参数名 | 类型 | 必填 | 说明 | 1021| ---------- | ------ | ---- | ---- | 1022| optimizePara | [OptimizeSpaceParam](#optimizespaceparam17) | 是 | 优化参数。 | 1023| callback | Callback<[OptimizeSpaceProgress](#optimizespaceprogress17)> | 否 | 返回优化进度。缺省情况下返回401错误，不执行清理任务 | 1024 1025**返回值：** 1026 1027 | 类型 | 说明 | 1028 | ------------------- | ---------------------------- | 1029 | Promise<void> | 无返回结果的Promise对象。 | 1030 1031**错误码：** 1032 1033以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理子系统错误码](errorcode-filemanagement.md)。 1034 1035| 错误码ID | 错误信息 | 1036| ---------------------------- | ---------- | 1037| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 1038| 202 | Permission verification failed, application which is not a system application uses system API. | 1039| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 1040| 13600001 | IPC error. | 1041| 22400005 | Inner error. | 1042| 22400006 | The same task is already in progress. | 1043 1044**示例：** 1045 1046 ```ts 1047 import { BusinessError } from '@kit.BasicServicesKit'; 1048 let para:cloudSync.OptimizeSpaceParam = {totalSize: 1073741824, agingDays: 30}; 1049 let callback = (data:cloudSync.OptimizeSpaceProgress) => { 1050 if (data.state == cloudSync.OptimizeState.FAILED) { 1051 console.info("optimize space failed"); 1052 } else if (data.state == cloudSync.OptimizeState.COMPLETED && data.progress == 100) { 1053 console.info("optimize space successfully"); 1054 } else if (data.state == cloudSync.OptimizeState.RUNNING) { 1055 console.info("optimize space progress:" + data.progress); 1056 } 1057 } 1058 cloudSync.startOptimizeSpace(para, callback).then(() => { 1059 console.info("start optimize space"); 1060 }).catch((err: BusinessError) => { 1061 console.error("start optimize space failed with error message: " + err.message + ", error code: " + err.code); 1062 }); 1063 ``` 1064 1065## cloudSync.stopOptimizeSpace<sup>17+</sup> 1066 1067stopOptimizeSpace(): void 1068 1069同步方法停止图库云图资源空间优化，和startOptimizeSpace配对使用。 1070 1071**需要权限**：ohos.permission.CLOUDFILE_SYNC 1072 1073**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 1074 1075**系统接口**：此接口为系统接口。 1076 1077**错误码：** 1078 1079以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理子系统错误码](errorcode-filemanagement.md)。 1080 1081| 错误码ID | 错误信息 | 1082| ---------------------------- | ---------- | 1083| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 1084| 202 | Permission verification failed, application which is not a system application uses system API. | 1085| 13600001 | IPC error. | 1086| 22400005 | Inner error. | 1087 1088**示例：** 1089 1090 ```ts 1091 import { BusinessError } from '@kit.BasicServicesKit'; 1092 let para:cloudSync.OptimizeSpaceParam = {totalSize: 1073741824, agingDays: 30}; 1093 let callback = (data:cloudSync.OptimizeSpaceProgress) => { 1094 if (data.state == cloudSync.OptimizeState.FAILED) { 1095 console.info("optimize space failed"); 1096 } else if (data.state == cloudSync.OptimizeState.RUNNING) { 1097 console.info("optimize space progress:" + data.progress); 1098 } 1099 } 1100 cloudSync.startOptimizeSpace(para, callback); 1101 cloudSync.stopOptimizeSpace(); // 停止空间优化 1102 ``` 1103 1104## OptimizeState<sup>17+</sup> 1105 1106优化空间状态，为枚举类型。 1107 1108**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 1109 1110**系统接口**：此接口为系统接口。 1111 1112| 名称 | 值| 说明 | 1113| ----- | ---- | ---- | 1114| RUNNING | 0 | 正在优化空间。 | 1115| COMPLETED | 1 | 优化空间成功结束。 | 1116| FAILED | 2 | 优化空间失败。 | 1117| STOPPED | 3 | 优化空间停止。 | 1118 1119## OptimizeSpaceProgress<sup>17+</sup> 1120 1121立即优化空间状态和当前进度。 1122 1123**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 1124 1125**系统接口**：此接口为系统接口。 1126 1127| 名称 | 类型 | 必填 | 说明 | 1128| ---------- | ------ | ---- | ---- | 1129| state | [OptimizeState](#optimizestate17) | 是 | 枚举值，优化空间状态。| 1130| progress | number | 是 | 优化进度百分比，范围[0,100]。| 1131 1132## OptimizeSpaceParam<sup>17+</sup> 1133 1134立即优化空间设置参数，设置优化总空间和老化天数。 1135 1136**系统能力**：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core 1137 1138**系统接口**：此接口为系统接口。 1139 1140| 名称 | 类型 | 必填 | 说明 | 1141| ---------- | ------ | ---- | ---- | 1142| totalSize | number | 是 | 优化空间总大小。查询媒体库接口获得需要老化的所有文件总大小，由应用传入，单位byte。| 1143| agingDays | number | 是 | 老化天数。系统会以当前时间为基准，优化老化天数前未访问、已同步云空间的本地图片/视频。|