!16836 新增协同场景下组件跨设备组件状态感知的接口文档说明

Merge pull request !16836 from 杜智海/master

zh-cn/application-dev/application-models/hop-multi-device-collaboration.md

@@ -397,7 +397,7 @@
        import Ability from '@ohos.app.ability.UIAbility';
        ```
    2. 获取Caller通信接口。
-       Ability的context属性实现了startAbilityByCall方法，用于获取指定通用组件的Caller通信接口。如下示例通过this.context获取Ability实例的context属性，使用startAbilityByCall拉起Callee被调用端并获取Caller通信接口，注册Caller的onRelease监听。应用开发者根据实际业务需要做相应处理。
+       Ability的context属性实现了startAbilityByCall方法，用于获取指定通用组件的Caller通信接口。如下示例通过this.context获取Ability实例的context属性，使用startAbilityByCall拉起Callee被调用端并获取Caller通信接口，注册Caller的onRelease和onRemoteStateChange监听。应用开发者根据实际业务需要做相应处理。
 
        
        ```ts
@@ -418,6 +418,14 @@
                        console.info(`remote caller onRelease is called ${msg}`);
                    })
                    console.info('remote caller register OnRelease succeed');
+                   // 注册caller的协同场景下跨设备组件状态变化监听通知
+                   try {
+                        caller.onRemoteStateChange((str) => {
+                            console.log('Remote state changed ' + str);
+                        });
+                    } catch (error) {
+                        console.log('Caller.onRemoteStateChange catch error, error.code: ${JSON.stringify(error.code)}, error.message: ${JSON.stringify(error.message)}');
+                    }
                }
            }).catch((error) => {
                console.error(`get remote caller failed with ${error}`);

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

@@ -574,6 +574,49 @@ release(): void;
   }
   ```
 
+  ## Caller.onRemoteStateChange
+
+ onRemoteStateChange(callback: OnRemoteStateChangeCallback): void;
+
+注册协同场景下跨设备组件状态变化监听通知。
+
+**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore
+
+**参数：**
+
+| 参数名 | 类型 | 必填 | 说明 |
+| -------- | -------- | -------- | -------- |
+| callback | [OnRemoteStateChangeCallback](#onremotestatechangecallback) | 是 | 返回onRemoteStateChange回调结果。 |
+
+**示例：**
+    
+  ```ts
+  import UIAbility from '@ohos.app.ability.UIAbility';
+
+  let caller;
+  let dstDeviceId: string;
+  export default class MainAbility extends UIAbility {
+      onWindowStageCreate(windowStage: Window.WindowStage) {
+          this.context.startAbilityByCall({
+              bundleName: 'com.example.myservice',
+              abilityName: 'MainUIAbility',
+              deviceId: dstDeviceId
+          }).then((obj) => {
+              caller = obj;
+              try {
+                  caller.onRemoteStateChange((str) => {
+                      console.log('Remote state changed ' + str);
+                  });
+              } catch (error) {
+                  console.log('Caller.onRemoteStateChange catch error, error.code: ${JSON.stringify(error.code)}, error.message: ${JSON.stringify(error.message)}');
+              }
+          }).catch((err) => {
+              console.log('Caller GetCaller error, error.code: ${JSON.stringify(err.code)}, error.message: ${JSON.stringify(err.message)}');
+          })；
+      }
+  }
+  ```
+
 ## Caller.on
 
  on(type: 'release', callback: OnReleaseCallback): void;
@@ -841,6 +884,16 @@ off(method: string): void;
 | -------- | -------- | -------- | -------- | -------- |
 | (msg: string) | 是 | 否 | function | 调用者注册的侦听器函数接口的原型。 |
 
+## OnRemoteStateChangeCallback
+
+(msg: string): void;
+
+**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore
+
+| 名称 | 可读 | 可写 | 类型 | 说明 |
+| -------- | -------- | -------- | -------- | -------- |
+| (msg: string) | 是 | 否 | function | 调用者注册的协同场景下组件状态变化监听函数接口的原型。 |
+
 ## CalleeCallback
 
 (indata: rpc.MessageSequence): rpc.Parcelable;