鸿蒙夸端迁移-应用续接源码阅读

官方demo源码地址夸端迁移一般有三个场景开发指导：①应用接续开发指导②跨设备拖曳开发指导③跨设备剪贴板开发指导开启启用应用接续能力在module.json5文件的abilities中，将continuable标签配置为“true”，表示该UIAbility可被迁移。配置为false的UIAbility将被系统识别为无法迁移且该配置默认值为false。支持应用根据实际使用场景动态设置迁移状态（默认

阿旭哟嘿

487人浏览 · 2025-04-10 18:08:15

阿旭哟嘿 · 2025-04-10 18:08:15 发布

官方demo源码地址
https://gitee.com/openharmony/applications_app_samples/tree/master/code/SuperFeature/DistributedAppDev/DistributedJotNote

迁移后地址：https://gitcode.com/openharmony

夸端迁移一般有三个场景

开发指导：

①应用接续开发指导

②跨设备拖曳开发指导

③跨设备剪贴板开发指导

开启启用应用接续能力

在module.json5文件的abilities中，将continuable标签配置为“true”，表示该UIAbility可被迁移。配置为false的UIAbility将被系统识别为无法迁移且该配置默认值为false。

可以实现的功能包括：

存储及恢复自定义数据（应用业务内容）。
存储及恢复页面路由信息和页面控件状态数据。
应用兼容性检测。
支持应用根据实际使用场景动态设置迁移状态（默认迁移状态为ACTIVE激活状态）。

如编辑类应用在编辑文本的页面下才需要迁移，其他页面不需要迁移，则可以通过setMissionContinueState进行控制。
支持应用动态选择是否进行页面栈恢复（默认进行页面栈信息恢复）。

如应用希望自定义迁移到其他设备后显示的页面，则可以通过wantConstant.Params进行控制。
支持应用动态选择流转成功后是否退出迁移源端应用（默认流转成功后退出迁移源端应用）。则可以通过@ohos.app.ability.wantConstant (wantConstant)进行控制。

目录结构

文件分析

EntryAbility.ets

onCreate

//UIAbility实例处于完全关闭状态下被创建完成后进入该生命周期回调，执行初始化业务逻辑操//作。即UIAbility实例冷启动时进入该生命周期回调。同步接口，不支持异步回调。
只会创建一次
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
  //当应用创建时申请迁移权限-DISTRIBUTED_DATASYNC
  this.checkPermissions();

  // 调用原因为迁移时，设置状态为可迁移，应对冷启动情况(保证迁移连续性)
  if (launchParam.launchReason == AbilityConstant.LaunchReason.CONTINUATION) {
 this.context.setMissionContinueState(AbilityConstant.ContinueState.ACTIVE, (result) => {
    });
  }
  // 迁移应用启动时恢复保存的迁移数据
  this.handleContinueParam(want, launchParam);
  // 初始化时：默认迁移页面栈&源端退出
  PersistentStorage.persistProp('pageStack_isON', true);
  PersistentStorage.persistProp('sourceEnd_isON', false);
}

LaunchReason

Ability初次启动原因，该类型为枚举，可配合UIAbility的onCreate(want, launchParam)方法根据launchParam.launchReason的不同类型执行相应操作。

名称	值	说明
UNKNOWN	0	未知原因。元服务API：从API version 11开始，该接口支持在元服务中使用。
START_ABILITY	1	通过startAbility接口启动Ability。元服务API：从API version 11开始，该接口支持在元服务中使用。
CALL	2	通过startAbilityByCall接口启动Ability。元服务API：从API version 11开始，该接口支持在元服务中使用。
CONTINUATION	3	跨端迁移启动Ability。元服务API：从API version 11开始，该接口支持在元服务中使用。
APP_RECOVERY	4	设置应用恢复后，应用故障时自动恢复启动Ability。元服务API：从API version 11开始，该接口支持在元服务中使用。
SHARE10+	5	通过元服务分享启动Ability。元服务API：从API version 11开始，该接口支持在元服务中使用。
AUTO_STARTUP11+	8	通过设置开机自启动来启动Ability。
INSIGHT_INTENT11+	9	通过洞察意图来启动Ability。元服务API：从API version 11开始，该接口支持在元服务中使用。
PREPARE_CONTINUATION12+	10	跨端迁移提前启动Ability。元服务API：从API version 12开始，该接口支持在元服务中使用。

handleContinueParam

handleContinueParam(want: Want, launchParam: AbilityConstant.LaunchParam) {
  // 迁移应用启动时（onCreate）&应用热启动时（onNewWant）:恢复保存的迁移数据
  if (launchParam.launchReason == AbilityConstant.LaunchReason.CONTINUATION) {
  ...省略
    //显式调用页面恢复
    this.contentStorage = new LocalStorage();
    Logger.info(TAG, 'handleContinueParam() ： ready to restore');
    this.context.restoreWindowStage(this.contentStorage);
    // 从分布式对象中恢复迁移数据
    this.getDistributedObject(want);
  }
}

onContinue

//当Ability准备迁移时触发，保存数据。
onContinue(wantParam: Record<string, Object>) {
  AppStorage.setOrCreate('isContinuation', true);
  //准备迁移数据
..省略

  // 将要迁移的数据保存在wantParam的``指定字段中
...省略

  // 每次创建分布式对象时，先将上一次的对象置空。具体实现可以看分布式对象的实现
...省略
  // 设置是否迁移页面栈
  if (AppStorage.get<boolean>('pageStack_isON')) {
    wantParam[wantConstant.Params.SUPPORT_CONTINUE_PAGE_STACK_KEY] = true;
  } else {
    wantParam[wantConstant.Params.SUPPORT_CONTINUE_PAGE_STACK_KEY] = false;
  }

  // 设置是否退出迁移源端应用
  if (AppStorage.get<boolean>('sourceEnd_isON')) {
    wantParam[wantConstant.Params.SUPPORT_CONTINUE_SOURCE_EXIT_KEY] = true;
  } else {
    wantParam[wantConstant.Params.SUPPORT_CONTINUE_SOURCE_EXIT_KEY] = false;
  }
  return AbilityConstant.OnContinueResult.AGREE;
}

want的Params操作的常量。

名称	值	说明
ABILITY_BACK_TO_OTHER_MISSION_STACK	ability.params.backToOtherMissionStack	表示是否支持跨任务链返回。元服务API：从API version 11开始，该接口支持在元服务中使用。
ABILITY_RECOVERY_RESTART10+	ohos.ability.params.abilityRecoveryRestart	指示当前Ability是否发生了故障恢复重启。元服务API：从API version 11开始，该接口支持在元服务中使用。
CONTENT_TITLE_KEY10+	ohos.extra.param.key.contentTitle	指示元服务支持分享标题的参数的操作。元服务API：从API version 11开始，该接口支持在元服务中使用。
SHARE_ABSTRACT_KEY10+	ohos.extra.param.key.shareAbstract	指示元服务支持分享内容的参数的操作。元服务API：从API version 11开始，该接口支持在元服务中使用。
SHARE_URL_KEY10+	ohos.extra.param.key.shareUrl	指示元服务支持分享链接的参数的操作。元服务API：从API version 11开始，该接口支持在元服务中使用。
SUPPORT_CONTINUE_PAGE_STACK_KEY10+	ohos.extra.param.key.supportContinuePageStack	指示在跨端迁移过程中是否迁移页面栈信息，默认值为true，自动迁移页面栈信息。元服务API：从API version 11开始，该接口支持在元服务中使用。
SUPPORT_CONTINUE_SOURCE_EXIT_KEY10+	ohos.extra.param.key.supportContinueSourceExit	指示跨端迁移源端应用是否退出，默认值为true，源端应用自动退出。元服务API：从API version 11开始，该接口支持在元服务中使用。
SHOW_MODE_KEY12+	ohos.extra.param.key.showMode	指示展示模式，值为枚举类型wantConstant.ShowMode 元服务API：从API version 12开始，该接口支持在元服务中使用。
PARAMS_STREAM12+	ability.params.stream	指示携带的文件URI要授权给目标方。对应的value必须是string类型的文件URI数组。文件URI的获取参考fileUri 元服务API：从API version 12开始，该接口支持在元服务中使用。
APP_CLONE_INDEX_KEY12+	ohos.extra.param.key.appCloneIndex	指示分身应用索引。元服务API：从API version 12开始，该接口支持在元服务中使用。
CALLER_REQUEST_CODE12+	ohos.extra.param.key.callerRequestCode	当调用startAbilityForResult或openLink拉起目标方Ability时, 需要目标方返回结果。为了确保目标方能够将结果准确返回到调用方，系统会自动生成唯一的requestCode，以标识本次调用。元服务API：从API version 12开始，该接口支持在元服务中使用。
PAGE_PATH12+	ohos.param.atomicservice.pagePath	指示页面参数路径。元服务API：从API version 12开始，该接口支持在元服务中使用。
ROUTER_NAME12+	ohos.param.atomicservice.routerName	指示页面路由名称。元服务API：从API version 12开始，该接口支持在元服务中使用。
PAGE_SOURCE_FILE12+	ohos.param.atomicservice.pageSourceFile	指示页面源文件。元服务API：从API version 12开始，该接口支持在元服务中使用。
BUILD_FUNCTION12+	ohos.param.atomicservice.buildFunction	指示生成函数的参数。元服务API：从API version 12开始，该接口支持在元服务中使用。
SUB_PACKAGE_NAME12+	ohos.param.atomicservice.subpackageName	指示子包名。元服务API：从API version 12开始，该接口支持在元服务中使用。
APP_INSTANCE_KEY14+	ohos.extra.param.key.appInstance	指示具体的应用实例。
CREATE_APP_INSTANCE_KEY14+	ohos.extra.param.key.createAppInstance	指示创建新应用实例。
CALLER_APP_CLONE_INDEX14+	ohos.param.callerAppCloneIndex	指示拉起方应用的分身索引。

AbilityConstant.OnContinueResult.AGREE 返回值说明

名称	值	说明
AGREE	0	表示同意。
REJECT	1	表示拒绝：如应用在onContinue中异常会导致迁移以后数据恢复时显示异常，则可以建议REJECT。
MISMATCH	2	表示版本不匹配：迁移发起端应用可以在onContinue中获取到迁移目标端应用的版本号，进行协商后，如果版本不匹配导致无法迁移，可以返回该错误。

onNewWant

//UIAbility实例已经启动并在前台运行过，由于某些原因切换到后台，再次启动该UIAbility实例时会回调执行该方法。即UIAbility实例热启动时进入该生命周期回调。
onNewWant(want: Want, launchParams: AbilityConstant.LaunchParam) {
  // 调用原因为迁移时，设置状态为可迁移，应对热启动情况（保证迁移连续性）
  if (launchParams.launchReason == AbilityConstant.LaunchReason.CONTINUATION) {
    this.context.setMissionContinueState(AbilityConstant.ContinueState.ACTIVE, (result) => {
  }
  //应用热启动时：恢复保存的迁移数据
  this.handleContinueParam(want, launchParams);
}

onWindowStageRestore

//窗口恢复时调用（当迁移多实例ability时，恢复WindowStage后调用）
//迁移的时候默认会把页面栈一起迁移过来，不想把页面带过来，就需要自己手动处理
onWindowStageRestore(windowStage: window.WindowStage) {
  if (AppStorage.get<boolean>('pageStack_isON') == false) {
    windowStage.loadContent('pages/Index', (err, data) => {
      if (err.code) {
        Logger.error(TAG, `Failed to load the content. Cause: ${JSON.stringify(err)}`);
        return;
      }
      Logger.info(TAG, `Succeeded in loading the content. Data: ${JSON.stringify(data)}`);
    });
  } else {
  
  }
}

onWindowStageCreate

//当WindowStage创建后调用只会创建一次
//WindowStage是一个窗口管理器,管理各个基本窗口单元，即Window实例
//Window当前窗口实例，窗口管理器管理的基本单元
onWindowStageCreate(windowStage: window.WindowStage) {
  // Main window is created, set main page for this ability
  Logger.info(TAG, 'Ability onWindowStageCreate');

  windowStage.loadContent('pages/Index', this.contentStorage);
}