1# @ohos.application.BackupExtensionAbility (备份恢复扩展能力) 2 3BackupExtensionAbility模块提供备份恢复服务相关扩展能力，为应用提供扩展的备份恢复能力。 4 5> **说明：** 6> 7> - 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> 9> - 本模块接口仅可在Stage模型下使用。 10 11## 导入模块 12 13```ts 14import { BackupExtensionAbility, BundleVersion } from '@kit.CoreFileKit'; 15``` 16 17## BundleVersion 18 19恢复时所需要的版本信息，开发者可根据配置的版本号来判断本次恢复时的应用版本数据。 20 21**系统能力**：SystemCapability.FileManagement.StorageService.Backup 22 23| 名称 | 类型 | 必填 | 说明 | 24| ---- | ------ | ---- | ---------------- | 25| code | number | 是 | 应用的版本号。 | 26| name | string | 是 | 应用的版本名称。 | 27 28## BackupExtensionAbility 29 30应用接入数据备份恢复需要通过BackupExtensionAbility实现，开发者可以通过[onBackup](#onbackup)，[onRestore](#onrestore)来实现自定义的备份恢复操作。 31 32### 属性 33 34**系统能力**：SystemCapability.FileManagement.StorageService.Backup 35 36| 名称 | 类型 | 必填 | 说明 | 37| --------------------- | ----------------------------------------------------------------- | ---- | --------------------------------------------------- | 38| context<sup>11+</sup> | [BackupExtensionContext](js-apis-file-backupextensioncontext.md) | 是 | BackupExtensionAbility的上下文环境，继承自[ExtensionContext](../apis-ability-kit/js-apis-inner-application-extensionContext.md)。 | 39 40### onBackup 41 42onBackup(): void; 43 44Extension生命周期回调，在执行备份数据时回调，由开发者提供扩展的备份数据的操作。 45 46**系统能力**：SystemCapability.FileManagement.StorageService.Backup 47 48**示例：** 49 50 ```ts 51 class BackupExt extends BackupExtensionAbility { 52 async onBackup() { 53 console.log('onBackup'); 54 } 55 } 56 ``` 57 58### onBackupEx<sup>12+</sup> 59 60onBackupEx(backupInfo: string): string | Promise<string> 61 62备份恢复框架增加扩展参数，允许应用备份、恢复时传递参数给应用 63onBackupEx与onBackup互斥，如果重写onBackupEx，则优先调用onBackupEx。 64onBackupEx返回值不能为空字符串，若onBackupEx返回值为空字符串，则会尝试调用onBackup。 65 66**系统能力**：SystemCapability.FileManagement.StorageService.Backup 67 68**参数：** 69 70| 参数名 | 类型 | 必填 | 说明 | 71|---------------| ------------------------------- | ---- |-----------------------------| 72| backupInfo |string | 是 | 扩展恢复数据的特殊处理接口中三方应用需要传递的包信息。 | 73 74> **说明：** 75> 76> 同步处理业务场景中，推荐使用示例如下。 77 78**示例：** 79 80 ```ts 81 import { BackupExtensionAbility, BundleVersion } from '@kit.CoreFileKit'; 82 83 interface ErrorInfo { 84 type: string, 85 errorCode: number, 86 errorInfo: string 87 } 88 89 class BackupExt extends BackupExtensionAbility { 90 onBackupEx(backupInfo: string): string { 91 console.log(`onBackupEx ok`); 92 let errorInfo: ErrorInfo = { 93 type: "ErrorInfo", 94 errorCode: 0, 95 errorInfo: "app customized error info" 96 } 97 return JSON.stringify(errorInfo); 98 } 99 } 100 ``` 101 102> **说明：** 103> 104> 异步处理业务场景中，推荐使用示例如下。 105 106**示例：** 107 108 ```ts 109 import { BackupExtensionAbility, BundleVersion } from '@kit.CoreFileKit'; 110 111 interface ErrorInfo { 112 type: string, 113 errorCode: number, 114 errorInfo: string 115 } 116 117 class BackupExt extends BackupExtensionAbility { 118 //异步实现 119 async onBackupEx(backupInfo: string): Promise<string> { 120 console.log(`onBackupEx ok`); 121 let errorInfo: ErrorInfo = { 122 type: "ErrorInfo", 123 errorCode: 0, 124 errorInfo: "app customized error info" 125 } 126 return JSON.stringify(errorInfo); 127 } 128 } 129 ``` 130 131### onRestore 132 133onRestore(bundleVersion: BundleVersion): void; 134 135Extension生命周期回调，在执行恢复数据时回调，由开发者提供扩展的恢复数据的操作。 136 137**系统能力**：SystemCapability.FileManagement.StorageService.Backup 138 139**参数：** 140 141| 参数名 | 类型 | 必填 | 说明 | 142| ------------- | ------------------------------- | ---- | ------------------------------ | 143| bundleVersion | [BundleVersion](#bundleversion) | 是 | 恢复时应用数据所在的版本信息。 | 144 145**示例：** 146 147 ```ts 148 import { BackupExtensionAbility, BundleVersion } from '@kit.CoreFileKit'; 149 150 class BackupExt extends BackupExtensionAbility { 151 async onRestore(bundleVersion : BundleVersion) { 152 console.log(`onRestore ok ${JSON.stringify(bundleVersion)}`); 153 } 154 } 155 ``` 156 157### onRestoreEx<sup>12+</sup> 158 159onRestoreEx(bundleVersion: BundleVersion, restoreInfo: string): string | Promise<string> 160 161Extension生命周期回调，在执行恢复数据时回调，由开发者提供扩展的恢复数据的操作，支持异步操作。 162onRestoreEx与onRestore互斥，如果重写onRestoreEx，则优先调用onRestoreEx。 163onRestoreEx返回值不能为空字符串，若onRestoreEx返回值为空字符串，则会尝试调用onRestore。 164onRestoreEx的返回值为Json格式，使用方法见示例代码。 165 166**系统能力**：SystemCapability.FileManagement.StorageService.Backup 167 168**参数：** 169 170| 参数名 | 类型 | 必填 | 说明 | 171| ------------- | ------------------------------- | ---- | ------------------------------ | 172| bundleVersion | [BundleVersion](#bundleversion) | 是 | 恢复时应用数据所在的版本信息。 | 173| restoreInfo |string | 是 | 预留字段，应用恢复过程中需要的扩展参数 | 174 175> **说明：** 176> 177> 异步处理业务场景中，推荐使用示例如下。 178 179**示例：** 180 181 ```ts 182 import { BackupExtensionAbility, BundleVersion } from '@kit.CoreFileKit'; 183 interface ErrorInfo { 184 type: string, 185 errorCode: number, 186 errorInfo: string 187 } 188 189 class BackupExt extends BackupExtensionAbility { 190 // 异步实现 191 async onRestoreEx(bundleVersion : BundleVersion, restoreInfo: string): Promise<string> { 192 console.log(`onRestoreEx ok ${JSON.stringify(bundleVersion)}`); 193 let errorInfo: ErrorInfo = { 194 type: "ErrorInfo", 195 errorCode: 0, 196 errorInfo: "app customized error info" 197 } 198 return JSON.stringify(errorInfo); 199 } 200 } 201 ``` 202 203> **说明：** 204> 205> 同步处理业务场景中，推荐使用示例如下。 206 207**示例：** 208 209```ts 210 import { BackupExtensionAbility, BundleVersion } from '@kit.CoreFileKit'; 211 interface ErrorInfo { 212 type: string, 213 errorCode: number, 214 errorInfo: string 215 } 216 217 class BackupExt extends BackupExtensionAbility { 218 // 同步实现 219 onRestoreEx(bundleVersion : BundleVersion, restoreInfo: string): string { 220 console.log(`onRestoreEx ok ${JSON.stringify(bundleVersion)}`); 221 let errorInfo: ErrorInfo = { 222 type: "ErrorInfo", 223 errorCode: 0, 224 errorInfo: "app customized error info" 225 } 226 return JSON.stringify(errorInfo); 227 } 228 } 229 ``` 230 231### onProcess<sup>12+</sup> 232 233onProcess(): string; 234 235备份恢复框架增加进度返回接口。该接口为同步接口，由应用在执行onBackup(onBackupEx)/onRestore(onRestoreEx)期间进行实现。返回应用自身处理业务的进度，返回值为json结构，使用方法见示例代码。 236 237**系统能力**：SystemCapability.FileManagement.StorageService.Backup 238 239> **说明：** 240> - onProcess可以不实现，系统有默认处理机制；若要实现，返回值结构严格按照示例代码返回。 241> - 实现onProcess时，业务需要将onBackup(onBackupEx)/onRestore(onRestoreEx)做异步实现，且需要单独开辟子线程，否则onProcess相关功能无法正常运行。具体使用方式见示例代码。 242> - onProcess() 推荐使用示例如下。 243 244**示例：** 245 246 ```ts 247 import { BackupExtensionAbility, BundleVersion } from '@kit.CoreFileKit'; 248 import { taskpool } from '@kit.ArkTS'; 249 250 interface ProgressInfo { 251 name: string, // appName 252 processed: number, // 已处理的数据 253 total: number, // 总数 254 isPercentage: boolean // 可选字段，true表示需要按百分比的格式化展示进度，false或者不实现该字段表示按具体项数展示进度 255 } 256 257 class BackupExt extends BackupExtensionAbility { 258 // 如下代码中，appJob方法为模拟的实际业务代码，args为appJob方法的参数，用于提交到taskpool中，开启子线程进行工作 259 async onBackup() { 260 console.log(`onBackup begin`); 261 let args = 100; // args为appJob方法的参数 262 let jobTask: taskpool.Task = new taskpool.LongTask(appJob, args); 263 try { 264 await taskpool.execute(jobTask, taskpool.Priority.LOW); 265 } catch (error) { 266 console.error("onBackup error." + error.message); 267 } 268 taskpool.terminateTask(jobTask); // 需要手动销毁 269 console.log(`onBackup end`); 270 } 271 272 async onRestore() { 273 console.log(`onRestore begin`); 274 let args = 100; // args为appJob方法的参数 275 let jobTask: taskpool.Task = new taskpool.LongTask(appJob, args); 276 try { 277 await taskpool.execute(jobTask, taskpool.Priority.LOW); 278 } catch (error) { 279 console.error("onRestore error." + error.message); 280 } 281 taskpool.terminateTask(jobTask); // 需要手动销毁 282 console.log(`onRestore end`); 283 } 284 285 286 onProcess(): string { 287 console.log(`onProcess begin`); 288 let process: string = `{ 289 "progressInfo":[ 290 { 291 "name": "callact", // appName 292 "processed": 100, // 已处理的数据 293 "total": 1000, //总数 294 "isPercentage", true // 可选字段，true表示需要按百分比的格式化展示进度，false或者不实现该字段表示按具体项数展示进度 295 } 296 ] 297 }`; 298 console.log(`onProcess end`); 299 return JSON.stringify(process); 300 } 301 } 302 303 @Concurrent 304 function appJob(args: number) : string { 305 // 业务实际逻辑 306 console.log(`appJob begin, args is: ` + args); 307 return "ok"; 308 } 309 ``` 310