如何在 HarmonyOS Next 中实现自定义 BackupExtensionAbility

6 阅读3分钟

本文旨在深入探讨华为鸿蒙HarmonyOS Next系统(截止目前API12)的技术细节,基于实际开发实践进行总结。
主要作为技术分享与交流载体,难免错漏,欢迎各位同仁提出宝贵意见和问题,以便共同进步。
本文为原创内容,任何形式的转载必须注明出处及原作者。


BackupExtensionAbility 是 HarmonyOS Next 系统中用于实现应用数据备份恢复的核心组件。通过自定义 BackupExtensionAbility 类并实现 onBackup 和 onRestore 方法,开发者可以定义应用在数据备份和恢复过程中需要执行的操作。本文将详细介绍如何在 HarmonyOS Next 中注册和配置 BackupExtensionAbility,并展示其自定义实现的基本流程。


一、BackupExtensionAbility 的注册与配置文件说明

在开发应用的备份和恢复功能之前,需先在配置文件中注册 BackupExtensionAbility,使应用能够正确地接入 HarmonyOS Next 的备份恢复框架。

1. 配置 module.json5 文件

module.json5 配置文件中,通过配置 extensionAbilities 字段来注册 BackupExtensionAbility,使系统识别该类为备份恢复组件。具体配置项如下:

  • type:设置为 "backup" 表示该扩展组件为备份恢复类型。
  • metadata:添加 "ohos.extension.backup" 项目来指定备份相关的资源。
  • srcEntry:指定 BackupExtensionAbility 类文件的路径。
{
  "extensionAbilities": [
    {
      "description": "$string:BackupExtensionAbilityDesc",
      "icon": "$media:app_icon",
      "name": "BackupExtensionAbility",
      "type": "backup",
      "exported": false,
      "metadata": [
        {
          "name": "ohos.extension.backup",
          "resource": "$profile:backup_config"
        }
      ],
      "srcEntry": "./ets/backupExtension/BackupExtension.ets"
    }
  ]
}

2. 配置备份资源文件

resources/base/profile 文件夹中,添加与 module.json5metadata.resource 字段一致的资源文件。此文件用于定义哪些应用数据和资源需要备份、是否允许恢复等配置。

以下为资源配置文件 backup_config.json 的示例:

{
  "allowToBackupRestore": true,
  "includes": [
    "/data/storage/el2/base/files/"
  ],
  "excludes": [
    "/data/storage/el2/base/files/cache/"
  ],
  "fullBackupOnly": false
}

该文件中的关键字段解释如下:

  • allowToBackupRestore:是否允许备份和恢复。
  • includes:需要备份的文件或文件夹列表。
  • excludes:无需备份的文件或文件夹列表。
  • fullBackupOnly:是否进行全量备份。

二、自定义 BackupExtensionAbility 类

配置完成后,接下来创建并自定义 BackupExtensionAbility 类,主要通过重写 onBackuponRestore 方法来定义具体的备份和恢复逻辑。

  1. onBackup:该方法用于实现数据备份逻辑。可在此方法中指定备份的文件路径、数据格式等。
  2. onRestore:该方法用于实现数据恢复逻辑。在设备升级或应用重装后,系统会自动调用此方法,将备份目录中的数据还原到应用的沙箱目录。

以下是一个基础的 BackupExtensionAbility 类实现:

import { BackupExtensionAbility, BundleVersion } from '@kit.CoreFileKit';

const TAG = `BackupExtensionAbility`;

// 自定义 BackupExtensionAbility 类export default class BackupExtension extends BackupExtensionAbility {
    // 数据备份方法
    onBackup() {
        console.log(TAG, `onBackup started, performing data backup...`);
        // 在此处编写数据备份逻辑,如指定备份路径和格式
    }

    // 数据恢复方法
    async onRestore(bundleVersion: BundleVersion): Promise<void> {
        console.log(TAG, `onRestore invoked with bundle version: ${JSON.stringify(bundleVersion)}`);
        if (bundleVersion.name.startsWith("0.0.0.0")) {
            console.log(TAG, `Performing data migration from HarmonyOS to HarmonyOS NEXT`);
            // 数据迁移处理逻辑
        } else {
            console.log(TAG, `Performing data restoration for other versions`);
        }
    }
}

三、备份和恢复数据的映射与控制

在 HarmonyOS Next 中,应用的数据通常存放于应用沙箱目录,而备份恢复框架会将这些数据迁移至备份目录。通过配置 includes 和 excludes 字段,开发者可灵活控制哪些数据需要备份,以及备份的数据恢复路径。

1. 数据目录映射

在应用数据备份中,以下几种常见目录的映射关系为:

应用数据目录备份恢复目录获取方式
/data/user_de/{userId}/{包名}//data/storage/el1/base/.backup/restore/{包名}/de/contextConstant.AreaMode.EL1
/data/user/{userId}/{包名}//data/storage/el2/base/.backup/restore/{包名}/ce/contextConstant.AreaMode.EL2
/data/media/{userId}/Android/data/{包名}//data/storage/el2/base/.backup/restore/{包名}/A/data/contextConstant.AreaMode.EL2

2. 数据存储与还原路径控制

通过 BackupExtensionAbility 的上下文对象 this.context,可以直接获取备份和恢复目录。开发者在实现 onBackup 和 onRestore 时,可以使用以下代码来读取和还原备份数据:

const deSourcePath = `${this.context.backupDir}restore/{包名}/de/`;
const ceSourcePath = `${this.context.backupDir}restore/{包名}/ce/`;

四、示例代码:onBackup 与 onRestore 的实现

以下代码示例展示了如何在 onBackup 和 onRestore 方法中实现数据备份和恢复逻辑。此示例演示了备份指定文件夹的数据,并在数据恢复过程中对不同系统版本执行特定的恢复操作。

import { BackupExtensionAbility, BundleVersion } from '@kit.CoreFileKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG = `FileBackupExtensionAbility`;

// BackupExtensionAbility 自定义实现export default class BackupExtension extends BackupExtensionAbility {
    // 数据备份逻辑
    async onBackup(): Promise<void> {
        hilog.info(0x0000, TAG, `onBackup invoked, starting data backup process...`);
        
        // 获取备份目录
        const backupPath = this.context.backupDir + "files/";
        try {
            // 执行备份逻辑
            hilog.info(0x0000, TAG, `Backing up data to path: ${backupPath}`);
            // 假设备份数据至指定目录,开发者可在此实现文件复制、打包等操作
        } catch (error) {
            hilog.error(0x0000, TAG, `Error during backup: ${error.message}`);
        }
    }

    // 数据恢复逻辑
    async onRestore(bundleVersion: BundleVersion): Promise<void> {
        hilog.info(0x0000, TAG, `onRestore invoked for bundle version: ${JSON.stringify(bundleVersion)}`);

        if (bundleVersion.name.startsWith("0.0.0.0")) {
            hilog.info(0x0000, TAG, `HarmonyOS to HarmonyOS NEXT upgrade detected, handling data migration.`);
            // 实现数据迁移逻辑
            const restorePath = `${this.context.backupDir}restore/{包名}/de/`;
            hilog.info(0x0000, TAG, `Restoring data from path: ${restorePath}`);
            // 从恢复目录中加载数据至沙箱目录
        } else {
            hilog.info(0x0000, TAG, `Standard restore for other versions.`);
        }
    }
}

在上述代码中:

  • onBackup 方法中定义了备份路径,并将应用数据存储到备份目录中。
  • onRestore 方法根据 bundleVersion 执行恢复逻辑,支持从 HarmonyOS 旧版本到 HarmonyOS NEXT 的数据迁移。

总结

通过自定义 BackupExtensionAbility 类,HarmonyOS Next 的备份恢复框架可以灵活处理应用数据的备份与恢复。咱们可以根据业务需求设置数据的备份路径、过滤条件,并在数据恢复阶段执行自定义的数据迁移策略。