HarmonyOS API:bundle
版本:v3.1 Beta
分布式迁移
更新时间: 2023-02-17 09:19
说明
- 进行分布式迁移时源设备和目标设备需要安装同一个应用。
 - 从API Version 7 开始,该接口不再维护,推荐使用新接口'@ohos.ability.featureAbility'。
 - 本模块首批接口从API version 4开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
 - 本模块接口仅支持在基于JS扩展的类Web开发范式下使用。
 
分布式迁移提供了一个主动迁移接口及一系列页面生命周期回调,以支持将本地业务无缝迁移到指定设备中。
注意:如果迁移到的设备上已经运行该FA,则生命周期onNewRequest将被回调。
支持设备
API  | 手机  | 平板  | 智慧屏  | 智能穿戴  | 
FeatureAbility.continueAbility  | 支持  | 支持  | 支持  | 支持  | 
onStartContinuation  | 支持  | 支持  | 支持  | 支持  | 
onSaveData  | 支持  | 支持  | 支持  | 支持  | 
onRestoreData  | 支持  | 支持  | 支持  | 支持  | 
onCompleteContinuation  | 支持  | 支持  | 支持  | 支持  | 
导入模块
无需导入
权限列表
ohos.permission.DISTRIBUTED_DATASYNC
此外,还需要在FA的onStart()中,调用requestPermissionsFromUser()方法向用户申请权限,代码示例如下:
public class MainAbility extends Ability implements IAbilityContinuation {
    @Override
    public void onStart(Intent intent) {
        super.onStart(intent); 
        // 开发者显示声明需要使用的权限
        requestPermissionsFromUser(new String[]{"ohos.permission.DISTRIBUTED_DATASYNC"}, 0);
    }
}
FeatureAbility.continueAbility
continueAbility(): Promise<Result>
主动进行FA迁移的入口。
返回值:
表1 Result
参数名  | 类型  | 非空  | 说明  | 
code  | number  | 是  | 0: 发起迁移成功 。 非0: 失败,原因见data。  | 
data  | Object  | 是  | 成功:返回null。 失败:携带错误信息,类型为String。  | 
示例:
下面的示例代码展示了一个备忘录FA从发起到完成迁移的过程。
发起迁移FA:
import prompt from '@system.prompt'
export default {
  data: {
    continueAbilityData: {
      remoteData1: 'self define continue data for distribute',
      remoteData2: {
        item1: 0,
        item2: true,
        item3: 'inner string'
      },
      remoteData3: [1, 2, 3]
    }
  },
  // shareData的数据会在onSaveData触发时与saveData一起传送到迁移目标FA,并绑定到其shareData数据段上
  // shareData的数据可以直接使用this访问。eg:this.remoteShareData1
  shareData: {
    remoteShareData1: 'share data for distribute',
    remoteShareData2: {
      item1: 0,
      item2: false,
      item3: 'inner string'
    },
    remoteShareData3: [4, 5, 6]
  },
  tryContinueAbility: async function() {
    // 应用进行迁移
    let result = await FeatureAbility.continueAbility();
    console.info("result:" + JSON.stringify(result));
  },
  onStartContinuation() {
    // 判断当前的状态是不是适合迁移
    console.info("onStartContinuation");
    return true;
  },
  onCompleteContinuation(code) {
    // 迁移操作完成,code返回结果
    console.info("CompleteContinuation: code = " + code);
  },
  onSaveData(saveData) {
    // 数据保存到savedData中进行迁移。
    var data = this.continueAbilityData;
    Object.assign(saveData, data)
  }
}迁移到FA:
onRestoreData(restoreData) {
  // 收到迁移数据,恢复。
  this.continueAbilityData = restoreData;
}
onStartContinuation
onStartContinuation(): boolean
FA发起迁移时的回调,在此回调中应用可以根据当前状态决定是否迁移。
返回值:
类型  | 说明  | 
boolean  | true表示允许进行迁移。 false表示不允许迁移。  | 
onSaveData
onSaveData(savedData: Object): void
保存状态数据的回调,开发者需要往参数对象中填入需迁移到目标设备上的数据。
参数:
参数名  | 类型  | 必填  | 说明  | 
savedData  | Object  | 是  | 出参,可以往其中填入可被序列化的自定义数据。  | 
说明
shareData中的数据在迁移时,会自动迁移到目标设备上。
onRestoreData
onRestoreData(restoreData: Object): void
恢复发起迁移时onSaveData方法保存的数据的回调。
参数:
参数名  | 类型  | 必填  | 说明  | 
restoreData  | Object  | 是  | 用于恢复应用状态的对象,其中的数据及结构由onSaveData决定  | 
onCompleteContinuation
onCompleteContinuation(code: number): void
迁移完成的回调,在调用端被触发,表示应用迁移到目标设备上的结果。
参数:
参数名  | 类型  | 必填  | 说明  | 
code  | number  | 是  | 迁移完成的结果。0:成功。 -1:失败  | 
分布式API在FA生命周期中的位置
更新时间: 2023-02-17 09:19
图1 分布式API在FA生命周期中的位置

说明
本章中未归属在某个模块下的回调接口均属于页面生命周期回调接口(如onNewRequest),与onInit / onReady 等回调接口平级。




















