1# 跨端迁移（仅对系统应用开放） 2 3 4## 功能描述 5 6跨端迁移的主要工作是实现将应用当前任务（包括页面控件状态变量等）迁移到目标设备，能在目标设备上接续。主要功能包括： 7 8- 支持用户自定义数据存储及恢复。 9 10- 支持页面路由信息和页面控件状态数据的存储及恢复。 11 12- 支持应用兼容性检测。 13 14 15## 跨端迁移流程 16 17跨端迁移流程如下图所示。 18 19 **图1** 跨端迁移流程图 20 21 22 23## 约束限制 24 25- 由于“跨端迁移任务管理”能力尚未具备，开发者当前只能开发具备跨端迁移能力的应用，但不能发起迁移。 26 27- 跨端迁移要求在同UIAbility之间进行，也就是需要相同的bundleName、abilityName和签名。 28 29 30## 最佳实践 31 32为了获得最佳体验，使用wantParam传输的数据建议在100KB以下。 33 34 35## 接口说明 36 37跨端迁移主要接口如下。详细接口介绍请参见[API参考](../reference/apis/js-apis-app-ability-uiAbility.md)。 38 39 **表1** 跨端迁移接口 40 41| **接口名** | **描述** | 42| -------- | -------- | 43| onContinue(wantParam : {[key: string]: any}): OnContinueResult | 迁移发起端在该回调中保存迁移所需要的数据，同时返回是否同意迁移：<br/>- AGREE：表示同意。<br/>- REJECT：表示拒绝。<br/>- MISMATCH：表示版本不匹配。 | 44| onCreate(want: Want, param: AbilityConstant.LaunchParam): void; | 多实例应用迁移接收端在该回调中完成数据恢复，并触发页面恢复。 | 45| onNewWant(want: Want, launchParams: AbilityConstant.LaunchParam): void; | 单实例应用迁移接收端在该回调中完成数据恢复，并触发页面恢复。 | 46 47 48## 开发步骤 49 501. 在module.json5配置数据同步权限，示例代码如下。 51 52 ```json 53 { 54 "module": { 55 "requestPermissions":[ 56 { 57 "name" : "ohos.permission.DISTRIBUTED_DATASYNC", 58 } 59 ] 60 } 61 } 62 ``` 63 642. 在配置文件中配置跨端迁移相关标签字段。 65 - 配置应用支持迁移 66 在module.json5中配置continuable标签：true表示支持迁移，false表示不支持，默认为false。配置为false的UIAbility将被系统识别为无法迁移。 67 68 69 ```json 70 { 71 "module": { 72 // ... 73 "abilities": [ 74 { 75 // ... 76 "continuable": true, 77 } 78 ] 79 } 80 } 81 ``` 82 - 根据需要配置应用启动模式类型，配置详情请参照[UIAbility组件启动模式](uiability-launch-type.md)。 83 843. 申请数据同步权限，弹框示例代码。 85 86 ```ts 87 requestPermission() { 88 let context = this.context 89 let permissions: Array<string> = ['ohos.permission.DISTRIBUTED_DATASYNC'] 90 context.requestPermissionsFromUser(permissions).then((data) => { 91 console.info("Succeed to request permission from user with data: "+ JSON.stringify(data)) 92 }).catch((error) => { 93 console.info("Failed to request permission from user with error: "+ JSON.stringify(error)) 94 }) 95 } 96 ``` 97 984. 在发起端UIAbility中实现[onContinue()](../reference/apis/js-apis-app-ability-uiAbility.md#abilityoncontinue)接口。 99 当应用触发迁移时，[onContinue()](../reference/apis/js-apis-app-ability-uiAbility.md#abilityoncontinue)接口在发起端被调用，开发者可以在该接口中保存迁移数据，实现应用兼容性检测，决定是否支持此次迁移。 100 - 保存迁移数据：开发者可以将要迁移的数据通过键值对的方式保存在wantParam中。 101 102 - 应用兼容性检测：开发者可以通过从wantParam中获取目标应用的版本号与本应用版本号做兼容性校验。 103 104 - 迁移决策：开发者可以通过onContinue接口的返回值决定是否支持此次迁移，返回值信息见[接口说明](#接口说明)。 105 106 示例如下： 107 108 ```ts 109 import UIAbility from '@ohos.app.ability.UIAbility'; 110 import AbilityConstant from '@ohos.app.ability.AbilityConstant'; 111 112 onContinue(wantParam : {[key: string]: any}) { 113 console.info(`onContinue version = ${wantParam.version}, targetDevice: ${wantParam.targetDevice}`) 114 let workInput = AppStorage.Get<string>('ContinueWork'); 115 // set user input data into want params 116 wantParam["work"] = workInput // set user input data into want params 117 console.info(`onContinue input = ${wantParam["input"]}`); 118 return AbilityConstant.OnContinueResult.AGREE 119 } 120 ``` 121 1225. 在目标端设备UIAbility中实现onCreate()/onNewWant()接口，恢复迁移数据。 123 - 多实例场景onCreate实现示例 124 - 目标端设备上，在onCreate中根据launchReason判断该次启动是否为迁移LaunchReason.CONTINUATION。 125 - 开发者可以从want中获取保存的迁移数据。 126 - 完成数据恢复后，开发者需要调用restoreWindowStage来触发页面恢复。 127 128 ```ts 129 import UIAbility from '@ohos.app.ability.UIAbility'; 130 import AbilityConstant from '@ohos.app.ability.AbilityConstant'; 131 import distributedObject from '@ohos.data.distributedDataObject'; 132 133 export default class EntryAbility extends UIAbility { 134 storage : LocalStorage; 135 onCreate(want, launchParam) { 136 console.info(`EntryAbility onCreate ${AbilityConstant.LaunchReason.CONTINUATION}`) 137 if (launchParam.launchReason == AbilityConstant.LaunchReason.CONTINUATION) { 138 // get user data from want params 139 let workInput = want.parameters.work 140 console.info(`work input ${workInput}`) 141 AppStorage.SetOrCreate<string>('ContinueWork', workInput) 142 this.storage = new LocalStorage(); 143 this.context.restoreWindowStage(this.storage); 144 } 145 } 146 } 147 ``` 148 - 如果是单实例应用，则采用同样的代码实现onNewWant()接口即可。 149
