harmony 鸿蒙@ohos.file.cloudSync (端云同步能力)

  • 2025-06-12
  • 浏览 (2)

@ohos.file.cloudSync (端云同步能力)

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

说明:

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

导入模块

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

SyncState12+

端云同步状态,为枚举类型。

说明:

以下同步状态发生变更时,如果应用注册了同步过程事件监听,则通过回调通知应用。

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

名称 说明
UPLOADING 0 上行同步中。
UPLOAD_FAILED 1 上行同步失败。
DOWNLOADING 2 下行同步中。
DOWNLOAD_FAILED 3 下行同步失败。
COMPLETED 4 同步成功。
STOPPED 5 同步已停止。

ErrorType12+

端云同步失败类型,为枚举类型。

  • 当前阶段,同步过程中,当开启无限量使用移动数据网络,移动数据网络和WIFI均不可用时,才会返回NETWORK_UNAVAILABLE;开启无限量使用移动数据网络,若有一种类型网络可用,则能正常同步。
  • 同步过程中,非充电场景下,电量低于10%,完成当前批上行同步后停止同步,返回低电量;
  • 触发同步时,非充电场景下,若电量低于10%,则不允许同步,start接口返回对应错误。
  • 上行时,若云端空间不足,则文件上行失败,云端无该文件记录。

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

名称 说明
NO_ERROR 0 没有错误。
NETWORK_UNAVAILABLE 1 所有网络不可用。
WIFI_UNAVAILABLE 2 WIFI不可用。
BATTERY_LEVEL_LOW 3 低电量(低于10%)。
BATTERY_LEVEL_WARNING 4 告警电量(低于15%)。
CLOUD_STORAGE_FULL 5 云端空间不足。
LOCAL_STORAGE_FULL 6 本地空间不足。
DEVICE_TEMPERATURE_TOO_HIGH 7 设备温度过高。

SyncProgress12+

端云同步过程。

属性

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

名称 类型 必填 说明
state SyncState 枚举值,端云同步状态。
error ErrorType 枚举值,同步失败错误类型。

State11+

云文件下载状态,为枚举类型。

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

名称 说明
RUNNING 0 云文件正在下载中。
COMPLETED 1 云文件下载完成。
FAILED 2 云文件下载失败。
STOPPED 3 云文件下载已停止。

DownloadProgress11+

云文件下载过程。

属性

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

名称 类型 必填 说明
state State 枚举值,云文件下载状态。
processed number 已下载数据大小,取值范围[0,9223372036854775807](单位:Byte)。
size number 当前云文件大小,取值范围[0,9223372036854775807](单位:Byte)。
uri string 当前云文件uri。
error DownloadErrorType 下载的错误类型。

FileSync12+

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

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

constructor12+

constructor()

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

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

错误码:

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

错误码ID 错误信息
401 The input parameter is invalid. Possible causes:Incorrect parameter types.

示例:

  let fileSync = new cloudSync.FileSync()

on12+

on(event: ‘progress’, callback: Callback<SyncProgress>): void

添加同步过程事件监听。

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

参数:

参数名 类型 必填 说明
event string 订阅的事件类型,取值为’progress’(同步过程事件)。
callback Callback<SyncProgress> 同步过程事件回调。

错误码:

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

错误码ID 错误信息
401 The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
13600001 IPC error.

示例:

  let fileSync = new cloudSync.FileSync();
  let callback = (pg: cloudSync.SyncProgress) => {
    console.info("file sync state:" + pg.state + "error type:" + pg.error);
  }

  fileSync.on('progress', callback);

off12+

off(event: ‘progress’, callback?: Callback<SyncProgress>): void

移除同步过程事件监听。

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

参数:

参数名 类型 必填 说明
event string 取消订阅的事件类型,取值为’progress’(同步过程事件)。
callback Callback<SyncProgress> 同步过程事件回调, 默认值为null。

错误码:

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

错误码ID 错误信息
401 The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
13600001 IPC error.

示例:

  let fileSync = new cloudSync.FileSync();

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

  fileSync.on('progress', callback);

  fileSync.off('progress', callback);

start12+

start(): Promise&lt;void&gt;

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

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

返回值:

类型 说明
Promise&lt;void&gt; Promise对象,无返回值。

错误码:

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

错误码ID 错误信息
401 The input parameter is invalid. Possible causes:Incorrect parameter types.
13600001 IPC error.
22400001 Cloud status not ready.
22400002 Network unavailable.
22400003 Low battery level.

示例:

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

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

  fileSync.on('progress', callback);

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

start12+

start(callback: AsyncCallback&lt;void&gt;): void

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

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

参数:

参数名 类型 必填 说明
callback AsyncCallback&lt;void&gt; 异步启动端云同步的回调。

错误码:

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

错误码ID 错误信息
401 The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
13600001 IPC error.
22400001 Cloud status not ready.
22400002 Network unavailable.
22400003 Low battery level.

示例:

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

  fileSync.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");
    }
  });

stop12+

stop(): Promise&lt;void&gt;

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

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

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

返回值:

类型 说明
Promise&lt;void&gt; 使用Promise形式返回停止端云同步的结果。

错误码:

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

错误码ID 错误信息
401 The input parameter is invalid. Possible causes:Incorrect parameter types.
13600001 IPC error.

示例:

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

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

stop12+

stop(callback: AsyncCallback&lt;void&gt;): void

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

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

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

参数:

参数名 类型 必填 说明
callback AsyncCallback&lt;void&gt; 异步停止端云同步的回调。

错误码:

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

错误码ID 错误信息
401 The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
13600001 IPC error.

示例:

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

  fileSync.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");
    }
  });

getLastSyncTime12+

getLastSyncTime(): Promise&lt;number&gt;

异步方法获取上次同步时间,以promise形式返回结果。

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

返回值:

类型 说明
Promise&lt;number&gt; 使用Promise形式返回上次同步时间。

错误码:

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

错误码ID 错误信息
401 The input parameter is invalid. Possible causes:Incorrect parameter types.
13600001 IPC error.

示例:

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

  fileSync.getLastSyncTime().then((timeStamp: number) => {
    let date = new Date(timeStamp);
    console.info("get last sync time successfully:"+ date);
  }).catch((err: BusinessError) => {
    console.error("get last sync time failed with error message: " + err.message + ", error code: " + err.code);
  });

getLastSyncTime12+

getLastSyncTime(callback: AsyncCallback&lt;number&gt;): void

异步方法获取上次同步时间,以callback形式返回结果。

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

参数:

参数名 类型 必填 说明
callback AsyncCallback&lt;number&gt; 异步获取上次同步时间的回调。

错误码:

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

错误码ID 错误信息
401 The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
13600001 IPC error.

示例:

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

  fileSync.getLastSyncTime((err: BusinessError, timeStamp: number) => {
    if (err) {
      console.error("get last sync time with error message: " + err.message + ", error code: " + err.code);
    } else {
      let date = new Date(timeStamp);
      console.info("get last sync time successfully:"+ date);
    }
  });

CloudFileCache11+

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

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

construct11+

constructor()

云盘文件缓存流程的构造函数,用于获取CloudFileCache类的实例。

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

错误码:

错误码ID 错误信息
401 The input parameter is invalid. Possible causes:Incorrect parameter types.

示例:

  let fileCache = new cloudSync.CloudFileCache();

on11+

on(event: ‘progress’, callback: Callback<DownloadProgress>): void

添加云盘文件缓存过程事件监听。

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

参数:

参数名 类型 必填 说明
event string 订阅的事件类型,取值为’progress’(下载过程事件)。
callback Callback<DownloadProgress> 云文件下载过程事件回调。

错误码:

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

错误码ID 错误信息
401 The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
13600001 IPC error.

示例:

  import { BusinessError } from '@kit.BasicServicesKit';
  let fileCache = new cloudSync.CloudFileCache();
  let callback = (pg: cloudSync.DownloadProgress) => {
    console.info("download state:" + pg.state);
  };

  try {
    fileCache.on('progress', callback);
  } catch (e) {
    const error = e as BusinessError;
    console.error(`Error code: ${error.code}, message: ${error.message}`);
  }

off11+

off(event: ‘progress’, callback?: Callback<DownloadProgress>): void

移除云盘文件缓存过程事件监听。

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

参数:

参数名 类型 必填 说明
event string 取消订阅的事件类型,取值为’progress’(同步过程事件)。
callback Callback<DownloadProgress> 云文件下载过程事件回调。若填写,将视为取消指定的回调函数;否则为取消当前订阅的所有回调函数。

错误码:

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

错误码ID 错误信息
401 The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
13600001 IPC error.

示例:

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

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

  try {
    fileCache.on('progress', callback);
    fileCache.off('progress', callback);
  } catch (e) {
    const error = e as BusinessError;
    console.error(`Error code: ${error.code}, message: ${error.message}`);
  }

start11+

start(uri: string): Promise&lt;void&gt;

异步方法启动云盘文件缓存,以Promise形式返回结果。

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

参数:

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

返回值:

类型 说明
Promise&lt;void&gt; 使用Promise形式返回启动云文件下载的结果。

错误码:

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

错误码ID 错误信息
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.
13900025 No space left on device.
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.on('progress', (pg: cloudSync.DownloadProgress) => {
      console.info("download state:" + pg.state);
    });
  } catch (e) {
    const error = e as BusinessError;
    console.error(`Error code: ${error.code}, message: ${error.message}`);
  }

  fileCache.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);
  });

start11+

start(uri: string, callback: AsyncCallback&lt;void&gt;): void

异步方法启动云盘文件缓存,以callback形式返回结果。

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

参数:

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

错误码:

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

错误码ID 错误信息
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.
13900025 No space left on device.
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);

  fileCache.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");
    }
  });

stop11+

stop(uri: string, needClean?: boolean): Promise&lt;void&gt;

异步方法停止云盘文件缓存,以Promise形式返回结果。

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

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

参数:

参数名 类型 必填 说明
uri string 待下载文件uri。
needClean12+ boolean 是否删除已下载的文件。默认值为false表示删除;true表示不删除。
从API version12开始支持该参数。

返回值:

类型 说明
Promise&lt;void&gt; 使用Promise形式返回停止云文件下载的结果。

错误码:

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

错误码ID 错误信息
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);

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

stop11+

stop(uri: string, callback: AsyncCallback&lt;void&gt;): void

异步方法停止云盘文件缓存,以callback形式返回结果。

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

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

参数:

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

错误码:

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

错误码ID 错误信息
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);

  fileCache.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");
    }
  });

DownloadErrorType11+

端云下载错误类型,为枚举类型。

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

名称 说明
NO_ERROR 0 没有错误。
UNKNOWN_ERROR 1 未知错误。
NETWORK_UNAVAILABLE 2 网络不可用。
LOCAL_STORAGE_FULL 3 本地空间不足。
CONTENT_NOT_FOUND 4 云端空间未找到对应文件。
FREQUENT_USER_REQUESTS 5 用户请求过于频繁。

cloudSync.registerChange12+

registerChange(uri: string, recursion: boolean, callback: Callback&lt;ChangeData&gt;): void

订阅监听指定文件的变化通知。

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

参数:

参数名 类型 必填 说明
uri string 待下载文件uri。
recursion boolean true为监听该URI以及子文件和子目录,false为仅监听该URI文件。
callback Callback&lt;ChangeData&gt; 返回更改的数据。

错误码:

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

错误码ID 错误信息
401 The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
13900001 Operation not permitted.
13900002 No such file or directory.
13900012 Permission denied.
14000002 Invalid URI.

示例:

  import { fileUri } from '@kit.CoreFileKit';
  let path = "/data/storage/el2/cloud/1.txt";
  let uri = fileUri.getUriFromPath(path);
  let onCallback1 = (changeData: cloudSync.ChangeData) => {
    if (changeData.type == cloudSync.NotifyType.NOTIFY_ADDED) {
      //file had added, do something
    } else if (changeData.type== cloudSync.NotifyType.NOTIFY_DELETED) {
      //file had removed, do something
    }
  }
  cloudSync.registerChange(uri, false, onCallback1);
  // 取消注册监听
  cloudSync.unregisterChange(uri);

cloudSync.unregisterChange12+

unregisterChange(uri: string): void

取消订阅监听指定文件的变化通知。

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

参数:

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

错误码:

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

错误码ID 错误信息
401 The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
13900001 Operation not permitted.
13900002 No such file or directory.
13900012 Permission denied.
14000002 Invalid URI.

示例:

  import { fileUri } from '@kit.CoreFileKit';
  let path = "/data/storage/el2/cloud/1.txt";
  let uri = fileUri.getUriFromPath(path);
  let onCallback1 = (changeData: cloudSync.ChangeData) => {
    if (changeData.type == cloudSync.NotifyType.NOTIFY_ADDED) {
      //file had added, do something
    } else if (changeData.type== cloudSync.NotifyType.NOTIFY_DELETED) {
      //file had removed, do something
    }
  }
  cloudSync.registerChange(uri, false, onCallback1);
  // 取消注册监听
  cloudSync.unregisterChange(uri);

NotifyType12+

数据变更通知类型。

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

名称 说明
NOTIFY_ADDED 0 文件已新建。
NOTIFY_MODIFIED 1 文件已修改。
NOTIFY_DELETED 2 文件已被删除。
NOTIFY_RENAMED 3 文件被重命名或者移动。

ChangeData12+

定义变更数据。

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

名称 类型 必填 说明
type NotifyType 更改的通知类型。
isDirectory Array&lt;boolean&gt; 指示更改的URI是否为目录。true:是目录。false:非目录。
uris Array&lt;string&gt; 更改的uris。

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Core File Kit(文件基础服务)

harmony 鸿蒙Environment

harmony 鸿蒙FileIO

harmony 鸿蒙FileShare_PolicyErrorResult

harmony 鸿蒙FileShare_PolicyInfo

harmony 鸿蒙error_code.h

harmony 鸿蒙文件管理错误码

harmony 鸿蒙FileShare

harmony 鸿蒙FileUri

harmony 鸿蒙@ohos.application.BackupExtensionAbility (备份恢复扩展能力)(系统接口)

0  赞