diff --git a/zh-cn/application-dev/application-models/Readme-CN.md b/zh-cn/application-dev/application-models/Readme-CN.md
index 12ad483618be5512ca2c3f1c75cedd5602f07866..3436b002f631f0c83667b34ded70c0e347e7d421 100644
--- a/zh-cn/application-dev/application-models/Readme-CN.md
+++ b/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)
diff --git a/zh-cn/application-dev/application-models/arkts-ui-widget-event-call.md b/zh-cn/application-dev/application-models/arkts-ui-widget-event-call.md
new file mode 100644
index 0000000000000000000000000000000000000000..f011aa6547fa69f88f9e779eb621f1caf8915c8c
--- /dev/null
+++ b/zh-cn/application-dev/application-models/arkts-ui-widget-event-call.md
@@ -0,0 +1,89 @@
+# 使用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));
+ }
+ }
+ };
+ ```
diff --git a/zh-cn/application-dev/application-models/arkts-ui-widget-event-overview.md b/zh-cn/application-dev/application-models/arkts-ui-widget-event-overview.md
index 783dc774f4db8dc76a20935f9772a00e6c8fb4a5..98867645bcd25a31126b0bc43909c9aad4b7a9c0 100644
--- a/zh-cn/application-dev/application-models/arkts-ui-widget-event-overview.md
+++ b/zh-cn/application-dev/application-models/arkts-ui-widget-event-overview.md
@@ -24,11 +24,11 @@ action参数说明:
| **Key** | **Value** | **样例描述** |
| -------- | -------- | -------- |
-| "action" | string | action的类型,支持三种预定义的类型:
- "router":应用跳转,触发后会跳转到对应UIAbility,仅允许跳转到当前应用的UIAbility。
- "message":自定义消息,触发后会调用提供方FormExtensionAbility的[onFormEvent()](../reference/apis/js-apis-app-form-formExtensionAbility.md#onformevent)生命周期回调。
- "call":应用非前台启动,触发后会启动对应的UIAbility,但不会调度到前台,call的目标应用需要具备后台运行权限([ohos.permission.KEEP_BACKGROUND_RUNNING](../security/permission-list.md#ohospermissionkeep_background_running))。 |
+| "action" | string | action的类型,支持三种预定义的类型:
- "router":应用跳转,触发后会跳转到对应UIAbility,仅允许跳转到当前应用的UIAbility。
- "message":自定义消息,触发后会调用提供方FormExtensionAbility的[onFormEvent()](../reference/apis/js-apis-app-form-formExtensionAbility.md#onformevent)生命周期回调。
- "call":应用非前台启动,触发后会启动当前应用的UIAbility,但不会调度到前台,call的目标应用需要具备后台运行权限([ohos.permission.KEEP_BACKGROUND_RUNNING](../security/permission-list.md#ohospermissionkeep_background_running))。 |
| "bundleName" | string | "router" / "call" 类型时跳转的包名,可选。 |
| "moduleName" | string | "router" / "call" 类型时跳转的模块名,可选。 |
| "abilityName" | string | "router" / "call" 类型时跳转的UIAbility名,必填。 |
-| "params" | Object | 当前action携带的额外参数,内容使用JSON格式的键值对形式。 |
+| "params" | Object | 当前action携带的额外参数,内容使用JSON格式的键值对形式。"call" 类型时需填入参数'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)
diff --git a/zh-cn/application-dev/application-models/arkts-ui-widget-event-uiability.md b/zh-cn/application-dev/application-models/arkts-ui-widget-event-uiability.md
index 141d66506508cd60d12b76c8d98da70e918612d6..fb42de0b4bf5409daad0ea58b22c4da9dce1929c 100644
--- a/zh-cn/application-dev/application-models/arkts-ui-widget-event-uiability.md
+++ b/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
diff --git a/zh-cn/application-dev/application-models/figures/WidgetPostCardAction.png b/zh-cn/application-dev/application-models/figures/WidgetPostCardAction.png
index f7c886204213b5250dbe49d54b9904cf33436ce8..04589e3228f4c7da9c7861fcceb2d110518295ff 100644
Binary files a/zh-cn/application-dev/application-models/figures/WidgetPostCardAction.png and b/zh-cn/application-dev/application-models/figures/WidgetPostCardAction.png differ