!17868 call事件文档补充

Merge pull request !17868 from wangkailong/callee

zh-cn/application-dev/application-models/Readme-CN.md

@@ -38,8 +38,9 @@
           - 开发卡片事件
             - [卡片事件能力说明](arkts-ui-widget-event-overview.md)
             - [通过FormExtensionAbility刷新卡片内容](arkts-ui-widget-event-formextensionability.md)
-            - [通过UIAbility刷新卡片内容](arkts-ui-widget-event-uiability.md)
             - [使用router事件跳转到指定页面](arkts-ui-widget-event-router.md)
+            - [使用call事件拉起指定UIAbility到后台](arkts-ui-widget-event-call.md)
+            - [通过UIAbility刷新卡片内容](arkts-ui-widget-event-uiability.md)
           - 卡片数据交互
             - [卡片数据交互说明](arkts-ui-widget-interaction-overview.md)
             - [定时刷新和定点刷新](arkts-ui-widget-update-by-time.md)

zh-cn/application-dev/application-models/arkts-ui-widget-event-call.md

+# 使用call事件拉起指定UIAbility到后台
+
+
+许多应用希望借助卡片的能力，实现和应用在前台时相同的功能。例如音乐卡片，卡片上提供播放、暂停等按钮，点击不同按钮将触发音乐应用的不同功能，进而提高用户的体验。在卡片中使用**postCardAction**接口的call能力，能够将卡片提供方应用拉到后台。同时，call能力提供了调用应用指定方法、传递数据的功能，使应用在后台运行时可以通过卡片上的按钮执行不同的功能。
+
+
+通常使用按钮控件来触发call事件，示例代码如下：
+
+
+- 在卡片页面中布局两个按钮，点击其中一个按钮时调用postCardAction向指定UIAbility发送call事件，并在事件内定义需要调用的方法和传递的数据。需要注意的是，method参数为必选参数，且类型需要为string类型，用于触发UIAbility中对应的方法。
+  
+  ```ts
+  @Entry
+  @Component
+  struct WidgetCard {
+    build() {
+      Column() {
+        Button('功能A')
+          .margin('20%')
+          .onClick(() => {
+            console.info('call EntryAbility funA');
+            postCardAction(this, {
+              'action': 'call',
+              'abilityName': 'EntryAbility', // 只能跳转到当前应用下的UIAbility
+              'params': {
+                'method': 'funA' // 在EntryAbility中调用的方法名
+              }
+            });
+          })
+  
+        Button('功能B')
+          .margin('20%')
+          .onClick(() => {
+            console.info('call EntryAbility funB');
+            postCardAction(this, {
+              'action': 'call',
+              'abilityName': 'EntryAbility', // 只能跳转到当前应用下的UIAbility
+              'params': {
+                'method': 'funB', // 在EntryAbility中调用的方法名
+                'num': 1 // 需要传递的其他参数
+              }
+            });
+          })
+      }
+      .width('100%')
+      .height('100%')
+    }
+  }
+  ```
+
+- 在UIAbility中接收call事件并获取参数，根据传递的method不同，执行不同的方法。其余数据可以通过readString的方式获取。需要注意的是，UIAbility需要onCreate生命周期中监听所需的方法。
+  
+  ```ts
+  import UIAbility from '@ohos.app.ability.UIAbility';
+
+  function FunACall(data) {
+    // 获取call事件中传递的所有参数
+    console.log('FunACall param:' + JSON.stringify(data.readString()));
+    return null;
+  }
+
+  function FunBCall(data) {
+    console.log('FunACall param:' + JSON.stringify(data.readString()));
+    return null;
+  }
+  
+  export default class CameraAbility extends UIAbility {
+    // 如果UIAbility第一次启动，在收到call事件后会触发onCreate生命周期回调
+    onCreate(want, launchParam) {
+        try {
+            // 监听call事件所需的方法
+            this.callee.on('funA', FunACall);
+            this.callee.on('funB', FunBCall);
+        } catch (error) {
+            console.log('register failed with error. Cause: ' + JSON.stringify(error));
+        }
+    }
+
+    // 进程退出时，解除监听
+    onDestroy() {
+        try {
+            this.callee.off('funA');
+            this.callee.off('funB');
+        } catch (error) {
+            console.log('register failed with error. Cause: ' + JSON.stringify(error));
+        }
+    }
+  };
+  ```

zh-cn/application-dev/application-models/arkts-ui-widget-event-overview.md

@@ -24,11 +24,11 @@ action参数说明：
 
 | **Key** | **Value** | **样例描述** |
 | -------- | -------- | -------- |
-| "action" | string | action的类型，支持三种预定义的类型：<br/>-&nbsp;"router"：应用跳转，触发后会跳转到对应UIAbility，仅允许跳转到当前应用的UIAbility。<br/>-&nbsp;"message"：自定义消息，触发后会调用提供方FormExtensionAbility的[onFormEvent()](../reference/apis/js-apis-app-form-formExtensionAbility.md#onformevent)生命周期回调。<br/>-&nbsp;"call"：应用非前台启动，触发后会启动对应的UIAbility，但不会调度到前台，call的目标应用需要具备后台运行权限([ohos.permission.KEEP_BACKGROUND_RUNNING](../security/permission-list.md#ohospermissionkeep_background_running))。 |
+| "action" | string | action的类型，支持三种预定义的类型：<br/>-&nbsp;"router"：应用跳转，触发后会跳转到对应UIAbility，仅允许跳转到当前应用的UIAbility。<br/>-&nbsp;"message"：自定义消息，触发后会调用提供方FormExtensionAbility的[onFormEvent()](../reference/apis/js-apis-app-form-formExtensionAbility.md#onformevent)生命周期回调。<br/>-&nbsp;"call"：应用非前台启动，触发后会启动当前应用的UIAbility，但不会调度到前台，call的目标应用需要具备后台运行权限([ohos.permission.KEEP_BACKGROUND_RUNNING](../security/permission-list.md#ohospermissionkeep_background_running))。 |
 | "bundleName" | string | "router"&nbsp;/&nbsp;"call"&nbsp;类型时跳转的包名，可选。 |
 | "moduleName" | string | "router"&nbsp;/&nbsp;"call"&nbsp;类型时跳转的模块名，可选。 |
 | "abilityName" | string | "router"&nbsp;/&nbsp;"call"&nbsp;类型时跳转的UIAbility名，必填。 |
-| "params" | Object | 当前action携带的额外参数，内容使用JSON格式的键值对形式。 |
+| "params" | Object | 当前action携带的额外参数，内容使用JSON格式的键值对形式。"call"&nbsp;类型时需填入参数'method'，且类型需要为string类型，用于触发UIAbility中对应的方法，必填。 |
 
 
 postCardAction()接口示例代码：
@@ -50,6 +50,22 @@ Button('跳转')
     });
   })
 ```
+```typescript
+Button('拉至后台')
+  .width('40%')
+  .height('20%')
+  .onClick(() => {
+    postCardAction(this, {
+      'action': 'call',
+      'bundleName': 'com.example.myapplication',
+      'abilityName': 'EntryAbility',
+      'params': {
+        'method': 'fun', // 自定义调用的方法名，必填
+        'message': 'testForcall' // 自定义要发送的message
+      }
+    });
+  })
+```
 
 
 以下是卡片开发过程中可以通过卡片事件实现的典型开发场景：
@@ -60,3 +76,5 @@ Button('跳转')
 - [通过UIAbility刷新卡片内容](arkts-ui-widget-event-uiability.md)
 
 - [使用router事件跳转到指定页面](arkts-ui-widget-event-router.md)
+
+- [使用call事件拉起指定UIAbility到后台](arkts-ui-widget-event-call.md)

zh-cn/application-dev/application-models/arkts-ui-widget-event-uiability.md

@@ -3,8 +3,9 @@
 
 在卡片页面中可以通过**postCardAction**接口触发router事件或者call事件拉起UIAbility，然后由UIAbility刷新卡片内容，下面是这种刷新方式的简单示例。
 
+## 通过postCardAction接口触发router事件
 
-- 在卡片页面通过注册Button的onClick点击事件回调，并在回调中调用**postCardAction**接口触发事件至FormExtensionAbility。
+- 在卡片页面通过注册Button的onClick点击事件回调，并在回调中调用**postCardAction**接口触发router事件至FormExtensionAbility。
   
   ```ts
   let storage = new LocalStorage();
@@ -84,3 +85,104 @@
     ...
   }
   ```
+
+## 通过postCardAction接口触发call事件
+
+- 在使用**postCardAction**接口的call事件时，需要在FormExtensionAbility中的onAddForm生命周期回调中更新formId。
+   
+   ```ts
+   import formBindingData from '@ohos.app.form.formBindingData';
+   import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility';
+   
+   export default class EntryFormAbility extends FormExtensionAbility {
+     onAddForm(want) {
+      let formId = want.parameters["ohos.extra.param.key.form_identity"];
+      let dataObj1 = {
+        "formId": formId
+      };
+      let obj1 = formBindingData.createFormBindingData(dataObj1);
+      return obj1;
+    }
+    
+     ...
+   };
+   ```
+
+- 在卡片页面通过注册Button的onClick点击事件回调，并在回调中调用**postCardAction**接口触发call事件至UIAbility。
+  
+  ```ts
+  let storage = new LocalStorage();
+  @Entry(storage)
+  @Component
+  struct WidgetCard {
+    @LocalStorageProp('detail') detail: string = 'init';
+    @LocalStorageProp('formId') formId: string = '0';
+
+    build() {
+      Column() {
+        Button('拉至后台')
+          .margin('20%')
+          .onClick(() => {
+            console.info('postCardAction to EntryAbility');
+            postCardAction(this, {
+              'action': 'call',
+              'abilityName': 'EntryAbility', // 只能拉起当前应用下的UIAbility
+              'params': {
+                'method': 'funA',
+                'formId': this.formId,
+                'detail': 'CallFromCard'
+              }
+            });
+          })
+        Text(`${this.detail}`).margin('20%')
+      }
+      .width('100%')
+      .height('100%')
+    }
+  }
+  ```
+  
+- 在UIAbility的onCreate生命周期中监听call事件所需的方法，然后在对应方法中调用[updateForm](../reference/apis/js-apis-app-form-formProvider.md#updateform)接口刷新卡片。
+  
+  ```ts
+  import UIAbility from '@ohos.app.ability.UIAbility';
+  import formBindingData from '@ohos.app.form.formBindingData';
+  import formProvider from '@ohos.app.form.formProvider';
+  import formInfo from '@ohos.app.form.formInfo';
+  
+  const MSG_SEND_METHOD: string = 'funA'
+
+  // 在收到call事件后会触发callee监听的方法
+  function FunACall(data) {
+    // 获取call事件中传递的所有参数
+    let params = JSON.parse(data.readString())
+    if (params.formId !== undefined) {
+      let curFormId = params.formId;
+      let message = params.detail;
+      console.info(`UpdateForm formId: ${curFormId}, message: ${message}`);
+      let formData = {
+        "detail": message
+      };
+      let formMsg = formBindingData.createFormBindingData(formData)
+      formProvider.updateForm(curFormId, formMsg).then((data) => {
+        console.info('updateForm success.' + JSON.stringify(data));
+      }).catch((error) => {
+        console.error('updateForm failed:' + JSON.stringify(error));
+      })
+    }
+    return null;
+  }
+  export default class EntryAbility extends UIAbility {
+    // 如果UIAbility第一次启动，call事件后会触发onCreate生命周期回调
+    onCreate(want, launchParam) {
+      console.info('Want:' + JSON.stringify(want));
+      try {
+         // 监听call事件所需的方法
+        this.callee.on(MSG_SEND_METHOD, FunACall);
+      } catch (error) {
+        console.log(`${MSG_SEND_METHOD} register failed with error ${JSON.stringify(error)}`)
+      }
+    }
+    ...
+  }
+  ```
\ No newline at end of file