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