openharmony 鸿蒙 js-apis-file-cloudsync

2025-06-12 浏览 (1)

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

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

说明：

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

导入模块

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

SyncState12+

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

说明：

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

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

名称值说明
UPLOADING0上行同步中。
UPLOAD_FAILED1上行同步失败。
DOWNLOADING2下行同步中。
DOWNLOAD_FAILED3下行同步失败。
COMPLETED4同步成功。
STOPPED5同步已停止。

ErrorType12+

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

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

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

名称值说明
NO_ERROR0没有错误。
NETWORK_UNAVAILABLE1所有网络不可用。
WIFI_UNAVAILABLE2WIFI不可用。
BATTERY_LEVEL_LOW3低电量（低于10%）。
BATTERY_LEVEL_WARNING4告警电量（低于15%）。
CLOUD_STORAGE_FULL5云端空间不足。
LOCAL_STORAGE_FULL6本地空间不足。
DEVICE_TEMPERATURE_TOO_HIGH7设备温度过高。

SyncProgress12+

端云同步过程。

属性

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

名称类型必填说明
stateSyncState是枚举值，端云同步状态。
errorErrorType是枚举值，同步失败错误类型。

State11+

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

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

名称值说明
RUNNING0云文件正在下载中。
COMPLETED1云文件下载完成。
FAILED2云文件下载失败。
STOPPED3云文件下载已停止。

DownloadProgress11+

云文件下载过程。

属性

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

名称类型必填说明
stateState是枚举值，云文件下载状态。
processednumber是已下载数据大小，取值范围[0，9223372036854775807]（单位：Byte）。
sizenumber是当前云文件大小，取值范围[0，9223372036854775807]（单位：Byte）。
uristring是当前云文件uri。
errorDownloadErrorType是下载的错误类型。

FileSync12+

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

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

constructor12+

constructor()

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

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

错误码：

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

错误码ID错误信息
401The 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

参数：

参数名类型必填说明
eventstring是订阅的事件类型，取值为'progress'（同步过程事件）。
callbackCallback<SyncProgress>是同步过程事件回调。

错误码：

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

错误码ID错误信息
401The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
13600001IPC 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

参数：

参数名类型必填说明
eventstring是取消订阅的事件类型，取值为'progress'（同步过程事件）。
callbackCallback<SyncProgress>否同步过程事件回调， 默认值为null。

错误码：

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

错误码ID错误信息
401The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
13600001IPC 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<void>

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

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

返回值：

类型说明
Promise<void>Promise对象，无返回值。

错误码：

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

错误码ID错误信息
401The input parameter is invalid. Possible causes:Incorrect parameter types.
13600001IPC error.
22400001Cloud status not ready.
22400002Network unavailable.
22400003Low 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<void>): void

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

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

参数：

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

错误码：

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

错误码ID错误信息
401The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
13600001IPC error.
22400001Cloud status not ready.
22400002Network unavailable.
22400003Low 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<void>

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

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

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

返回值：

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

错误码：

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

错误码ID错误信息
401The input parameter is invalid. Possible causes:Incorrect parameter types.
13600001IPC 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<void>): void

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

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

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

参数：

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

错误码：

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

错误码ID错误信息
401The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
13600001IPC 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<number>

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

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

返回值：

类型说明
Promise<number>使用Promise形式返回上次同步时间。

错误码：

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

错误码ID错误信息
401The input parameter is invalid. Possible causes:Incorrect parameter types.
13600001IPC 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<number>): void

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

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

参数：

参数名类型必填说明
callbackAsyncCallback<number>是异步获取上次同步时间的回调。

错误码：

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

错误码ID错误信息
401The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
13600001IPC 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错误信息
401The 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

参数：

参数名类型必填说明
eventstring是订阅的事件类型，取值为'progress'（下载过程事件）。
callbackCallback<DownloadProgress>是云文件下载过程事件回调。

错误码：

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

错误码ID错误信息
401The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
13600001IPC 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

参数：

参数名类型必填说明
eventstring是取消订阅的事件类型，取值为'progress'（同步过程事件）。
callbackCallback<DownloadProgress>否云文件下载过程事件回调。若填写，将视为取消指定的回调函数；否则为取消当前订阅的所有回调函数。

错误码：

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

错误码ID错误信息
401The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
13600001IPC 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<void>

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

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

参数：

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

返回值：

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

错误码：

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

错误码ID错误信息
401The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
13600001IPC error.
13900002No such file or directory.
13900025No space left on device.
14000002Invalid 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<void>): void

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

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

参数：

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

错误码：

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

错误码ID错误信息
401The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
13600001IPC error.
13900002No such file or directory.
13900025No space left on device.
14000002Invalid 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<void>

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

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

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

参数：

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

返回值：

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

错误码：

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

错误码ID错误信息
401The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
13600001IPC error.
13900002No such file or directory.
14000002Invalid 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<void>): void

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

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

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

参数：

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

错误码：

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

错误码ID错误信息
401The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
13600001IPC error.
13900002No such file or directory.
14000002Invalid 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_ERROR0没有错误。
UNKNOWN_ERROR1未知错误。
NETWORK_UNAVAILABLE2网络不可用。
LOCAL_STORAGE_FULL3本地空间不足。
CONTENT_NOT_FOUND4云端空间未找到对应文件。
FREQUENT_USER_REQUESTS5用户请求过于频繁。

cloudSync.registerChange12+

registerChange(uri: string, recursion: boolean, callback: Callback<ChangeData>): void

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

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

参数：

参数名类型必填说明
uristring是待下载文件uri。
recursionboolean是true为监听该URI以及子文件和子目录，false为仅监听该URI文件。
callbackCallback<ChangeData>是返回更改的数据。

错误码：

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

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

参数：

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

错误码：

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

错误码ID错误信息
401The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
13900001Operation not permitted.
13900002No such file or directory.
13900012Permission denied.
14000002Invalid 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_ADDED0文件已新建。
NOTIFY_MODIFIED1文件已修改。
NOTIFY_DELETED2文件已被删除。
NOTIFY_RENAMED3文件被重命名或者移动。

ChangeData12+

定义变更数据。

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

名称类型必填说明
typeNotifyType是更改的通知类型。
isDirectoryArray<boolean>是指示更改的URI是否为目录。true：是目录。false：非目录。
urisArray<string>是更改的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 (备份恢复扩展能力)(系统接口)

  • 所属分类： 后端技术
  • 本文标签： 软件 鸿蒙
  • 版权声明： 本文链接 https://seaxiang.com/blog/jtXbSk