GGiteeupdate zh-cn/application-dev/reference/apis-core-file-kit/js-apis-file-cloudsync-sys.md.

7ca1732b创建于 2025年3月24日历史提交

@ohos.file.cloudSync (端云同步能力)(系统接口)

该模块向应用提供端云同步能力，包括启动/停止端云同步以及启动/停止原图下载功能。

说明：

本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

当前页面仅包含本模块的系统接口，其他公开接口参见@ohos.file.cloudSync (端云同步能力)。

导入模块

import { cloudSync } from '@kit.CoreFileKit';

GallerySync

云图同步对象，用来支撑图库应用媒体资源端云同步流程。在使用前，需要先创建GallerySync实例。

constructor

constructor()

端云同步流程的构造函数，用于获取GallerySync类的实例。

系统能力：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

系统接口：该接口为系统接口。

示例：

let gallerySync = new cloudSync.GallerySync()

on

on(evt: 'progress', callback: (pg: SyncProgress) => void): void

添加同步过程事件监听。

需要权限：ohos.permission.CLOUDFILE_SYNC

系统能力：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

系统接口：该接口为系统接口。

参数：

参数名	类型	必填	说明
evt	string	是	订阅的事件类型，取值为'progress'（同步过程事件）。
callback	(pg: SyncProgress) => void	是	同步过程事件回调，回调入参为SyncProgress，返回值为void。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID	错误信息
201	Permission verification failed.
202	The caller is not a system application.
401	The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
13600001	IPC error.

示例：

let gallerySync = new cloudSync.GallerySync();

gallerySync.on('progress', (pg: cloudSync.SyncProgress) => {
  console.info("syncState：" + pg.state);
});

off

off(evt: 'progress', callback: (pg: SyncProgress) => void): void

移除同步过程事件监听。

需要权限：ohos.permission.CLOUDFILE_SYNC

系统能力：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

系统接口：该接口为系统接口。

参数：

参数名	类型	必填	说明
evt	string	是	取消订阅的事件类型，取值为'progress'（同步过程事件）。
callback	(pg: SyncProgress) => void	是	同步过程事件回调，回调入参为SyncProgress，返回值为void。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID	错误信息
201	Permission verification failed.
202	The caller is not a system application.
401	The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
13600001	IPC error.

示例：

let gallerySync = new cloudSync.GallerySync();

let callback = (pg: cloudSync.SyncProgress) => {
  console.info("gallery sync state：" + pg.state + "error type:" + pg.error);
}

gallerySync.on('progress', callback);

gallerySync.off('progress', callback);

off

off(evt: 'progress'): void

移除同步过程事件监听。

需要权限：ohos.permission.CLOUDFILE_SYNC

系统能力：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

系统接口：该接口为系统接口。

参数：

参数名	类型	必填	说明
evt	string	是	取消订阅的事件类型，取值为'progress'（同步过程事件）。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID	错误信息
201	Permission verification failed.
202	The caller is not a system application.
401	The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
13600001	IPC error.

示例：

let gallerySync = new cloudSync.GallerySync();

gallerySync.on('progress', (pg: cloudSync.SyncProgress) => {
    console.info("syncState：" + pg.state);
});

gallerySync.off('progress');

start

start(): Promise<void>

异步方法启动端云同步，以Promise形式返回结果。

需要权限：ohos.permission.CLOUDFILE_SYNC

系统能力：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

系统接口：该接口为系统接口。

返回值：

类型	说明
Promise<void>	使用Promise形式返回启动端云同步的结果。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID	错误信息
201	Permission verification failed.
202	The caller is not a system application.
401	The input parameter is invalid. Possible causes:Incorrect parameter types.
22400001	Cloud status not ready.
22400002	Network unavailable.
22400003	Low battery level.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
let gallerySync = new cloudSync.GallerySync();

gallerySync.on('progress', (pg: cloudSync.SyncProgress) => {
    console.info("syncState：" + pg.state);
});

gallerySync.start().then(() => {
    console.info("start sync successfully");
}).catch((err: BusinessError) => {
    console.error("start sync failed with error message: " + err.message + ", error code: " + err.code);
});

start

start(callback: AsyncCallback<void>): void

异步方法启动端云同步, 以callback形式返回结果。

需要权限：ohos.permission.CLOUDFILE_SYNC

系统能力：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

系统接口：该接口为系统接口。

参数：

参数名	类型	必填	说明
callback	AsyncCallback<void>	是	异步启动端云同步的回调。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID	错误信息
201	Permission verification failed.
202	The caller is not a system application.
401	The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
22400001	Cloud status not ready.
22400002	Network unavailable.
22400003	Low battery level.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
let gallerySync = new cloudSync.GallerySync();

gallerySync.start((err: BusinessError) => {
  if (err) {
    console.error("start sync failed with error message: " + err.message + ", error code: " + err.code);
  } else {
    console.info("start sync successfully");
  }
});

stop

stop(): Promise<void>

异步方法停止端云同步，以Promise形式返回结果。

说明：

调用stop接口，同步流程会停止。再次调用start接口会继续同步。

需要权限：ohos.permission.CLOUDFILE_SYNC

系统能力：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

系统接口：该接口为系统接口。

返回值：

类型	说明
Promise<void>	使用Promise形式返回停止端云同步的结果。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID	错误信息
201	Permission verification failed.
202	The caller is not a system application.
401	The input parameter is invalid. Possible causes:Incorrect parameter types.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
let gallerySync = new cloudSync.GallerySync();

gallerySync.stop().then(() => {
    console.info("stop sync successfully");
}).catch((err: BusinessError) => {
    console.error("stop sync failed with error message: " + err.message + ", error code: " + err.code);
});

stop

stop(callback: AsyncCallback<void>): void

异步方法停止端云同步，以callback形式返回结果。

说明：

调用stop接口，同步流程会停止。再次调用start接口会继续同步。

需要权限：ohos.permission.CLOUDFILE_SYNC

系统能力：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

系统接口：该接口为系统接口。

参数：

参数名	类型	必填	说明
callback	AsyncCallback<void>	是	异步停止端云同步的回调。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID	错误信息
201	Permission verification failed.
202	The caller is not a system application.
401	The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
let gallerySync = new cloudSync.GallerySync();

gallerySync.stop((err: BusinessError) => {
  if (err) {
    console.error("stop sync failed with error message: " + err.message + ", error code: " + err.code);
  } else {
    console.info("stop sync successfully");
  }
});

Download

云文件下载对象，用来支撑图库应用原图文件下载流程。在使用前，需要先创建Download实例。

constructor

constructor()

云文件下载流程的构造函数，用于获取Download类的实例。

系统能力：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

系统接口：该接口为系统接口。

示例：

let download = new cloudSync.Download()

on

on(evt: 'progress', callback: (pg: DownloadProgress) => void): void

添加云文件下载过程事件监听。

需要权限：ohos.permission.CLOUDFILE_SYNC

系统能力：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

系统接口：该接口为系统接口。

参数：

参数名	类型	必填	说明
evt	string	是	订阅的事件类型，取值为'progress'（下载过程事件）。
callback	(pg: DownloadProgress) => void	是	云文件下载过程事件回调，回调入参为DownloadProgress，返回值为void。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID	错误信息
201	Permission verification failed.
202	The caller is not a system application.
401	The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
13600001	IPC error.

示例：

let download = new cloudSync.Download();

download.on('progress', (pg: cloudSync.DownloadProgress) => {
  console.info("download state：" + pg.state);
});

off

off(evt: 'progress', callback: (pg: DownloadProgress) => void): void

移除云文件下载过程事件监听。

需要权限：ohos.permission.CLOUDFILE_SYNC

系统能力：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

系统接口：该接口为系统接口。

参数：

参数名	类型	必填	说明
evt	string	是	取消订阅的事件类型，取值为'progress'（同步过程事件）。
callback	(pg: DownloadProgress) => void	是	云文件下载过程事件回调，回调入参为DownloadProgress, 返回值为void。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID	错误信息
201	Permission verification failed.
202	The caller is not a system application.
401	The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
13600001	IPC error.

示例：

let download = new cloudSync.Download();

let callback = (pg: cloudSync.DownloadProgress) => {
  console.info("download state：" + pg.state);
}

download.on('progress', callback);

download.off('progress', callback);

off

off(evt: 'progress'): void

移除云文件下载过程事件监听。

需要权限：ohos.permission.CLOUDFILE_SYNC

系统能力：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

系统接口：该接口为系统接口。

参数：

参数名	类型	必填	说明
evt	string	是	取消订阅的事件类型，取值为'progress'（下载过程事件）。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID	错误信息
201	Permission verification failed.
202	The caller is not a system application.
401	The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
13600001	IPC error.

示例：

let download = new cloudSync.Download();

download.on('progress', (pg: cloudSync.DownloadProgress) => {
    console.info("download state:" + pg.state);
});

download.off('progress');

start

start(uri: string): Promise<void>

异步方法启动云文件下载，以Promise形式返回结果。

需要权限：ohos.permission.CLOUDFILE_SYNC

系统能力：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

系统接口：该接口为系统接口。

参数：

参数名	类型	必填	说明
uri	string	是	待下载文件uri。

返回值：

类型	说明
Promise<void>	使用Promise形式返回启动云文件下载的结果。

示例：

import { BusinessError } from '@kit.BasicServicesKit';
let download = new cloudSync.Download();
let uri: string = "file:///media/Photo/1";

download.on('progress', (pg: cloudSync.DownloadProgress) => {
    console.info("download state:" + pg.state);
});

download.start(uri).then(() => {
    console.info("start download successfully");
}).catch((err: BusinessError) => {
    console.error("start download failed with error message: " + err.message + ", error code: " + err.code);
});

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID	错误信息
201	Permission verification failed.
202	The caller is not a system application.
401	The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
13900002	No such file or directory.
13900025	No space left on device.

start

start(uri: string, callback: AsyncCallback<void>): void

异步方法启动云文件下载，以callback形式返回结果。

需要权限：ohos.permission.CLOUDFILE_SYNC

系统能力：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

系统接口：该接口为系统接口。

参数：

参数名	类型	必填	说明
uri	string	是	待下载文件uri。
callback	AsyncCallback<void>	是	异步启动云文件下载的回调。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID	错误信息
201	Permission verification failed.
202	The caller is not a system application.
401	The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
13900002	No such file or directory.
13900025	No space left on device.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
let download = new cloudSync.Download();
let uri: string = "file:///media/Photo/1";

download.start(uri, (err: BusinessError) => {
  if (err) {
    console.error("start download failed with error message: " + err.message + ", error code: " + err.code);
  } else {
    console.info("start download successfully");
  }
});

stop

stop(uri: string): Promise<void>

异步方法停止云文件下载，以Promise形式返回结果。

说明：

调用stop接口，当前文件下载流程会终止，缓存文件会被删除，再次调用start接口会重新开始下载。

需要权限：ohos.permission.CLOUDFILE_SYNC

系统能力：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

系统接口：该接口为系统接口。

参数：

参数名	类型	必填	说明
uri	string	是	待下载文件uri。

返回值：

类型	说明
Promise<void>	使用Promise形式返回停止云文件下载的结果。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID	错误信息
201	Permission verification failed.
202	The caller is not a system application.
401	The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
let download = new cloudSync.Download();
let uri: string = "file:///media/Photo/1";

download.stop(uri).then(() => {
    console.info("stop download successfully");
}).catch((err: BusinessError) => {
    console.error("stop download failed with error message: " + err.message + ", error code: " + err.code);
});

stop

stop(uri: string, callback: AsyncCallback<void>): void

异步方法停止云文件下载，以callback形式返回结果。

说明：

调用stop接口，当前文件下载流程会终止，缓存文件会被删除，再次调用start接口会重新开始下载。

需要权限：ohos.permission.CLOUDFILE_SYNC

系统能力：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

系统接口：该接口为系统接口。

参数：

参数名	类型	必填	说明
uri	string	是	待下载文件uri。
callback	AsyncCallback<void>	是	异步停止云文件下载的回调。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID	错误信息
201	Permission verification failed.
202	The caller is not a system application.
401	The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
let download = new cloudSync.Download();
let uri: string = "file:///media/Photo/1";

download.stop(uri, (err: BusinessError) => {
  if (err) {
    console.error("stop download failed with error message: " + err.message + ", error code: " + err.code);
  } else {
    console.info("stop download successfully");
  }
});

FileSync¹²⁺

云盘同步对象，用于支撑文件管理器应用完成云盘文件的端云同步流程。在使用前，需要先创建FileSync实例。

constructor¹²⁺

constructor(bundleName: string)

端云同步流程的构造函数，用于获取FileSync类的实例。

系统能力：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

系统接口：该接口为系统接口。

参数：

参数名	类型	必填	说明
bundleName	string	是	应用包名。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID	错误信息
202	Permission verification failed, application which is not a system application uses system API.
401	The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.

示例：

let fileSync = new cloudSync.FileSync("com.ohos.demo")

CloudFileCache¹¹⁺

云盘文件缓存对象，用来支撑文件管理应用原文件下载流程。

系统能力：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

cleanCache¹¹⁺

cleanCache(uri: string): void

同步方法删除文件缓存。

需要权限：ohos.permission.CLOUDFILE_SYNC

系统能力：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

系统接口：该接口为系统接口。

参数：

参数名	类型	必填	说明
uri	string	是	待删除缓存文件的uri。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID	错误信息
201	Permission verification failed, usually the result returned by VerifyAccessToken.
202	Permission verification failed, application which is not a system application uses system API.
401	The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
13600001	IPC error.
13900002	No such file or directory.
14000002	Invalid URI.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { fileUri } from '@kit.CoreFileKit';
let fileCache = new cloudSync.CloudFileCache();
let path = "/data/storage/el2/cloud/1.txt";
let uri = fileUri.getUriFromPath(path);

try {
  fileCache.cleanCache(uri);
} catch (err) {
  let error:BusinessError = err as BusinessError;
  console.error("clean cache failed with error message: " + err.message + ", error code: " + err.code);
}

cloudSync.getFileSyncState¹¹⁺

getFileSyncState(uri: Array<string>): Promise<Array<FileSyncState>>

异步方法获取文件同步状态，以promise形式返回结果。

需要权限：ohos.permission.CLOUDFILE_SYNC

系统能力：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

系统接口：该接口为系统接口。

参数：

参数名	类型	必填	说明
uri	Array<string>	是	待获取同步状态的uri。

返回值：

类型	说明
Promise<Array<FileSyncState>>	使用Promise形式返回文件同步状态的结果。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID	错误信息
201	Permission verification failed, usually the result returned by VerifyAccessToken.
202	Permission verification failed, application which is not a system application uses system API.
401	The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
13600001	IPC error.
13900002	No such file or directory.
14000002	Invalid URI.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

let uris: Array<string> = ["file://uri"];
cloudSync.getFileSyncState(uris).then((syncStates: Array<cloudSync.FileSyncState>) => {
  for(let i = 0, len = syncStates.length; i < len; i++){
      console.info("get file sync state successfully" + syncStates[i]);
  }
}).catch((err: BusinessError) => {
    console.error("get file sync state failed with error message: " + err.message + ", error code: " + err.code);
});

cloudSync.getFileSyncState¹¹⁺

getFileSyncState(uri: Array<string>, callback: AsyncCallback<Array<FileSyncState>>): void

异步方法获取文件同步状态，以callback形式返回结果。

需要权限：ohos.permission.CLOUDFILE_SYNC

系统能力：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

系统接口：该接口为系统接口。

参数：

参数名	类型	必填	说明
uri	Array<string>	是	待获取同步状态的uri。
callback	AsyncCallback<Array<FileSyncState>>	是	异步获取文件状态的回调。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID	错误信息
201	Permission verification failed, usually the result returned by VerifyAccessToken.
202	Permission verification failed, application which is not a system application uses system API.
401	The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
13600001	IPC error.
13900002	No such file or directory.
14000002	Invalid URI.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

let uris: Array<string> = ["file://uri"];
cloudSync.getFileSyncState(uris, (err: BusinessError, syncStates: Array<cloudSync.FileSyncState>) => {
  if (err) {
    console.error("get file sync state with error message: " + err.message + ", error code: " + err.code);
  } else {
    for(let i = 0, len = syncStates.length; i < len; i++){
      console.info("get file sync state successfully" + syncStates[i]);
  }
  }
});

cloudSync.getFileSyncState¹²⁺

getFileSyncState(uri: string): FileSyncState

获取文件同步状态。

系统能力：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

系统接口：该接口为系统接口。

参数：

参数名	类型	必填	说明
uri	string	是	待下载文件uri。

返回值：

类型	说明
FileSyncState	返回给定文件的同步状态。

错误码：

以下错误码的详细介绍请参见文件管理子系统错误码。

错误码ID	错误信息
202	Permission verification failed, application which is not a system application uses system API.
401	The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
13900002	No such file or directory.
13900004	Interrupted system call.
13900010	Try again.
13900012	Permission denied by the file system.
13900031	Function not implemented.
13900042	Unknown error.
14000002	Invalid URI.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { fileUri } from '@kit.CoreFileKit';
let path = "/data/storage/el2/cloud/1.txt";
let uri = fileUri.getUriFromPath(path);
try {
  let state = fileSync.getFileSyncState(uri)
}.catch(err) {
  let error:BusinessError = err as BusinessError;
  console.error("getFileSyncStatefailed with error:" + JSON.stringify(error));
}

FileSyncState¹¹⁺

端云文件同步状态，为枚举类型。

系统能力：SystemCapability.FileManagement.DistributedFileService.CloudSync.Core

系统接口：该接口为系统接口。

名称	值	说明
UPLOADING	0	上行同步中。
DOWNLOADING	1	下行同步中。
COMPLETED	2	同步成功。
STOPPED	3	同步已停止。
TO_BE_UPLOADED¹²⁺	4	正在等待上行。
UPLOAD_SUCCESS¹²⁺	5	文件已成功上行。
UPLOAD_FAILURE¹²⁺	6	文件上行失败。

@ohos.file.cloudSync (端云同步能力)(系统接口)

导入模块

GallerySync

constructor

on

off

off

start

start

stop

stop

Download

constructor

on

off

off

start

start

stop

stop

FileSync12+

constructor12+

CloudFileCache11+

cleanCache11+

cloudSync.getFileSyncState11+

cloudSync.getFileSyncState11+

cloudSync.getFileSyncState12+

FileSyncState11+

FileSync¹²⁺

constructor¹²⁺

CloudFileCache¹¹⁺

cleanCache¹¹⁺

cloudSync.getFileSyncState¹¹⁺

cloudSync.getFileSyncState¹¹⁺

cloudSync.getFileSyncState¹²⁺

FileSyncState¹¹⁺