HarmonyOS-鸿蒙app开发 —基于java_流转_HarmonyOS端发起跨端迁移_跨端迁移开发指导

场景介绍

开发者在应用FA中通过调用流转任务管理服务、分布式任务调度的接口，实现跨端迁移。

设备A上的应用FA向流转任务管理服务注册一个流转回调：
- Alt1-系统推荐流转：系统感知周边有可用设备后，主动为用户提供可选择流转的设备信息，并在用户完成设备选择后回调onConnected通知应用FA开始流转，将用户选择的设备B的设备信息提供给应用FA。
- Alt2-用户手动流转：系统在用户手动点击流转图标后，通过showDeviceList通知流转任务管理服务，被动为用户提供可选择交互的设备信息，并在用户完成设备选择后回调onConnected通知应用FA开始流转，将用户选择的设备B的设备信息提供给应用FA。
设备A上的应用FA通过调用分布式任务调度的能力，向设备B的应用发起跨端迁移。应用FA需要自己管理流转状态，将流转状态从IDLE迁移到CONNECTING，并上报到流转任务管理服务。
1. 设备A上的FA请求迁移。
2. 系统回调设备A上FA，及其AbilitySlice栈中所有AbilitySlice实例的IAbilityContinuation.onStartContinuation()方法，以确认当前是否可以开始迁移，onStartContinuation方法返回true，表示当前FA可以开始迁移。
3. 如果可以开始迁移，则系统回调设备A上FA，及其AbilitySlice栈中所有AbilitySlice实例的IAbilityContinuation.onSaveData()方法，以便保存迁移后恢复状态必须的数据。
4. 如果保存数据成功，则系统在设备B上启动同一个FA，并恢复AbilitySlice栈，然后回调IAbilityContinuation.onRestoreData()方法，传递设备A上FA保存的数据，应用可在此方法恢复业务状态；此后设备B上此FA从onStart()开始其生命周期回调。
5. 系统回调设备A上FA，及其AbilitySlice栈中所有AbilitySlice实例的IAbilityContinuation.onCompleteContinuation()方法，通知应用迁移成功。
6. 应用将流转状态从CONNECTING迁移到CONNECTED，并上报到流转任务管理服务。
7. 流转任务管理服务将流转状态重新置为IDLE，流转完成。
8. 应用向流转任务管理服务注销流转回调。
应用自行退出。

接口说明

流转任务管理服务提供的注册、解注册、显示设备列表、上报业务状态是实现跨端迁移的前提。开发者通过跨端迁移能力，可实现如文档跨设备编辑、视频跨设备接续播放等场景。

表1 IContinuationRegisterManager接口功能介绍
接口名	描述
void register(String bundleName, ExtraParams parameter, IContinuationDeviceCallback deviceCallback, RequestCallback requestCallback)	注册并连接到流转任务管理服务，并获取对应的注册token。参数说明： bundleName，必填，String类型，本应用包名。 params，可选，ExtraParams类型，系统推荐流转时所需的过滤条件。如系统推荐流转无特殊要求，可与showDeviceList接口的过滤条件保持一致。若需关闭系统推荐流转，ExtraParams中jsonParams传入{“isTurnOffRecommend”:true}即可。 deviceCallback，可选，设备选择列表中选择设备后的回调，返回选择设备ID。 requestCallback，可选，注册请求回调，返回应用注册后的token。 ExtraParams说明： devType，可选，待连接的设备类型。可取值（”00E”手机、”011″平板、”06D”手表、”09C”智慧屏），如”devType”:[“011”]。若为空，则支持则待连接的设备类型为手机、平板、手表和智慧屏。 targetBundleName，可选，目标应用包名。若为空，则目标应用包名与方法入参bundleName本应用包名相同。 description，可选，ability描述，用于在设备列表页面展示 jsonParams，可选，拓展参数。用于设备过滤等。示例： {“filter”:{“commonFilter”: {“system”:{“harmonyVersion”:”2.0.0″},”groupType”: “1”,”curComType”: 0x00000004, “faFilter”:{\”targetBundleName\”:\”com.xxx.yyy\”}”}},”transferScene”:1,”isTurnOffRecommend”:false,”remoteAuthenticationDescription”: “拉起HiVision扫描弹框描述”,”remoteAuthenticationPicture”:””} jsonParams说明： system：可选，String类型，待连接设备的HarmonyOS版本号，目标设备对应的harmonyVersion>=该值，如”system”:{“harmonyVersion”:”2.0.0″}。 groupType：可选，String类型。为空时，不要求是否是同帐号。本设备和待连接设备的帐号是否要求一致，可取值（1要求同帐号、1\|256不要求同帐号）,如”groupType”:”1″。 curComType：可选，int类型。为空时，不要求在同一局域网下。本设备和待连接设备是否需要在同一局域网下，可取值（0x00000004需要在同一局域网下，0x00030004不需要在同一局域网下），如”curComType”:0x00000004。 faFilter：可选，String类型。为空时，不做版本兼容性检查。要做版本兼容性检查时，需要传入目标应用包名。 transferScene：可选，int类型，默认值为0。可取值为：0-单选协同场景，设备选择面板为单选面板，设备间互斥，流转成功设备面板自动消失，流转失败设备面板不消失，且系统会维护设备的流转状态，如流转成功设备面板消失后再打开设备面板，会显示之前设备流转成功的状态；1-单选迁移场景，设备选择面板为单选面板，设备间互斥，流转成功设备面板自动消失，流转失败设备面板不消失，且系统不会维护设备的流转状态，如流转成功设备面板消失后再打开设备面板，设备流转状态为未流转；2-多选协同场景，设备选择面板为多选面板，流转成功或失败设备面板不消失，设备间不互斥，系统会维护设备的流转状态。 isTurnOffRecommend：可选，boolean类型，默认为false。true：关闭系统推荐流转；false：开启系统推荐流转。 remoteAuthenticationDescription：可选，String类型，跨账号/无账号设备进行扫码认证时，拉起对端HiVision扫描弹框描述。register接口无需传该参数，showDeviceList可按需传参。 remoteAuthenticationPicture：可选，String类型，跨账号/无账号设备进行扫码认证时，拉起对端HiVision扫描弹框显示的图片。需将图片对应的byte[]转String, Base64.encodeToString(mBuff,Base64.DEFAULT)。register接口无需传该参数，showDeviceList可按需传参。注册后，通过RequestCallback的onResult回调知道执行是否成功，返回值为<0时为失败；其他情况，表示成功，并返回本次流转任务的唯一标识token。当用户选择设备后，通过deviceCallback定义的onConnected回调获取设备的deviceID、类型、名称。
void unregister(int token, RequestCallback requestCallback)	从流转任务管理服务解注册，传入注册时获取的token进行解注册。执行后，通过RequestCallback的onResult回调知道执行是否成功。
void updateConnectStatus(int token, String deviceId, int status, RequestCallback requestCallback)	通知流转任务管理服务更新当前用户程序的连接状态，并在流转任务管理服务界面展示给用户。token、deviceId参数来自于注册流转任务管理服务的回调。status参数可以为IDLE、CONNECTING、CONNECTED、DIS_CONNECTING。如果有错误，需要上报errorCode。执行后，通过RequestCallback的onResult回调知道执行是否成功。
void showDeviceList(int token, ExtraParams parameter, RequestCallback requestCallback)	显示组网内可选择设备列表信息。该接口提供手动显示设备列表的能力，parameter参数可以指定设备过滤的条件，用于手动多端协同，支持的过滤条件与register接口相同。token参数来自于注册流转任务管理服务的回调。执行后，通过RequestCallback的onResult回调知道执行是否成功。
void disconnect()	在应用退出时，主动调用断开和流转任务管理服务的连接。

表2 IContinuationDeviceCallback接口功能介绍
接口名	描述
void onConnected(ContinuationDeviceInfo deviceInfo)	当用户从选择设备列表选择设备时调用，返回设备ID、设备类型和设备名称供开发者使用。
void onDisconnected(String deviceId)	当流转任务管理服务断开连接设备时调用。

表3 RequestCallback接口功能介绍
接口名	描述
void onResult(int result)	与流转任务管理服务交互成功时调用。当作为注册流转任务管理服务的回调对象时，注册成功后给用户程序返回对应的token。

表4 Ability/AbilitySlice接口功能介绍
接口名	描述
IContinuationRegisterManager getContinuationRegisterManager()	获取流转任务管理服务注册服务管理类，可以与流转任务管理服务进行交互，包括注册/解注册，更新设备连接状态，显示可选择设备列表等。
void continueAbility(String deviceId)	把当前FA流转到同一个分布式网络中另外一个设备上，仅支持单向流转。

表5 IAbilityContinuation接口功能介绍
接口名	描述
boolean onStartContinuation()	FA请求迁移后，系统首先回调此方法，开发者可以在此回调中决策当前是否可以执行迁移，比如，弹框让用户确认是否开始迁移。
boolean onSaveData(IntentParams saveData)	如果onStartContinuation()返回true，则系统回调此方法，开发者在此回调中保存必须传递到目标端设备上，用于恢复FA状态的数据。
boolean onRestoreData(IntentParams restoreData)	发起端设备上FA完成保存数据后，系统在目标端设备上回调此方法，开发者在此回调中接受用于恢复FA状态的数据。说明在目标端设备上的FA会重新启动其生命周期，无论其启动模式如何配置，且系统回调此方法的时机在onStart()之前。
void onCompleteContinuation(int result)	目标端设备上恢复数据一旦完成，系统就会在发起端设备上回调FA的此方法，以便通知应用迁移流程已结束。开发者可以在此检查迁移结果是否成功，并在此处理迁移结束的动作，例如，应用可以在迁移完成后终止自身生命周期。
void onFailedContinuation(int errorCode)	迁移过程中发生异常，系统会在发起端回调FA的此方法，以便通知应用迁移流程发生的异常。并不是所有异常都会回调此方法，仅局限于该接口枚举的异常。开发者可以在此检查异常信息，并在此处理迁移异常发生后的动作。例如：应用可以提醒用户此时发生的异常信息并给出处理建议。

约束与限制

每个应用注册流转任务管理服务的Ability数量上限为5个，后续新增注册的Ability会将最开始注册的覆盖。
一个应用可能包含多个FA，仅需要在支持跨端迁移的FA及其所包含的AbilitySlice中，调用或实现相关接口。
跨端迁移不支持两个设备之间分别登录不同的帐号，也就是要求多个设备是同帐号。
跨端迁移不支持对PA的迁移，只支持对FA的迁移。
跨端迁移完成时，系统不会主动关闭发起迁移的FA，开发者可以根据业务需要，主动调用terminateAbility或stopAbility关闭FA，并调用updateConnectStatus()更新设备的连接状态。
通过continueAbility进行跨端迁移过程中，远端FA首先接收到发起端FA传输的数据，再执行启动，即onRestoreData()发生在onStart()之前。
跨端迁移的数据大小限制200KB以内，即onSaveData只能传递200KB以内的数据。
迁移传输的数据，当前仅支持基础类型数据传递和系统Sequenceable对象，不支持自定义对象及文件数据传递。
FA流转过程中，在流转未完成时再次调用continueAbility发起流转，接口将会抛出状态异常，应用需要加以限制处理。
跨端迁移要求HarmonyOS 2.0以上版本才能支持，注册到流转任务管理服务时jsonParams中需要增加{“harmonyVersion”:”2.0.0″}过滤条件。

开发步骤

完成环境搭建，在DevEco Studio中，选择手机设备，Empty Feature Ability(Java)模板创建项目，在项目自动创建的MainAbility中实现IAbilityContinuation接口。

public class MainAbility extends Ability implements IAbilityContinuation {

private static final int DOMAIN_ID = 0xD001100;

private static final HiLogLabel LABEL_LOG = new HiLogLabel(3, DOMAIN_ID, “MainAbility”);

@Override

public void onStart(Intent intent) {

super.onStart(intent);

super.setMainRoute(MainAbilitySlice.class.getName());

}

// 为了方便演示，不在Ability实现流转逻辑，具体逻辑在AbilitySlice中实现

@Override

public boolean onStartContinuation() {

HiLog.info(LABEL_LOG, “onStartContinuation called”);

return true;

}

@Override

public boolean onSaveData(IntentParams saveData) {

HiLog.info(LABEL_LOG, “onSaveData called”);

return true;

}

@Override

public boolean onRestoreData(IntentParams restoreData) {

HiLog.info(LABEL_LOG, “onRestoreData called”);

return true;

}

@Override

public void onCompleteContinuation(int result) {

HiLog.info(LABEL_LOG, “onCompleteContinuation called”);

}

@Override

public void onFailedContinuation(int errorCode) {

HiLog.info(LABEL_LOG, “onFailedContinuation called”);

}

在AbilitySlice中实现一个用于控制基础功能的页面，以下演示代码逻辑都将在AbilitySlice中实现，代码示例如下：

public class MainAbilitySlice extends AbilitySlice {

@Override

public void onStart(Intent intent) {

super.onStart(intent);

// 开发者可以自行进行界面设计

// 为按钮设置统一的背景色

// 例如通过PositionLayout可以实现简单界面

PositionLayout layout = new PositionLayout(this);

LayoutConfig config = new LayoutConfig(LayoutConfig.MATCH_PARENT, LayoutConfig.MATCH_PARENT);

layout.setLayoutConfig(config);

ShapeElement buttonBg = new ShapeElement();

buttonBg.setRgbColor(new RgbColor(0, 125, 255));

super.setUIContent(layout);

}

@Override

public void onInactive() {

super.onInactive();

}

@Override

public void onActive() {

super.onActive();

}

@Override

public void onBackground() {

super.onBackground();

}

@Override

public void onForeground(Intent intent) {

super.onForeground(intent);

}

@Override

public void onStop() {

super.onStop();

}

在MainAbility对应的config.json中声明跨端迁移访问的权限：ohos.permission.DISTRIBUTED_DATASYNC。在config.json中的配置如下：

{

“module”: {

“reqPermissions”: [

{

“name”: “ohos.permission.DISTRIBUTED_DATASYNC”,

“reason”: “need”,

“usedScene”: {

“ability”: [

“MainAbility”

“when”: “inuse”

}

…

}

…

}

此外，还需要在MainAbility的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);

…

}

…

}

设置流转任务管理服务回调函数，注册流转任务管理服务，管理流转的目标设备，同时需要在流转结束时解注册流转任务管理服务。

public class MainAbilitySlice extends AbilitySlice {

// 流转应用包名

private String BUNDLE_NAME = “XXX.XXX.XXX”;

// 注册流转任务管理服务后返回的Ability token

private int abilityToken;

// 用户在设备列表中选择设备后返回的设备ID

private String selectDeviceId;

// 用户是否已发起可拉回流转流程

private boolean isReversibly = false;

// 获取流转任务管理服务管理类

private IContinuationRegisterManager continuationRegisterManager;

// 设置流转任务管理服务设备状态变更的回调

private IContinuationDeviceCallback callback = new IContinuationDeviceCallback() {

@Override

public void onConnected(ContinuationDeviceInfo deviceInfo) {

// 在用户选择设备后设置设备ID

selectDeviceId = deviceInfo.getDeviceId();

//更新选择设备后的流转状态

continuationRegisterManager.updateConnectStatus(abilityToken, selectDeviceId, DeviceConnectState.CONNECTED.getState(), null);

}

@Override

public void onDisconnected(String deviceId) {

}

};

// 设置注册流转任务管理服务回调

private RequestCallback requestCallback = new RequestCallback() {

@Override

public void onResult(int result) {

abilityToken = result;

}

};

…

@Override

public void onStart(Intent intent) {

…

continuationRegisterManager = getContinuationRegisterManager();

}

@Override

public void onStop() {

super.onStop();

// 解注册流转任务管理服务

continuationRegisterManager.unregister(abilityToken, null);

// 断开流转任务管理服务连接

continuationRegisterManager.disconnect();

}

为不同功能设置相应的控制按钮。

// 建议开发者按照自己的界面进行按钮设计,示例代码仅供参考

private static final int OFFSET_X = 100;

private static final int OFFSET_Y = 100;

private static final int ADD_OFFSET_Y = 150;

private static final int BUTTON_WIDTH = 800;

private static final int BUTTON_HEIGHT = 100;

private static final int TEXT_SIZE = 50;

private int offsetY = 0;

private Button createButton(String text, ShapeElement buttonBg) {

Button button = new Button(this);

button.setContentPosition(OFFSET_X, OFFSET_Y + offsetY);

offsetY += ADD_OFFSET_Y;

button.setWidth(BUTTON_WIDTH);

button.setHeight(BUTTON_HEIGHT);

button.setTextSize(TEXT_SIZE);

button.setTextColor(Color.YELLOW);

button.setText(text);

button.setBackground(buttonBg);

return button;

}

// 按照顺序在PositionLayout中依次添加按钮的示例

private void addComponents(PositionLayout linear, ShapeElement buttonBg) {

// 构建显示注册流转任务管理服务的按钮

Button btnRegister = createButton(“register”, buttonBg);

btnRegister.setClickedListener(mRegisterListener);

linear.addComponent(btnRegister);

// 构建显示设备列表的按钮

Button btnShowDeviceList = createButton(“ShowDeviceList”, buttonBg);

btnShowDeviceList.setClickedListener(mShowDeviceListListener);

linear.addComponent(btnShowDeviceList);

// 构建跨端迁移FA的按钮

Button btnContinueRemoteFA = createButton(“ContinueRemoteFA”, buttonBg);

btnContinueRemoteFA.setClickedListener(mContinueAbilityListener);

linear.addComponent(btnContinueRemoteFA);

// 构建可拉回迁移FA的按钮

Button btnContinueReversibly = createButton(“ContinueReversibly”, buttonBg);

btnContinueReversibly.setClickedListener(mContinueReversiblyListener);

linear.addComponent(btnContinueReversibly);

// 构建拉回FA的按钮

Button btnReverseContinue = createButton(“ReverseContinuation”, buttonBg);

btnReverseContinue.setClickedListener(mReverseContinueListener);

linear.addComponent(btnReverseContinue);

}

@Override

public void onStart(Intent intent) {

…

//添加功能按钮布局

addComponents(layout, buttonBg);

super.setUIContent(layout);

}

注册流转任务管理服务。

// 注册流转任务管理服务

private Component.ClickedListener mRegisterListener = new Component.ClickedListener() {

@Override

public void onClick(Component arg0) {

HiLog.info(LABEL_LOG, “register call.”);

//增加过滤条件

ExtraParams params = new ExtraParams();

String[] devTypes = new String[]{ExtraParams.DEVICETYPE_SMART_PAD, ExtraParams.DEVICETYPE_SMART_PHONE};

params.setDevType(devTypes);

String jsonParams = “{‘filter’:{‘commonFilter’:{‘system’:{‘harmonyVersion’:’2.0.0′},’groupType’:’1|256′,’curComType’: 0x00030004,’faFilter’:'{\”localVersionCode\”:1,\”localMinCompatibleVersionCode\”:2,\”targetBundleName\”: \”com.xxx.yyy\”}’}},’transferScene’:0,’remoteAuthenticationDescription’: ‘拉起HiVision扫描弹框描述’,’remoteAuthenticationPicture’:”}”;

params.setJsonParams(jsonParams);

continuationRegisterManager.register(BUNDLE_NAME, params, callback, requestCallback);

}

};

通过流转任务管理服务提供的showDeviceList()接口获取选择设备列表，用户选择设备后在IContinuationDeviceCallback回调中获取设备ID。

// 显示设备列表，获取设备信息

private ClickedListener mShowDeviceListListener = new ClickedListener() {

@Override

public void onClick(Component arg0) {

// 设置过滤设备类型

ExtraParams params = new ExtraParams();

String[] devTypes = new String[]{ExtraParams.DEVICETYPE_SMART_PAD, ExtraParams.DEVICETYPE_SMART_PHONE};

params.setDevType(devTypes);

params.setJsonParams(jsonParams);

// 显示选择设备列表

continuationRegisterManager.showDeviceList(abilityToken, params, null);

}

};

可使用两种方法实现FA的迁移。
- 方法一：直接迁移FA，迁移后不可回迁，具体方法请参见9。
- 方法二：迁移一个支持回迁的FA，迁移后还可将FA拉回到本端。具体方法请参见10。

将运行时的FA迁移到目标设备，实现业务在设备间无缝迁移。

// 跨端迁移FA

private ClickedListener mContinueAbilityListener = new ClickedListener() {

@Override

public void onClick(Component arg0) {

if (selectDeviceId != null) {

// 用户点击后发起迁移流程

continueAbility(selectDeviceId);

}

};

本步骤执行后，跳转至11。

设置一个支持回迁FA的迁移功能按钮，以及拉回该FA的功能按钮。

// 设置支持回迁FA的迁移按钮

private Component.ClickedListener mContinueReversiblyListener = new Component.ClickedListener() {

@Override

public void onClick(Component arg0) {

if (selectDeviceId != null) {

// 用户选择设备后实现可拉回迁移

continueAbilityReversibly(selectDeviceId);

isReversibly = true;

}

};

// 设置拉回已迁移FA的按钮

private Component.ClickedListener mReverseContinueListener = new Component.ClickedListener() {

@Override

public void onClick(Component arg0) {

// 用户拉回迁移FA

if (isReversibly) {

reverseContinueAbility();

isReversibly = false;

}

};

FA的迁移还涉及到状态数据的传递，需要实现IAbilityContinuation接口，供开发者实现迁移过程中特定事件的管理能力，代码示例如下：

public class MainAbilitySlice extends AbilitySlice implements IAbilityContinuation {

private void showMessage(String msg) {

ToastDialog toastDialog = new ToastDialog(this);

toastDialog.setText(msg);

toastDialog.show();

}

@Override

public boolean onStartContinuation() {

showMessage(“ContinueAbility Start”);

return true;

}

@Override

public boolean onSaveData(IntentParams saveData) {

String exampleData = String.valueOf(System.currentTimeMillis());

saveData.setParam(“continueParam”, exampleData);

return true;

}

@Override

public boolean onRestoreData(IntentParams restoreData) {

// 远端FA迁移传来的状态数据，开发者可以按照特定的场景对这些数据进行处理

Object data = restoreData.getParam(“continueParam”);

return true;

}

@Override

public void onCompleteContinuation(int result) {

// 开发者可以根据业务需要，提示用户迁移完成，关闭本端FA

showMessage(“ContinueAbility Done”);

if (!isReversibly) {

terminateAbility();

}

@Override

public void onFailedContinuation(int errorCode) {

// 开发者可以根据业务需要，提示用户迁移失败

showMessage(“ContinueAbility failed”);

if (!isReversibly) {

terminateAbility();

}

通过自定义迁移事件相关的行为，最终实现对FA的迁移。此处主要以较为常用的两个事件，包括迁移发起端完成迁移的回调onCompleteContinuation(int result)，以及接收到远端迁移行为传递数据的回调onRestoreData(IntentParams restoreData)。其他还包括用于本端迁移发起时保存状态数据的回调onSaveData(IntentParams saveData)和本端发起迁移的回调onStartContinuation()。按照实际应用自定义特定场景对应的回调，可以完成多种场景下FA的迁移任务。