1# 跨端迁移 2 3## 概述 4 5在用户使用设备的过程中，当使用情境发生变化时（例如从室内走到户外或者周围有更适合的设备等），之前使用的设备可能已经不适合继续当前的任务，此时，用户可以选择新的设备来继续当前的任务，原设备可按需决定是否退出任务，这个就是跨端迁移的场景。常见的跨端迁移场景实例：在平板上播放的视频，迁移到智慧屏继续播放，从而获得更佳的观看体验；平板上的视频应用退出。在应用开发层面，跨端迁移指在A端运行的[UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md)迁移到B端上，完成迁移后，B端UIAbility继续任务，而A端UIAbility可按需决定是否退出。 6 7主要功能包括： 8 9- 支持用户自定义数据存储及恢复。 10 11- 支持页面路由信息和页面控件状态数据的存储及恢复。 12 13- 支持应用兼容性检测。 14 15- 支持应用根据实际使用场景动态设置迁移状态（默认迁移状态为 **ACTIVE** 激活状态）。例如，编辑类应用在编辑文本的页面下才需要迁移，其他页面不需要迁移，则可以通过[setMissionContinueState](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextsetmissioncontinuestate10)进行控制。 16 17- 支持应用动态选择是否进行页面栈恢复（默认进行页面栈信息恢复）。例如，应用希望自定义迁移到其他设备后显示的页面，则可以通过[SUPPORT_CONTINUE_PAGE_STACK_KEY](../reference/apis-ability-kit/js-apis-app-ability-wantConstant.md#params)进行控制。 18 19- 支持应用动态选择迁移成功后是否退出迁移源端应用（默认迁移成功后退出迁移源端应用）。可以通过[SUPPORT_CONTINUE_SOURCE_EXIT_KEY](../reference/apis-ability-kit/js-apis-app-ability-wantConstant.md#params)进行控制。 20 21 > **说明：** 22 > 23 > 开发者可以开发具有迁移能力的应用，迁移的触发由系统应用完成。 24 25## 运作机制 26 27 28 291. 在源端，通过[UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md)的[onContinue()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityoncontinue)回调，开发者可以保存待迁移的业务数据。例如，在浏览器应用中完成跨端迁移，开发者需要使用onContinue()回调保存页面URL等业务内容。 302. 分布式框架提供了跨设备应用页面栈以及业务数据的保存和恢复机制，它负责将数据从源端发送到对端。 313. 在对端，同一UIAbility可以通过[onCreate()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityoncreate)（冷启动）和[onNewWant()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonnewwant)（热启动）接口来恢复业务数据。 32 33## 跨端迁移流程 34 35以从对端的迁移入口发起迁移为例，跨端迁移流程如下图所示。 36 37 38 39## 约束限制 40 41- 跨端迁移要求在同一[UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md)之间进行，也就是需要相同的`bundleName`、`abilityName`和签名信息。 42- 为了获得最佳体验，使用`wantParam`传输的数据需要控制在100KB以下。 43 44## 开发步骤 45 461. 在[module.json5配置文件](../quick-start/module-configuration-file.md)的abilities标签中配置跨端迁移标签`continuable`。 47 48 ```json 49 { 50 "module": { 51 // ... 52 "abilities": [ 53 { 54 // ... 55 "continuable": true, // 配置UIAbility支持迁移 56 } 57 ] 58 } 59 } 60 ``` 61 62 > **说明：** 63 > 64 > 根据需要配置应用启动模式类型，配置详情请参照[UIAbility组件启动模式](uiability-launch-type.md)。 65 662. 在源端UIAbility中实现onContinue()回调。 67 68 当[UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md)实例触发迁移时，[onContinue()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityoncontinue)回调在源端被调用，开发者可以在该接口中通过同步或异步的方式来保存迁移数据，实现应用兼容性检测，决定是否支持此次迁移。 69 70 1. 保存迁移数据：开发者可以将要迁移的数据通过键值对的方式保存在`wantParam`参数中。 71 72 2. （可选）检测应用兼容性：开发者可以在触发迁移时从`onContinue()`入参`wantParam.version`获取到迁移对端应用的版本号，与迁移源端应用版本号做兼容校验。应用在校验版本兼容性失败后，需要提示用户迁移失败的原因。 73 74 > **说明：** 75 > 76 > 如果迁移过程中的兼容性问题对于应用迁移体验影响较小或无影响，可以跳过该步骤。 77 78 3. 返回迁移结果：开发者可以通过`onContinue()`回调的返回值决定是否支持此次迁移，接口返回值详见[AbilityConstant.OnContinueResult](../reference/apis-ability-kit/js-apis-app-ability-abilityConstant.md#oncontinueresult)。 79 80 81 `onContinue()`接口传入的`wantParam`参数中，有部分字段由系统预置，开发者可以使用这些字段用于业务处理。同时，应用在保存自己的`wantParam`参数时，也应注意不要使用同样的key值，避免被系统覆盖导致数据获取异常。详见下表： 82 83 | 字段|含义| 84 | ---- | ---- | 85 | version | 对端应用的版本号 | 86 | targetDevice | 对端设备的networkId | 87 88 ```ts 89 import { AbilityConstant, UIAbility } from '@kit.AbilityKit'; 90 import { hilog } from '@kit.PerformanceAnalysisKit'; 91 import { promptAction } from '@kit.ArkUI'; 92 93 const TAG: string = '[MigrationAbility]'; 94 const DOMAIN_NUMBER: number = 0xFF00; 95 96 export default class MigrationAbility extends UIAbility { 97 // 在onContinue中准备迁移数据 98 onContinue(wantParam: Record<string, Object>):AbilityConstant.OnContinueResult { 99 let targetVersion = wantParam.version; 100 let targetDevice = wantParam.targetDevice; 101 hilog.info(DOMAIN_NUMBER, TAG, `onContinue version = ${targetVersion}, targetDevice: ${targetDevice}`); 102 103 // 应用可根据源端版本号设置支持接续的最小兼容版本号，源端版本号可从app.json5文件中的versionCode字段获取；防止目标端版本号过低导致不兼容。 104 let versionThreshold: number = -1; // 替换为应用自己支持兼容的最小版本号 105 // 兼容性校验 106 if (targetVersion < versionThreshold) { 107 // 建议在校验版本兼容性失败后，提示用户拒绝迁移的原因 108 promptAction.showToast({ 109 message: '目标端应用版本号过低，不支持接续，请您升级应用版本后再试', 110 duration: 2000 111 }) 112 // 在兼容性校验不通过时返回MISMATCH 113 return AbilityConstant.OnContinueResult.MISMATCH; 114 } 115 116 // 将要迁移的数据保存在wantParam的自定义字段（例如data）中 117 const continueInput = '迁移的数据'; 118 wantParam['data'] = continueInput; 119 120 return AbilityConstant.OnContinueResult.AGREE; 121 } 122 } 123 ``` 124 1253. 对端设备的UIAbility通过实现[onCreate()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityoncreate)/[onNewWant()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonnewwant)接口，来恢复迁移数据和加载UI。 126 127 不同的启动方式下会调用不同的接口，详见下图。 128 129  130 131 > **说明：** 132 > 1. 在应用迁移启动时，无论是冷启动还是热启动，都会在执行完onCreate()/onNewWant()后，触发[onWindowStageRestore()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonwindowstagerestore)生命周期函数，不执行[onWindowStageCreate()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonwindowstagecreate)生命周期函数。 133 > 2. 开发者如果在`onWindowStageCreate()`中进行了一些应用启动时必要的初始化，那么迁移后需要在`onWindowStageRestore()`中执行同样的初始化操作，避免应用异常。 134 135 - 通过在onCreate()/onNewWant()回调中检查`launchReason`(CONTINUATION)，可以判断此次启动是否由迁移触发。 136 - 开发者可以从[want](../reference/apis-ability-kit/js-apis-app-ability-want.md)中获取之前保存的迁移数据。 137 - 若开发者使用系统页面栈恢复功能，则需要在onCreate()/onNewWant()执行完成前，同步调用[restoreWindowStage()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextrestorewindowstage)，来触发带有页面栈的页面恢复，详见[按需迁移页面栈](./hop-cross-device-migration.md#按需迁移页面栈)。 138 139 ```ts 140 import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 141 import { hilog } from '@kit.PerformanceAnalysisKit'; 142 143 const TAG: string = '[MigrationAbility]'; 144 const DOMAIN_NUMBER: number = 0xFF00; 145 146 export default class MigrationAbility extends UIAbility { 147 storage : LocalStorage = new LocalStorage(); 148 149 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 150 hilog.info(DOMAIN_NUMBER, TAG, '%{public}s', 'Ability onCreate'); 151 if (launchParam.launchReason === AbilityConstant.LaunchReason.CONTINUATION) { 152 // 将上述保存的数据从want.parameters中取出恢复 153 let continueInput = ''; 154 if (want.parameters !== undefined) { 155 continueInput = JSON.stringify(want.parameters.data); 156 hilog.info(DOMAIN_NUMBER, TAG, `continue input ${JSON.stringify(continueInput)}`); 157 } 158 // 触发页面恢复 159 this.context.restoreWindowStage(this.storage); 160 } 161 } 162 163 onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void { 164 hilog.info(DOMAIN_NUMBER, TAG, 'onNewWant'); 165 if (launchParam.launchReason === AbilityConstant.LaunchReason.CONTINUATION) { 166 // 将上述保存的数据从want.parameters中取出恢复 167 let continueInput = ''; 168 if (want.parameters !== undefined) { 169 continueInput = JSON.stringify(want.parameters.data); 170 hilog.info(DOMAIN_NUMBER, TAG, `continue input ${JSON.stringify(continueInput)}`); 171 } 172 // 触发页面恢复 173 this.context.restoreWindowStage(this.storage); 174 } 175 } 176 } 177 ``` 178 179## 可选配置迁移能力 180 181### 动态配置迁移能力 182 183从API version 10开始，提供了支持动态配置迁移能力的功能。即应用可以根据实际使用场景，在需要迁移时开启应用迁移能力；在业务不需要迁移时则可以关闭迁移能力。 184 185开发者可以通过调用[setMissionContinueState()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextsetmissioncontinuestate10)接口对迁移能力进行设置。默认状态下，应用的迁移能力为**ACTIVE**状态，即迁移能力开启，可以迁移。 186 187**设置迁移能力的时机** 188 189如果需要实现某些特殊场景，比如只在具体某个页面下支持迁移，或只在某个事件发生时才支持迁移，可以按照如下步骤进行配置。 190 1911. 在[UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md)的[onCreate()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityoncreate)生命周期回调中，关闭迁移能力。 192 193 ```ts 194 // MigrationAbility.ets 195 import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 196 import { hilog } from '@kit.PerformanceAnalysisKit'; 197 198 const TAG: string = '[MigrationAbility]'; 199 const DOMAIN_NUMBER: number = 0xFF00; 200 201 export default class MigrationAbility extends UIAbility { 202 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 203 // ... 204 this.context.setMissionContinueState(AbilityConstant.ContinueState.INACTIVE, (result) => { 205 hilog.info(DOMAIN_NUMBER, TAG, `setMissionContinueState INACTIVE result: ${JSON.stringify(result)}`); 206 }); 207 // ... 208 } 209 } 210 ``` 211 212 2. 如果需要在具体某个页面中打开迁移能力，可以在页面的[onPageShow()](../reference/apis-arkui/arkui-ts/ts-custom-component-lifecycle.md#onpageshow)函数中调用接口。 213 214 ```ts 215 // Page_MigrationAbilityFirst.ets 216 import { AbilityConstant, common } from '@kit.AbilityKit'; 217 import { hilog } from '@kit.PerformanceAnalysisKit'; 218 219 const TAG: string = '[MigrationAbility]'; 220 const DOMAIN_NUMBER: number = 0xFF00; 221 222 @Entry 223 @Component 224 struct Page_MigrationAbilityFirst { 225 private context = getContext(this) as common.UIAbilityContext; 226 build() { 227 // ... 228 } 229 // ... 230 onPageShow(){ 231 // 进入该页面时，将应用设置为可迁移状态 232 this.context.setMissionContinueState(AbilityConstant.ContinueState.ACTIVE, (result) => { 233 hilog.info(DOMAIN_NUMBER, TAG, '%{public}s', `setMissionContinueState ACTIVE result: ${JSON.stringify(result)}`); 234 }); 235 } 236 } 237 ``` 238 2393. 如果想要在某个组件的触发事件打开迁移能力，可以在该事件中调用。以Button组件的[onClick()](../reference/apis-arkui/arkui-ts/ts-universal-events-click.md#onclick)事件为例： 240 241 ```ts 242 // Page_MigrationAbilityFirst.ets 243 import { AbilityConstant, common } from '@kit.AbilityKit'; 244 import { hilog } from '@kit.PerformanceAnalysisKit'; 245 import { promptAction } from '@kit.ArkUI'; 246 247 const TAG: string = '[MigrationAbility]'; 248 const DOMAIN_NUMBER: number = 0xFF00; 249 250 @Entry 251 @Component 252 struct Page_MigrationAbilityFirst { 253 private context = getContext(this) as common.UIAbilityContext; 254 build() { 255 Column() { 256 //... 257 List({ initialIndex: 0 }) { 258 ListItem() { 259 Row() { 260 //... 261 } 262 .onClick(() => { 263 // 点击该按钮时，将应用设置为可迁移状态 264 this.context.setMissionContinueState(AbilityConstant.ContinueState.ACTIVE, (result) => { 265 hilog.info(DOMAIN_NUMBER, TAG, '%{public}s', `setMissionContinueState ACTIVE result: ${JSON.stringify(result)}`); 266 promptAction.showToast({ 267 message: 'Success' 268 }); 269 }); 270 }) 271 } 272 //... 273 } 274 //... 275 } 276 //... 277 } 278 } 279 ``` 280 281### 按需迁移页面栈 282 283 284> **说明：** 285> 286> 1. 当前仅支持router路由的页面栈自动恢复，暂不支持navigation路由的页面栈自动恢复。 287> 2. 若应用使用navigation路由，可以设置不进行默认页面栈迁移（配置[SUPPORT_CONTINUE_PAGE_STACK_KEY](../reference/apis-ability-kit/js-apis-app-ability-wantConstant.md#params)参数为`false`），并将需要迁移的页面（或页面栈）信息保存在want中传递，然后在目标端手动加载指定页面。 288 289[UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md)的迁移默认恢复页面栈。开发者需要在[onCreate()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityoncreate)/[onNewWant()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonnewwant)执行完成前，调用[restoreWindowStage()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#restore)，向系统传入当前的窗口上下文，用于页面栈的加载恢复。`restoreWindowStage()`接口必须在同步方法中执行。如果在异步回调中执行该接口，会导致在应用拉起时页面有概率加载失败。 290 291以`onCreate()`为例： 292 293```ts 294import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 295 296export default class MigrationAbility extends UIAbility { 297 storage : LocalStorage = new LocalStorage(); 298 299 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 300 // ... 301 // 同步执行结束前触发页面恢复 302 this.context.restoreWindowStage(this.storage); 303 } 304} 305``` 306 307如果应用不想通过系统自动恢复页面栈，可以通过配置[SUPPORT_CONTINUE_PAGE_STACK_KEY](../reference/apis-ability-kit/js-apis-app-ability-wantConstant.md#params)参数为`false`关闭该功能。开发者需要在[onWindowStageRestore()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonwindowstagerestore)中，指定迁移后进入的页面。不指定迁移后进入的页面，会导致迁移拉起后显示空白页面。 308 309例如，`UIAbility`在对端恢复时不需要按照源端页面栈进行恢复，而是需要恢复到指定页面`Page_MigrationAbilityThird`。 310 311```ts 312// MigrationAbility.ets 313import { AbilityConstant, UIAbility, wantConstant } from '@kit.AbilityKit'; 314import { hilog } from '@kit.PerformanceAnalysisKit'; 315import { window } from '@kit.ArkUI'; 316 317const TAG: string = '[MigrationAbility]'; 318const DOMAIN_NUMBER: number = 0xFF00; 319 320export default class MigrationAbility extends UIAbility { 321 onContinue(wantParam: Record<string, Object>): AbilityConstant.OnContinueResult { 322 // ... 323 // 配置不使用系统页面栈恢复 324 wantParam[wantConstant.Params.SUPPORT_CONTINUE_PAGE_STACK_KEY] = false; 325 return AbilityConstant.OnContinueResult.AGREE; 326 } 327 328 onWindowStageRestore(windowStage: window.WindowStage): void { 329 // 不使用系统页面栈恢复时，需要在此处指定应用迁移后进入的页面 330 windowStage.loadContent('pages/page_migrationability/Page_MigrationAbilityThird', (err, data) => { 331 if (err.code) { 332 hilog.error(DOMAIN_NUMBER, TAG, 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? ''); 333 return; 334 } 335 }); 336 } 337} 338``` 339 340### 按需退出 341 342[UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md)的迁移默认迁移结束后退出源端应用。如果应用希望迁移后源端应用继续运行，或需要进行其他操作（如，保存草稿、清理资源等）后再自行触发退出，不想在迁移后立即自动退出源端应用，可以通过配置[SUPPORT_CONTINUE_SOURCE_EXIT_KEY](../reference/apis-ability-kit/js-apis-app-ability-wantConstant.md#params)参数为`false`设置源端迁移后不退出。 343 344示例：`UIAbility`设置迁移成功后，源端不需要退出迁移应用。 345 346```ts 347import { AbilityConstant, UIAbility, wantConstant } from '@kit.AbilityKit'; 348import { hilog } from '@kit.PerformanceAnalysisKit'; 349 350const TAG: string = '[MigrationAbility]'; 351const DOMAIN_NUMBER: number = 0xFF00; 352 353export default class MigrationAbility extends UIAbility { 354 // ... 355 onContinue(wantParam: Record<string, Object>): AbilityConstant.OnContinueResult { 356 hilog.info(DOMAIN_NUMBER, TAG, `onContinue version = ${wantParam.version}, targetDevice: ${wantParam.targetDevice}`); 357 wantParam[wantConstant.Params.SUPPORT_CONTINUE_SOURCE_EXIT_KEY] = false; 358 return AbilityConstant.OnContinueResult.AGREE; 359 } 360} 361``` 362 363### 支持同应用中不同Ability跨端迁移 364一般情况下，跨端迁移的双端是同Ability之间，但有些应用在不同设备类型下的同一个业务Ability名称不同（即异Ability），为了支持该场景下的两个Ability之间能够完成迁移，可以通过在[module.json5](../quick-start/module-configuration-file.md)文件的abilities标签中配置迁移类型continueType进行关联。 365需要迁移的两个Ability的continueType字段取值必须保持一致，示例如下： 366 > **说明：** 367 > 368 > continueType在本应用中要保证唯一，字符串以字母、数字和下划线组成，最大长度127个字节，不支持中文。 369 > continueType标签类型为字符串数组，如果配置了多个字段，当前仅第一个字段会生效。 370 371```json 372 // 设备A 373 { 374 "module": { 375 // ... 376 "abilities": [ 377 { 378 // ... 379 "name": "Ability-deviceA", 380 "continueType": ['continueType1'], // continueType标签配置 381 } 382 ] 383 } 384 } 385 386 // 设备B 387 { 388 "module": { 389 // ... 390 "abilities": [ 391 { 392 // ... 393 "name": "Ability-deviceB", 394 "continueType": ['continueType1'], // 与设备A相同的continueType标签 395 } 396 ] 397 } 398 } 399``` 400 401### 支持快速拉起目标应用 402默认情况下，发起迁移后不会立即拉起对端的目标应用，而是等待迁移数据从源端同步到对端后，才会拉起。为了发起迁移后能够立即拉起目标应用，做到及时响应，可以通过在continueType标签中添加“_ContinueQuickStart”后缀进行生效，这样待迁移数据从源端同步到对端后只恢复迁移数据即可，提升应用迁移体验。 403 404 ```json 405 { 406 "module": { 407 // ... 408 "abilities": [ 409 { 410 // ... 411 "name": "EntryAbility" 412 "continueType": ['EntryAbility_ContinueQuickStart'], // 如果已经配置了continueType标签，可以在该标签值后添加'_ContinueQuickStart'后缀；如果没有配置continueType标签，可以使用AbilityName + '_ContinueQuickStart'作为continueType标签实现快速拉起目标应用 413 } 414 ] 415 } 416 } 417 ``` 418配置快速拉起功能后，用户触发迁移，等待迁移数据返回的过程中，并行拉起应用，减小用户等待迁移启动时间。同时需注意，应用在迁移的提前启动时，首次触发迁移会收到`launchReason`为提前拉起 (PREPARE_CONTINUATION)的[onCreate()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityoncreate)/[onNewWant()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonnewwant)请求。应用可以通过此`launchReason`，解决跳转、时序等问题，也可以在迁移快速启动时，增加loading界面，以获得更好的体验。快速拉起流程如下图所示。 419 420 421 422配置了快速拉起的应用，触发迁移时会收到两次启动请求，区别如下： 423 424| 场景 | 生命周期函数 | launchParam.launchReason | 425| -------------- | ------------------------------------------- | ------------------------------------------------- | 426| 第一次启动请求 | onCreate (冷启动)<br />或onNewWant (热启动) | AbilityConstant.LaunchReason.PREPARE_CONTINUATION | 427| 第二次启动请求 | onNewWant | AbilityConstant.LaunchReason.CONTINUATION | 428 429如果没有配置快速拉起，则触发迁移时会收到一次启动请求： 430 431| 场景 | 生命周期函数 | launchParam.launchReason | 432| ------------ | ------------------------------------------- | ----------------------------------------- | 433| 一次启动请求 | onCreate (冷启动)<br />或onNewWant (热启动) | AbilityConstant.LaunchReason.CONTINUATION | 434 435配置快速拉起功能后，对应的[onCreate()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityoncreate)/[onNewWant()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonnewwant)接口具体实现，示例代码如下： 436 437```ts 438import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 439import { hilog } from '@kit.PerformanceAnalysisKit'; 440 441const TAG: string = '[MigrationAbility]'; 442const DOMAIN_NUMBER: number = 0xFF00; 443 444export default class MigrationAbility extends UIAbility { 445 storage : LocalStorage = new LocalStorage(); 446 447 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 448 hilog.info(DOMAIN_NUMBER, TAG, '%{public}s', 'Ability onCreate'); 449 450 // 1.已配置快速拉起功能，应用立即启动时触发应用生命周期回调 451 if (launchParam.launchReason === AbilityConstant.LaunchReason.PREPARE_CONTINUATION) { 452 //若应用迁移数据较大，可在此处添加加载页面(页面中显示loading等) 453 //可处理应用自定义跳转、时序等问题 454 // ... 455 } 456 } 457 458 onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void { 459 hilog.info(DOMAIN_NUMBER, TAG, 'onNewWant'); 460 461 // 1.已配置快速拉起功能，应用立即启动时触发应用生命周期回调 462 if (launchParam.launchReason === AbilityConstant.LaunchReason.PREPARE_CONTINUATION) { 463 //若应用迁移数据较大，可在此处添加加载页面(页面中显示loading等) 464 //可处理应用自定义跳转、时序等问题 465 // ... 466 } 467 468 // 2.迁移数据恢复时触发应用生命周期回调 469 if (launchParam.launchReason === AbilityConstant.LaunchReason.CONTINUATION) { 470 // 将上述保存的数据从want.parameters中取出恢复 471 let continueInput = ''; 472 if (want.parameters !== undefined) { 473 continueInput = JSON.stringify(want.parameters.data); 474 hilog.info(DOMAIN_NUMBER, TAG, `continue input ${JSON.stringify(continueInput)}`); 475 } 476 // 触发页面恢复 477 this.context.restoreWindowStage(this.storage); 478 } 479 } 480} 481``` 482 483快速拉起目标应用时，应用的[onWindowStageCreate()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonwindowstagecreate)和[onWindowStageRestore()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonwindowstagerestore)回调会被依次触发。通常在onWindowStageCreate()中，开发者会调用[loadContent()](../reference/apis-arkui/js-apis-window.md#loadcontent9)加载页面，该接口会抛出一个异步任务加载首页，该异步任务与onWindowStageRestore()无同步关系。如果在onWindowStageRestore()中使用UI接口（如路由接口），其调用时机可能早于首页加载。为保证正常加载顺序，可以使用[setTimeout()](../reference/common/js-apis-timer.md#settimeout)抛出异步任务执行相关操作。详细见示例代码。 484 485示例代码如下： 486 487```ts 488import { UIAbility } from '@kit.AbilityKit'; 489import { hilog } from '@kit.PerformanceAnalysisKit'; 490import { UIContext, window } from '@kit.ArkUI'; 491 492export default class EntryAbility extends UIAbility { 493 private uiContext: UIContext | undefined = undefined; 494 495 // ... 496 497 onWindowStageCreate(windowStage: window.WindowStage): void { 498 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate'); 499 500 windowStage.loadContent('pages/Index', (err) => { 501 if (err.code) { 502 hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? ''); 503 return; 504 } 505 this.uiContext = windowStage.getMainWindowSync().getUIContext(); 506 hilog.info(0x0000, 'testTag', 'Succeeded in loading the content.'); 507 }); 508 } 509 510 onWindowStageRestore(windowStage: window.WindowStage): void { 511 setTimeout(() => { 512 // 抛出异步任务执行路由，保证其执行位于首页加载之后。 513 this.uiContext?.getRouter().pushUrl({ 514 url: 'pages/examplePage' 515 }); 516 }, 0); 517 } 518 519 // ... 520} 521``` 522 523## 跨端迁移中的数据迁移 524 525当前推荐两种不同的数据迁移方式，开发者可以根据实际使用需要进行选择。 526 > **说明：** 527 > 528 > 部分ArkUI组件支持通过配置`restoreId`的方式，在迁移后将特定状态恢复到对端设备。详情请见[分布式迁移标识](../reference/apis-arkui/arkui-ts/ts-universal-attributes-restoreId.md)。 529 > 530 > 如果涉及分布式数据对象迁移时应注意： 531 > 532 > API 11及以前版本涉及分布式数据对象迁移前，需要执行如下操作。 533 > 1. 申请`ohos.permission.DISTRIBUTED_DATASYNC`权限，配置方式请参见[声明权限](../security/AccessToken/declare-permissions.md)。 534 > 535 > 2. 在应用首次启动时弹窗向用户申请授权，使用方式请参见[向用户申请授权](../security/AccessToken/request-user-authorization.md)。 536 537### 使用wantParam迁移数据 538 539在需要迁移的数据较少（100KB以下）时，开发者可以选择在`wantParam`中增加字段进行数据迁移。示例如下： 540 541```ts 542import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 543import { hilog } from '@kit.PerformanceAnalysisKit'; 544 545const TAG: string = '[MigrationAbility]'; 546const DOMAIN_NUMBER: number = 0xFF00; 547 548export default class MigrationAbility extends UIAbility { 549 storage: LocalStorage = new LocalStorage(); 550 551 // 源端保存 552 onContinue(wantParam: Record<string, Object>): AbilityConstant.OnContinueResult { 553 // 将要迁移的数据保存在wantParam的自定义字段（例如data）中 554 const continueInput = '迁移的数据'; 555 wantParam['data'] = continueInput; 556 return AbilityConstant.OnContinueResult.AGREE; 557 } 558 559 // 对端恢复 560 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 561 if (launchParam.launchReason === AbilityConstant.LaunchReason.CONTINUATION) { 562 // 将上述保存的数据取出恢复 563 let continueInput = ''; 564 if (want.parameters !== undefined) { 565 continueInput = JSON.stringify(want.parameters.data); 566 hilog.info(DOMAIN_NUMBER, TAG, `continue input ${continueInput}`); 567 } 568 // 触发页面恢复 569 this.context.restoreWindowStage(this.storage); 570 } 571 } 572 573 onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void { 574 if (launchParam.launchReason === AbilityConstant.LaunchReason.CONTINUATION) { 575 let continueInput = ''; 576 if (want.parameters !== undefined) { 577 continueInput = JSON.stringify(want.parameters.data); 578 hilog.info(DOMAIN_NUMBER, TAG, `continue input ${JSON.stringify(continueInput)}`); 579 } 580 // 触发页面恢复 581 this.context.restoreWindowStage(this.storage); 582 } 583 } 584} 585``` 586 587### 使用分布式数据对象迁移数据 588 589当需要迁移的数据较大（100KB以上）或需要迁移文件时，可以使用[分布式数据对象](../reference/apis-arkdata/js-apis-data-distributedobject.md)。原理与接口说明详见[分布式数据对象跨设备数据同步](../database/data-sync-of-distributed-data-object.md)。 590 591 > **说明：** 592 > 593 > 自API 12起，由于直接使用[跨设备文件访问](../file-management/file-access-across-devices.md)实现文件的迁移难以获取文件同步完成的时间，为了保证更高的成功率，文件数据的迁移不建议继续通过该方式实现，推荐使用分布式数据对象携带资产的方式进行。开发者此前通过跨设备文件访问实现的文件迁移依然生效。 594 595#### 基础数据的迁移 596 597使用分布式数据对象，需要在源端[onContinue()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityoncontinue)接口中进行数据保存，并在对端的[onCreate()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityoncreate)/[onNewWant()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonnewwant)接口中进行数据恢复。 598 599在源端，将需要迁移的数据保存到分布式数据对象[DataObject](../reference/apis-arkdata/js-apis-data-distributedobject.md#dataobject)中。 600 601- 在onContinue()接口中使用[create()](../reference/apis-arkdata/js-apis-data-distributedobject.md#distributeddataobjectcreate9)接口创建分布式数据对象，将所要迁移的数据填充到分布式数据对象数据中。 602- 调用[genSessionId()](../reference/apis-arkdata/js-apis-data-distributedobject.md#distributeddataobjectgensessionid)接口生成数据对象组网id，并使用该id调用[setSessionId()](../reference/apis-arkdata/js-apis-data-distributedobject.md#setsessionid9)加入组网，激活分布式数据对象。 603- 使用[save()](../reference/apis-arkdata/js-apis-data-distributedobject.md#save9)接口将已激活的分布式数据对象持久化，确保源端退出后对端依然可以获取到数据。 604- 将生成的`sessionId`通过`want`传递到对端，供对端激活同步使用。 605 606> **注意** 607> 608> 1. 分布式数据对象需要先激活，再持久化，因此必须在`setSessionId()`后调用save()接口。 609> 2. 对于源端迁移后需要退出的应用，为了防止数据未保存完成应用就退出，应采用`await`的方式等待save()接口执行完毕。从API 12 起，`onContinue()`接口提供了`async`版本供该场景使用。 610> 3. 当前，`wantParams`中`sessionId`字段在迁移流程中被系统占用，建议开发者在`wantParams`中定义其他key值存储该id，避免数据异常。 611 612示例代码如下： 613 614```ts 615// 导入模块 616import { distributedDataObject } from '@kit.ArkData'; 617import { UIAbility, AbilityConstant } from '@kit.AbilityKit'; 618import { BusinessError } from '@kit.BasicServicesKit'; 619import { hilog } from '@kit.PerformanceAnalysisKit'; 620 621const TAG: string = '[MigrationAbility]'; 622const DOMAIN_NUMBER: number = 0xFF00; 623 624// 业务数据定义 625class ParentObject { 626 mother: string 627 father: string 628 629 constructor(mother: string, father: string) { 630 this.mother = mother 631 this.father = father 632 } 633} 634 635// 支持字符、数字、布尔值、对象的传递 636class SourceObject { 637 name: string | undefined 638 age: number | undefined 639 isVis: boolean | undefined 640 parent: ParentObject | undefined 641 642 constructor(name: string | undefined, age: number | undefined, isVis: boolean | undefined, parent: ParentObject | undefined) { 643 this.name = name 644 this.age = age 645 this.isVis = isVis 646 this.parent = parent 647 } 648} 649 650export default class MigrationAbility extends UIAbility { 651 d_object?: distributedDataObject.DataObject; 652 653 async onContinue(wantParam: Record<string, Object>): Promise<AbilityConstant.OnContinueResult> { 654 // ... 655 let parentSource: ParentObject = new ParentObject('jack mom', 'jack Dad'); 656 let source: SourceObject = new SourceObject("jack", 18, false, parentSource); 657 658 // 创建分布式数据对象 659 this.d_object = distributedDataObject.create(this.context, source); 660 661 // 生成数据对象组网id，激活分布式数据对象 662 let dataSessionId: string = distributedDataObject.genSessionId(); 663 this.d_object.setSessionId(dataSessionId); 664 665 // 将组网id存在want中传递到对端 666 wantParam['dataSessionId'] = dataSessionId; 667 668 // 数据对象持久化，确保迁移后即使应用退出，对端依然能够恢复数据对象 669 // 从wantParam.targetDevice中获取到对端设备的networkId作为入参 670 await this.d_object.save(wantParam.targetDevice as string).then((result: 671 distributedDataObject.SaveSuccessResponse) => { 672 hilog.info(DOMAIN_NUMBER, TAG, `Succeeded in saving. SessionId: ${result.sessionId}`, 673 `version:${result.version}, deviceId:${result.deviceId}`); 674 }).catch((err: BusinessError) => { 675 hilog.error(DOMAIN_NUMBER, TAG, 'Failed to save. Error: ', JSON.stringify(err) ?? ''); 676 }); 677 678 return AbilityConstant.OnContinueResult.AGREE; 679 } 680} 681``` 682 683对端在[onCreate()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityoncreate)/[onNewWant()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonnewwant)中，通过加入与源端一致的分布式数据对象组网进行数据恢复。 684 685- 创建空的分布式数据对象，用于接收恢复的数据。 686- 从[want](../reference/apis-ability-kit/js-apis-app-ability-want.md)中读取分布式数据对象组网id。 687- 注册[on()](../reference/apis-arkdata/js-apis-data-distributedobject.md#onstatus9)接口监听数据变更。在收到`status`为`restore`的事件的回调中，实现数据恢复完毕时需要进行的业务操作。 688- 调用[setSessionId()](../reference/apis-arkdata/js-apis-data-distributedobject.md#setsessionid9)加入组网，激活分布式数据对象。 689 690> **注意** 691> 692> 1. 对端加入组网的分布式数据对象不能为临时变量，因为on()接口的回调可能在onCreate()/onNewWant()执行结束后才执行，临时变量被释放可能导致空指针异常。可以使用类成员变量避免该问题。 693> 2. 对端用于创建分布式数据对象的`Object`，其属性应在激活分布式数据对象前置为`undefined`，否则会导致新数据加入组网后覆盖源端数据，数据恢复失败。 694> 3. 应当在激活分布式数据对象之前，调用on()接口进行注册监听，防止错过`restore`事件导致数据恢复失败。 695 696示例代码如下： 697 698```ts 699import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 700import { distributedDataObject } from '@kit.ArkData'; 701import { hilog } from '@kit.PerformanceAnalysisKit'; 702 703const TAG: string = '[MigrationAbility]'; 704const DOMAIN_NUMBER: number = 0xFF00; 705 706// 示例数据对象定义与上同 707export default class MigrationAbility extends UIAbility { 708 d_object?: distributedDataObject.DataObject; 709 710 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 711 if (launchParam.launchReason === AbilityConstant.LaunchReason.CONTINUATION) { 712 // ... 713 // 调用封装好的分布式数据对象处理函数 714 this.handleDistributedData(want); 715 } 716 } 717 718 onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void { 719 if (launchParam.launchReason === AbilityConstant.LaunchReason.CONTINUATION) { 720 if (want.parameters !== undefined) { 721 // ... 722 // 调用封装好的分布式数据对象处理函数 723 this.handleDistributedData(want); 724 } 725 } 726 } 727 728 handleDistributedData(want: Want) { 729 // 创建空的分布式数据对象 730 let remoteSource: SourceObject = new SourceObject(undefined, undefined, undefined, undefined); 731 this.d_object = distributedDataObject.create(this.context, remoteSource); 732 733 // 读取分布式数据对象组网id 734 let dataSessionId = ''; 735 if (want.parameters !== undefined) { 736 dataSessionId = want.parameters.dataSessionId as string; 737 } 738 739 // 添加数据变更监听 740 this.d_object.on("status", (sessionId: string, networkId: string, status: 'online' | 'offline' | 'restored') => { 741 hilog.info(DOMAIN_NUMBER, TAG, "status changed " + sessionId + " " + status + " " + networkId); 742 if (status == 'restored') { 743 if (this.d_object) { 744 // 收到迁移恢复的状态时，可以从分布式数据对象中读取数据 745 hilog.info(DOMAIN_NUMBER, TAG, "restored name:" + this.d_object['name']); 746 hilog.info(DOMAIN_NUMBER, TAG, "restored parents:" + JSON.stringify(this.d_object['parent'])); 747 } 748 } 749 }); 750 751 // 激活分布式数据对象 752 this.d_object.setSessionId(dataSessionId); 753 } 754} 755``` 756 757#### 文件资产的迁移 758 759对于图片、文档等文件类数据，需要先将其转换为[资产`commonType.Asset`](../reference/apis-arkdata/js-apis-data-commonType.md#asset)类型，再封装到分布式数据对象中进行迁移。迁移实现方式与普通的分布式数据对象类似，下例中仅针对区别部分进行说明。 760 761在源端，将需要迁移的文件资产保存到分布式数据对象[DataObject](../reference/apis-arkdata/js-apis-data-distributedobject.md#dataobject)中。 762 763- 将文件资产拷贝到[分布式文件目录](application-context-stage.md#获取应用文件路径)下，相关接口与用法详见[基础文件接口](../file-management/app-file-access.md)。 764- 使用分布式文件目录下的文件创建`Asset`资产对象。 765- 将`Asset`资产对象作为分布式数据对象的根属性保存。 766 767随后，与普通数据对象的迁移的源端实现相同，可以使用该数据对象加入组网，并进行持久化保存。 768 769示例如下： 770 771```ts 772// 导入模块 773import { UIAbility, AbilityConstant } from '@kit.AbilityKit'; 774import { distributedDataObject, commonType } from '@kit.ArkData'; 775import { fileIo, fileUri } from '@kit.CoreFileKit'; 776import { hilog } from '@kit.PerformanceAnalysisKit'; 777import { BusinessError } from '@ohos.base'; 778 779const TAG: string = '[MigrationAbility]'; 780const DOMAIN_NUMBER: number = 0xFF00; 781 782// 数据对象定义 783class ParentObject { 784 mother: string 785 father: string 786 787 constructor(mother: string, father: string) { 788 this.mother = mother 789 this.father = father 790 } 791} 792 793class SourceObject { 794 name: string | undefined 795 age: number | undefined 796 isVis: boolean | undefined 797 parent: ParentObject | undefined 798 attachment: commonType.Asset | undefined // 新增资产属性 799 800 constructor(name: string | undefined, age: number | undefined, isVis: boolean | undefined, 801 parent: ParentObject | undefined, attachment: commonType.Asset | undefined) { 802 this.name = name 803 this.age = age 804 this.isVis = isVis 805 this.parent = parent 806 this.attachment = attachment; 807 } 808} 809 810export default class MigrationAbility extends UIAbility { 811 d_object?: distributedDataObject.DataObject; 812 813 async onContinue(wantParam: Record<string, Object>): Promise<AbilityConstant.OnContinueResult> { 814 // ... 815 816 // 1. 将资产写入分布式文件目录下 817 let distributedDir: string = this.context.distributedFilesDir; // 获取分布式文件目录路径 818 let fileName: string = '/test.txt'; // 文件名 819 let filePath: string = distributedDir + fileName; // 文件路径 820 821 try { 822 // 在分布式目录下创建文件 823 let file = fileIo.openSync(filePath, fileIo.OpenMode.READ_WRITE | fileIo.OpenMode.CREATE); 824 hilog.info(DOMAIN_NUMBER, TAG, 'Create file success.'); 825 // 向文件中写入内容（若资产为图片，可将图片转换为buffer后写入） 826 fileIo.writeSync(file.fd, '[Sample] Insert file content here.'); 827 // 关闭文件 828 fileIo.closeSync(file.fd); 829 } catch (error) { 830 let err: BusinessError = error as BusinessError; 831 hilog.error(DOMAIN_NUMBER, TAG, `Failed to openSync / writeSync / closeSync. Code: ${err.code}, message: ${err.message}`); 832 } 833 834 // 2. 使用分布式文件目录下的文件创建资产对象 835 let distributedUri: string = fileUri.getUriFromPath(filePath); // 获取分布式文件Uri 836 837 // 获取文件参数 838 let ctime: string = ''; 839 let mtime: string = ''; 840 let size: string = ''; 841 await fileIo.stat(filePath).then((stat: fileIo.Stat) => { 842 ctime = stat.ctime.toString(); // 创建时间 843 mtime = stat.mtime.toString(); // 修改时间 844 size = stat.size.toString(); // 文件大小 845 }) 846 847 // 创建资产对象 848 let attachment: commonType.Asset = { 849 name: fileName, 850 uri: distributedUri, 851 path: filePath, 852 createTime: ctime, 853 modifyTime: mtime, 854 size: size, 855 } 856 857 // 3. 将资产对象作为分布式数据对象的根属性，创建分布式数据对象 858 let parentSource: ParentObject = new ParentObject('jack mom', 'jack Dad'); 859 let source: SourceObject = new SourceObject("jack", 18, false, parentSource, attachment); 860 this.d_object = distributedDataObject.create(this.context, source); 861 862 // 生成组网id，激活分布式数据对象，save持久化保存 863 // ... 864 865 return AbilityConstant.OnContinueResult.AGREE; 866 } 867} 868``` 869 870对端需要先创建一个各属性为空的`Asset`资产对象作为分布式数据对象的根属性。在接收到[on()](../reference/apis-arkdata/js-apis-data-distributedobject.md#onstatus9)接口`status`为`restored`的事件的回调时，表示包括资产在内的数据同步完成，可以像获取基本数据一样获取到源端的资产对象。 871 872> **注意** 873> 874> 对端创建分布式数据对象时，`SourceObject`对象中的资产不能直接使用`undefined`初始化，需要创建一个所有属性初始值为空的Asset资产对象，使分布式对象可以识别出资产类型。 875 876```ts 877import { UIAbility, Want } from '@kit.AbilityKit'; 878import { distributedDataObject, commonType } from '@kit.ArkData'; 879import { hilog } from '@kit.PerformanceAnalysisKit'; 880 881const TAG: string = '[MigrationAbility]'; 882const DOMAIN_NUMBER: number = 0xFF00; 883 884export default class MigrationAbility extends UIAbility { 885 d_object?: distributedDataObject.DataObject; 886 887 handleDistributedData(want: Want) { 888 // ... 889 // 创建一个各属性为空的资产对象 890 let attachment: commonType.Asset = { 891 name: '', 892 uri: '', 893 path: '', 894 createTime: '', 895 modifyTime: '', 896 size: '', 897 } 898 899 // 使用该空资产对象创建分布式数据对象，其余基础属性可以直接使用undefined 900 let source: SourceObject = new SourceObject(undefined, undefined, undefined, undefined, attachment); 901 this.d_object = distributedDataObject.create(this.context, source); 902 903 this.d_object.on("status", (sessionId: string, networkId: string, status: 'online' | 'offline' | 'restored') => { 904 if (status == 'restored') { 905 if (this.d_object) { 906 // 收到监听的restored回调，表示分布式资产对象同步完成 907 hilog.info(DOMAIN_NUMBER, TAG, "restored attachment:" + JSON.stringify(this.d_object['attachment'])); 908 } 909 } 910 }); 911 // ... 912 } 913} 914``` 915 916若应用想要同步多个资产，可采用两种方式实现 917 9181. 可将每个资产作为分布式数据对象的一个根属性实现，适用于要迁移的资产数量固定的场景。 9192. 可以将资产数组传化为`Object`传递，适用于需要迁移的资产个数会动态变化的场景（如，用户选择了不定数量的图片）。当前不支持直接将资产数组作为根属性传递。 920 921其中方式1的实现可以直接参照添加一个资产的方式添加更多资产。方式2的示例如下所示： 922 923```ts 924// 导入模块 925import { distributedDataObject, commonType } from '@kit.ArkData'; 926import { UIAbility } from '@kit.AbilityKit'; 927 928// 数据对象定义 929class SourceObject { 930 name: string | undefined 931 assets: Object | undefined // 分布式数据对象的中添加一个Object属性 932 933 constructor(name: string | undefined, assets: Object | undefined) { 934 this.name = name 935 this.assets = assets; 936 } 937} 938 939export default class MigrationAbility extends UIAbility { 940 d_object?: distributedDataObject.DataObject; 941 942 // 该函数用于将资产数组转为Record 943 GetAssetsWapper(assets: commonType.Assets): Record<string, commonType.Asset> { 944 let wrapper: Record<string, commonType.Asset> = {} 945 let num: number = assets.length; 946 for (let i: number = 0; i < num; i++) { 947 wrapper[`asset${i}`] = assets[i]; 948 } 949 return wrapper; 950 } 951 952 async onContinue(wantParam: Record<string, Object>): AbilityConstant.OnContinueResult { 953 // ... 954 955 // 创建了多个资产对象 956 let attachment1: commonType.Asset = { 957 // ... 958 } 959 960 let attachment2: commonType.Asset = { 961 // ... 962 } 963 964 // 将资产对象插入资产数组 965 let assets: commonType.Assets = []; 966 assets.push(attachment1); 967 assets.push(attachment2); 968 969 // 将资产数组转为Record Object，并用于创建分布式数据对象 970 let assetsWrapper: Object = this.GetAssetsWapper(assets); 971 let source: SourceObject = new SourceObject("jack", assetsWrapper); 972 this.d_object = distributedDataObject.create(this.context, source); 973 974 // ... 975 } 976} 977``` 978 979## 验证指导 980 981为方便开发者验证已开发的可迁移应用，系统提供了一个全局任务中心demo应用`MissionCenter`作为迁移的入口。下面介绍通过安装全局任务中心来验证迁移的方式。 982 983> **说明：** 984> 985> 本文中的截图仅为参考，具体的显示界面请以实际使用的DevEco Studio和SDK的版本为准。 986 9871. 编译安装全局任务中心。 988 989 1. 为了正确编译安装全局任务中心，开发者需要替换Full-SDK，具体操作可参见[替换指南](../faqs/full-sdk-switch-guide.md)。 990 991 2. 下载[MissionCenter_Demo](https://gitee.com/openharmony/ability_dmsfwk/tree/master/services/dtbschedmgr/test/missionCenterDemo/dmsDemo/entry/src/main)示例代码。 992 993 3. 编译工程文件。 994 995 1. 新建一个工程，找到对应的文件夹替换下载文件。 996 997  998 999 2. 自动签名，编译安装。 1000 DevEco的自动签名模板默认签名权限为`normal`级。而本应用所需`ohos.permission.MANAGE_MISSIONS`权限为`system_core`级别。自动生成的签名无法获得足够的权限，所以需要将权限升级为`system_core`级别，然后签名。 1001 1. 将Sdk目录下的`openharmony\api版本 (如：10)\toolchains\lib\UnsignedReleasedProfileTemplate.json`文件中的`"apl":"normal"`改为`"apl":"system_core"`。 1002 1003 2. 点击 **file->Project Structure**。 1004 1005  1006 1007 3. 点击 **Signing Configs** 点击 **OK**。 1008 1009  1010 1011 3. 连接开发板运行生成demo。 1012 10132. 设备组网。 1014 1015 1. 打开A，B两设备的计算器。 1016 2. 点击右上角箭头选择B设备。 1017 3. 在B设备选择信任设备，弹出PIN码。 1018 4. 在A设备输入PIN码。 1019 5. 已组网成功，验证方法：在A设备输入数字，B设备同步出现则证明组网成功。 1020 10213. 发起迁移。 1022 1023 1. 在B设备打开多设备协同权限的应用，A设备打开全局任务中心demo，demo显示A设备名称和B设备名称。 1024 2. 点击B设备名称，列表显示B设备的应用卡片列表。 1025 3. 将要接续的应用卡片拖拽到A设备名称处，A设备应用被拉起。 1026 1027## 常见问题 1028 1029### Q1：迁移之后的应用，无法重新迁移回源端 1030 1031由于迁移状态的设置是Ability级别的，对端拉起的应用可能执行过自己的迁移状态设置命令（例如，冷启动时对端在[onCreate()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityoncreate)中设置了 **INACTIVE** ；热启动时对端已打开了不可迁移的页面，迁移状态为 **INACTIVE** 等情况）。为了保证迁移过后的应用依然具有可以迁移回源端的能力，应在 onCreate()/[onNewWant()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonnewwant)的迁移调用判断中，将迁移状态设置为 **ACTIVE** 。 1032 1033```ts 1034// MigrationAbility.ets 1035import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 1036import { hilog } from '@kit.PerformanceAnalysisKit'; 1037 1038const TAG: string = '[MigrationAbility]'; 1039const DOMAIN_NUMBER: number = 0xFF00; 1040 1041export default class MigrationAbility extends UIAbility { 1042 // ... 1043 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 1044 // ... 1045 if (launchParam.launchReason === AbilityConstant.LaunchReason.CONTINUATION) { 1046 // ... 1047 // 调用原因为迁移时，设置状态为可迁移，应对冷启动情况 1048 this.context.setMissionContinueState(AbilityConstant.ContinueState.ACTIVE, (result) => { 1049 hilog.info(DOMAIN_NUMBER, TAG, `setMissionContinueState ACTIVE result: ${JSON.stringify(result)}`); 1050 }); 1051 } 1052 // ... 1053 } 1054 1055 onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void { 1056 // ... 1057 // 调用原因为迁移时，设置状态为可迁移，应对热启动情况 1058 if (launchParam.launchReason === AbilityConstant.LaunchReason.CONTINUATION) { 1059 this.context.setMissionContinueState(AbilityConstant.ContinueState.ACTIVE, (result) => { 1060 hilog.info(DOMAIN_NUMBER, TAG, `setMissionContinueState ACTIVE result: ${JSON.stringify(result)}`); 1061 }); 1062 } 1063 } 1064 // ... 1065} 1066``` 1067 1068### Q2：在onWindowStageRestore()中调用loadContent()没有生效 1069 1070如果应用没有配置关闭页面栈迁移能力，系统默认对应用的页面栈进行迁移与加载。这种情况下，如果开发者在生命周期函数[onWindowStageRestore()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonwindowstagerestore)中再次通过[loadContent()](../reference/apis-arkui/js-apis-window.md#loadcontent9)等方式触发指定页面加载，则这次加载不会生效，依然恢复页面栈中的页面。 1071 1072## 相关实例 1073 1074针对跨端迁移的开发，有以下相关实例可供参考： 1075 1076[跨端迁移随手记（ArkTS）（Public SDK）（API12）](https://gitee.com/openharmony/applications_app_samples/tree/master/code/SuperFeature/DistributedAppDev/DistributedJotNote) 1077
