From 6ce5737f7c8b5baeff241a2549cdfb1ab8c07a22 Mon Sep 17 00:00:00 2001 From: hobbycao Date: Fri, 30 Jun 2023 16:07:29 +0800 Subject: [PATCH] feat: add dms interface desc Signed-off-by: hobbycao --- .../hop-cross-device-migration.md | 66 ++++++++++++++++ .../inter-device-interaction-hop-overview.md | 4 +- .../js-apis-app-ability-abilityConstant.md | 21 +++++ .../apis/js-apis-app-ability-wantConstant.md | 2 + ...apis-inner-application-uiAbilityContext.md | 76 +++++++++++++++++++ 5 files changed, 167 insertions(+), 2 deletions(-) diff --git a/zh-cn/application-dev/application-models/hop-cross-device-migration.md b/zh-cn/application-dev/application-models/hop-cross-device-migration.md index 15ae649e92..19ae439ffc 100644 --- a/zh-cn/application-dev/application-models/hop-cross-device-migration.md +++ b/zh-cn/application-dev/application-models/hop-cross-device-migration.md @@ -11,6 +11,12 @@ - 支持应用兼容性检测。 +- 支持应用根据实际使用场景动态设置迁移状态（默认迁移状态为ACTIVE激活状态）。如编辑类应用在编辑文本的页面下才需要迁移，其他页面不需要迁移，则可以通过[setMissionContinueState](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextsetmissioncontinuestate10)进行控制。 + +- 支持应用动态选择是否进行页面栈恢复（默认进行页面栈信息恢复）。如应用希望自定义迁移到其他设备后显示的页面，则可以通过[SUPPORT_CONTINUE_PAGE_STACK_KEY](../reference/apis/js-apis-app-ability-wantConstant.md#wantconstantparams)进行控制。 + +- 支持应用动态选择流转成功后是否退出迁移发起端应用（默认流转成功后退出迁移发起端应用）。则可以通过[SUPPORT_CONTINUE_SOURCE_EXIT_KEY](../reference/apis/js-apis-app-ability-wantConstant.md#wantconstantparams)进行控制。 + ## 跨端迁移流程 @@ -125,3 +131,63 @@ } ``` - 如果是单实例应用，则采用同样的代码实现onNewWant()接口即可。 + +6. **可选配置：** 在应用支持迁移特性时，默认开启应用迁移状态开关，根据应用当前任务获取焦点/失去焦点通知周边的可信设备当前任务可流转/取消流转。若应用需要在特定场景下才通知周边设备可流转，则需要在应用打开时设置迁移状态为INACTIVE，在后续的业务流程中需要迁移时再设置迁移状态为ACTIVE。接口见[setMissionContinueState](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextsetmissioncontinuestate10)。 + + - 示例：应用启动不需要流转 + + ```ts + import UIAbility from '@ohos.app.ability.UIAbility'; + import AbilityConstant from '@ohos.app.ability.AbilityConstant'; + + onCreate(want, launchParam) { + this.context.setMissionContinueState(AbilityConstant.ContinueState.INACTIVE, (result) => { + console.info(`setMissionContinueState: ${JSON.stringify(result)}`); + }); + } + ``` + - 示例：应用在后续的业务流程中需要流转了 + + ```ts + import UIAbility from '@ohos.app.ability.UIAbility'; + import AbilityConstant from '@ohos.app.ability.AbilityConstant'; + + this.context.setMissionContinueState(AbilityConstant.ContinueState.ACTIVE, (result) => { + console.info(`setMissionContinueState: ${JSON.stringify(result)}`); + }); + ``` + +7. **可选配置：** 支持应用动态选择是否进行页面栈恢复（默认进行页面栈信息恢复）。如果应用不想使用系统默认恢复的页面栈，则可以设置不进行页面栈迁移，而需要在`onWindowStageRestore`设置流转后进入的页面，参数定义见[SUPPORT_CONTINUE_PAGE_STACK_KEY](../reference/apis/js-apis-app-ability-wantConstant.md#wantconstantparams)。 + + - 示例：应用迁移不需要自动流转页面栈信息 + + ```ts + import UIAbility from '@ohos.app.ability.UIAbility'; + import wantConstant from '@ohos.app.ability.wantConstant.d.ts'; + + onContinue(wantParam : {[key: string]: any}) { + console.info(`onContinue version = ${wantParam.version}, targetDevice: ${wantParam.targetDevice}`) + wantParam[wantConstant.SUPPORT_CONTINUE_PAGE_STACK_KEY] = false; + return AbilityConstant.OnContinueResult.AGREE; + } + + onWindowStageRestore(windowStage) { + // 若不需要自动流转页面栈信息，则需要在此处设置应用流转后进入的页面 + windowStage.setUIContent(this.contex, "pages/index", null); + } + ``` + +8. **可选配置：** 支持应用动态选择迁移成功后是否退出迁移发起端应用（默认流转成功后退出迁移发起端应用）。如果应用不想让系统自动退出迁移发起端应用，则可以设置不退出，参数定义见参数定义见[SUPPORT_CONTINUE_SOURCE_EXIT_KEY](../reference/apis/js-apis-app-ability-wantConstant.md#wantconstantparams)。 + + - 示例：应用迁移设置不需要迁移成功后退出迁移发起端应用 + + ```ts + import UIAbility from '@ohos.app.ability.UIAbility'; + import wantConstant from '@ohos.app.ability.wantConstant.d.ts'; + + onContinue(wantParam : {[key: string]: any}) { + console.info(`onContinue version = ${wantParam.version}, targetDevice: ${wantParam.targetDevice}`) + wantParam[wantConstant.SUPPORT_CONTINUE_SOURCE_EXIT_KEY] = false; + return AbilityConstant.OnContinueResult.AGREE; + } + ``` \ No newline at end of file diff --git a/zh-cn/application-dev/application-models/inter-device-interaction-hop-overview.md b/zh-cn/application-dev/application-models/inter-device-interaction-hop-overview.md index 5ae4d34ac7..94f2d55e2a 100644 --- a/zh-cn/application-dev/application-models/inter-device-interaction-hop-overview.md +++ b/zh-cn/application-dev/application-models/inter-device-interaction-hop-overview.md @@ -16,11 +16,11 @@ - **跨端迁移** - 在用户使用设备的过程中，当使用情境发生变化时（例如从室内走到户外或者周围有更合适的设备等），之前使用的设备可能已经不适合继续当前的任务，此时，用户可以选择新的设备来继续当前的任务，原设备退出任务，这就是跨端迁移场景。常见的跨端迁移场景实例：在平板上播放的视频，迁移到智慧屏继续播放，从而获得更佳的观看体验；平板上的视频应用退出。在应用开发层面，跨端迁移指在A端运行的UIAbility迁移到B端上，完成迁移后， B端UIAbility继续任务，而A端UIAbility退出。 + 在用户使用设备的过程中，当使用情境发生变化时（例如从室内走到户外或者周围有更合适的设备等），之前使用的设备可能已经不适合继续当前的任务，此时，用户可以选择新的设备来继续当前的任务，原设备可按需决定是否退出任务，这就是跨端迁移场景。常见的跨端迁移场景实例：在平板上播放的视频，迁移到智慧屏继续播放，从而获得更佳的观看体验；平板上的视频应用退出。在应用开发层面，跨端迁移指在A端运行的UIAbility迁移到B端上，完成迁移后， B端UIAbility继续任务，而A端UIAbility可按需决定是否退出。 - **多端协同** - 用户拥有的多个设备，可以作为一个整体，为用户提供比单设备更加高效、沉浸的体验，这就是多端协同场景。常见的多端协同场景实例：平板侧应用A做答题板，智慧屏侧应用B做直播，为用户提供更优的上网课体验。在应用开发层面，多端协同指多端上的不同UIAbility/ServiceExtensionAbility同时运行、或者交替运行实现完整的业务；或者多端上的相同UIAbility/ServiceExtensionAbility同时运行实现完整的业务。 + 用户拥有的多个设备，可以作为一个整体，为用户提供比单设备更加高效、沉浸的体验，这就是多端协同场景。常见的多端协同场景实例：场景一：两台设备A和B打开备忘录同一篇笔记进行双端协同编辑，在设备A上可以使用本地图库中的图片资源插入编辑，设备B上进行文字内容编辑。场景二：设备A上正在和客户进行聊天，客户需要的资料在设备B上，可以通过聊天软件打开设备B上的文档应用选择到想要的资料回传到设备A上，然后通过聊天软件发送给客户。在应用开发层面，多端协同指多端上的不同UIAbility/ServiceExtensionAbility同时运行、或者交替运行实现完整的业务；或者多端上的相同UIAbility/ServiceExtensionAbility同时运行实现完整的业务。 ## 流转架构 diff --git a/zh-cn/application-dev/reference/apis/js-apis-app-ability-abilityConstant.md b/zh-cn/application-dev/reference/apis/js-apis-app-ability-abilityConstant.md index 664c7ba801..b112c2db13 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-app-ability-abilityConstant.md +++ b/zh-cn/application-dev/reference/apis/js-apis-app-ability-abilityConstant.md @@ -223,4 +223,25 @@ class MyAbility extends UIAbility { return AbilityConstant.OnSaveResult.ALL_AGREE; } } +``` + +## AbilityConstant.ContinueState10+ + +ContinueState说明枚举值。用于表示当前应用任务流转的状态。可配合[UIAbilityContext](js-apis-inner-application-uiAbilityContext.md)的[setMissionContinueState](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextsetmissioncontinuestate10)方法进行设置。 + +**系统能力**：SystemCapability.Ability.AbilityRuntime.Core + +| 名称 | 值 | 说明 | +| ------------- | --------- | ------------------------------------------------------------ | +| ACTIVE | 0 | 指示当前应用任务流转处于激活状态。 | +| INACTIVE | 1 | 指示当前应用任务流转处于未激活状态。 | + +**示例：** + +```ts + import AbilityConstant from '@ohos.app.ability.AbilityConstant'; + + this.context.setMissionContinueState(AbilityConstant.ContinueState.INACTIVE, (result) => { + console.info(`setMissionContinueState: ${JSON.stringify(result)}`); + }); ``` \ No newline at end of file diff --git a/zh-cn/application-dev/reference/apis/js-apis-app-ability-wantConstant.md b/zh-cn/application-dev/reference/apis/js-apis-app-ability-wantConstant.md index a1ce62ff8a..1533356acf 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-app-ability-wantConstant.md +++ b/zh-cn/application-dev/reference/apis/js-apis-app-ability-wantConstant.md @@ -30,6 +30,8 @@ want的Params操作的常量。 | CONTENT_TITLE_KEY10+ | ohos.extra.param.key.contentTitle | 指示原子化服务支持分享标题的参数的操作。 | | SHARE_ABSTRACT_KEY10+ | ohos.extra.param.key.shareAbstract | 指示原子化服务支持分享内容的参数的操作。 | | SHARE_URL_KEY10+ | ohos.extra.param.key.shareUrl | 指示原子化服务支持分享链接的参数的操作。 | +| SUPPORT_CONTINUE_PAGE_STACK_KEY10+ | ohos.extra.param.key.supportContinuePageStack | 指示在跨端迁移过程中是否迁移页面栈信息，默认值为true，自动迁移页面栈信息。| +| SUPPORT_CONTINUE_SOURCE_EXIT_KEY10+ | ohos.extra.param.key.supportContinueSourceExit | 指示跨端迁移源端应用是否退出，默认值为true，源端应用自动退出。| ## wantConstant.Flags diff --git a/zh-cn/application-dev/reference/apis/js-apis-inner-application-uiAbilityContext.md b/zh-cn/application-dev/reference/apis/js-apis-inner-application-uiAbilityContext.md index 8187a8401a..07b146d51b 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-inner-application-uiAbilityContext.md +++ b/zh-cn/application-dev/reference/apis/js-apis-inner-application-uiAbilityContext.md @@ -2117,6 +2117,82 @@ setMissionIcon(icon: image.PixelMap): Promise\; console.error(`setMissionLabel failed, code is ${err.code}, message is ${err.message}`); }); ``` + +## UIAbilityContext.setMissionContinueState10+ + +setMissionContinueState(state: AbilityConstant.ContinueState, callback:AsyncCallback<void>): void; + +设置UIAbility任务中流转状态（callback形式）。 + +**系统能力**：SystemCapability.Ability.AbilityRuntime.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| state | [ContinueState](js-apis-app-ability-abilityConstant.md#abilityconstantcontinuestate10) | 是 | 流转状态。 | +| callback | AsyncCallback<void> | 是 | 回调函数，返回接口调用是否成功的结果。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | -------------------------------- | +| 16000011 | The context does not exist. | +| 16000050 | Internal error. | + +错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md) + +**示例：** + + ```ts + import AbilityConstant from '@ohos.app.ability.AbilityConstant'; + + this.context.setMissionContinueState(AbilityConstant.ContinueState.INACTIVE, (result) => { + console.info(`setMissionContinueState: ${JSON.stringify(result)}`); + }); + ``` + +## UIAbilityContext.setMissionContinueState10+ + +setMissionContinueState(state: AbilityConstant.ContinueState): Promise<void>; + +设置UIAbility任务中流转状态（promise形式）。 + +**系统能力**：SystemCapability.Ability.AbilityRuntime.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| state | [ContinueState](js-apis-app-ability-abilityConstant.md#abilityconstantcontinuestate10) | 是 | 流转状态。 | + +**返回值：** + +| 类型 | 说明 | +| -------- | -------- | +| Promise<void> | 返回一个Promise，包含接口的结果。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | -------------------------------- | +| 16000011 | The context does not exist. | +| 16000050 | Internal error. | + +错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md) + +**示例：** + + ```ts + import AbilityConstant from '@ohos.app.ability.AbilityConstant'; + + this.context.setMissionContinueState(AbilityConstant.ContinueState.INACTIVE).then(() => { + console.info('success'); + }).catch((err) => { + console.error(`setMissionContinueState failed, code is ${err.code}, message is ${err.message}`); + }); + ``` + ## UIAbilityContext.restoreWindowStage restoreWindowStage(localStorage: LocalStorage) : void; -- GitLab