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