!20325 feat: add dms interface doc

Merge pull request !20325 from hobbycao/master

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

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同时运行实现完整的业务。
 
 
 ## 流转架构

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.ContinueState<sup>10+</sup>
+
+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

zh-cn/application-dev/reference/apis/js-apis-app-ability-wantConstant.md

@@ -30,6 +30,8 @@ want的Params操作的常量。
 | CONTENT_TITLE_KEY<sup>10+</sup>       | ohos.extra.param.key.contentTitle  | 指示原子化服务支持分享标题的参数的操作。  |
 | SHARE_ABSTRACT_KEY<sup>10+</sup>      | ohos.extra.param.key.shareAbstract | 指示原子化服务支持分享内容的参数的操作。  |
 | SHARE_URL_KEY<sup>10+</sup>           | ohos.extra.param.key.shareUrl      | 指示原子化服务支持分享链接的参数的操作。  |
+| SUPPORT_CONTINUE_PAGE_STACK_KEY<sup>10+</sup>    | ohos.extra.param.key.supportContinuePageStack  | 指示在跨端迁移过程中是否迁移页面栈信息，默认值为true，自动迁移页面栈信息。|
+| SUPPORT_CONTINUE_SOURCE_EXIT_KEY<sup>10+</sup>  | ohos.extra.param.key.supportContinueSourceExit      | 指示跨端迁移源端应用是否退出，默认值为true，源端应用自动退出。|
 
 
 ## wantConstant.Flags

zh-cn/application-dev/reference/apis/js-apis-inner-application-uiAbilityContext.md

@@ -2213,6 +2213,82 @@ setMissionIcon(icon: image.PixelMap): Promise\<void>;
       console.error(`setMissionLabel failed, code is ${err.code}, message is ${err.message}`);
     });
   ```
+
+## UIAbilityContext.setMissionContinueState<sup>10+</sup>
+
+setMissionContinueState(state: AbilityConstant.ContinueState, callback:AsyncCallback&lt;void&gt;): void;
+
+设置UIAbility任务中流转状态（callback形式）。
+
+**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
+
+**参数：**
+
+| 参数名 | 类型 | 必填 | 说明 |
+| -------- | -------- | -------- | -------- |
+| state | [ContinueState](js-apis-app-ability-abilityConstant.md#abilityconstantcontinuestate10) | 是 | 流转状态。 |
+| callback | AsyncCallback&lt;void&gt; | 是 | 回调函数，返回接口调用是否成功的结果。 |
+
+**错误码：**
+
+| 错误码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.setMissionContinueState<sup>10+</sup>
+
+setMissionContinueState(state: AbilityConstant.ContinueState): Promise&lt;void&gt;;
+
+设置UIAbility任务中流转状态（promise形式）。
+
+**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
+
+**参数：**
+
+| 参数名 | 类型 | 必填 | 说明 |
+| -------- | -------- | -------- | -------- |
+| state | [ContinueState](js-apis-app-ability-abilityConstant.md#abilityconstantcontinuestate10) | 是 | 流转状态。 |
+
+**返回值：**
+
+| 类型 | 说明 |
+| -------- | -------- |
+| Promise&lt;void&gt; | 返回一个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;