卡片事件能力说明
ArkTS卡片中提供了postCardAction()接口用于卡片内部和提供方应用间的交互，当前支持router、message和call三种类型的事件，仅在卡片中可以调用。
接口定义：postCardAction(component: Object, action: Object): void
接口参数说明：
| 参数名 | 参数类型 | 必填 | 参数描述 |
|---|---|---|---|
| component | Object | 是 | 当前自定义组件的实例，通常传入this。 |
| action | Object | 是 | action的具体描述，详情见下表。 |
action参数说明：
| Key | Value | 样例描述 |
|---|---|---|
| “action” | string | action的类型，支持三种预定义的类型：“router”：跳转到提供方应用的指定UIAbility。“message”：自定义消息。触发后会调用提供方FormExtensionAbility的onFormEvent()生命周期回调。“call”：后台启动提供方应用。触发后会拉起提供方应用的指定UIAbility（仅支持launchType为singleton的UIAbility，即启动模式为单实例的UIAbility），但不会调度到前台。提供方应用需要具备后台运行权限（ohos.permission.KEEP_BACKGROUND_RUNNING）。 |
| “bundleName” | string | “router” / “call” 类型时跳转的包名，可选。 |
| “moduleName” | string | “router” / “call” 类型时跳转的模块名，可选。 |
| “abilityName” | string | “router” / “call” 类型时跳转的UIAbility名，必填。 |
| “params” | Object | 当前action携带的额外参数，内容使用JSON格式的键值对形式。"call"类型时需填入参数’method’，且类型需要为string类型，用于触发UIAbility中对应的方法，必填。 |
postCardAction()接口示例代码：
Button('跳转')
.width('40%')
.height('20%')
.onClick(() => {
postCardAction(this, {
'action': 'router',
'bundleName': 'com.example.myapplication',
'abilityName': 'EntryAbility',
'params': {
'message': 'testForRouter' // 自定义要发送的message
}
});
})
Button('拉至后台')
.width('40%')
.height('20%')
.onClick(() => {
postCardAction(this, {
'action': 'call',
'bundleName': 'com.example.myapplication',
'abilityName': 'EntryAbility',
'params': {
'method': 'fun', // 自定义调用的方法名，必填
'message': 'testForCall' // 自定义要发送的message
}
});
})
使用router事件跳转到指定UIAbility
在卡片中使用postCardAction接口的router能力，能够快速拉起卡片提供方应用的指定UIAbility，因此UIAbility较多的应用往往会通过卡片提供不同的跳转按钮，实现一键直达的效果。例如相机卡片，卡片上提供拍照、录像等按钮，点击不同按钮将拉起相机应用的不同UIAbility，从而提升用户的体验。
通常使用按钮控件来实现页面拉起，示例代码如下：
-
在卡片页面中布局两个按钮，点击其中一个按钮时调用postCardAction向指定UIAbility发送router事件，并在事件内定义需要传递的内容。
@Entry @Component struct WidgetCard { build() { Column() { Button('功能A') .margin('20%') .onClick(() => { console.info('Jump to EntryAbility funA'); postCardAction(this, { 'action': 'router', 'abilityName': 'EntryAbility', // 只能跳转到当前应用下的UIAbility 'params': { 'targetPage': 'funA' // 在EntryAbility中处理这个信息 } }); }) Button('功能B') .margin('20%') .onClick(() => { console.info('Jump to EntryAbility funB'); postCardAction(this, { 'action': 'router', 'abilityName': 'EntryAbility', // 只能跳转到当前应用下的UIAbility 'params': { 'targetPage': 'funB' // 在EntryAbility中处理这个信息 } }); }) } .width('100%') .height('100%') } } -
在UIAbility中接收router事件并获取参数，根据传递的params不同，选择拉起不同的页面。
import UIAbility from '@ohos.app.ability.UIAbility'; import window from '@ohos.window'; let selectPage = ""; let currentWindowStage = null; export default class CameraAbility extends UIAbility { // 如果UIAbility第一次启动，在收到Router事件后会触发onCreate生命周期回调 onCreate(want, launchParam) { // 获取router事件中传递的targetPage参数 console.info("onCreate want:" + JSON.stringify(want)); if (want.parameters.params !== undefined) { let params = JSON.parse(want.parameters.params); console.info("onCreate router targetPage:" + params.targetPage); selectPage = params.targetPage; } } // 如果UIAbility已在后台运行，在收到Router事件后会触发onNewWant生命周期回调 onNewWant(want, launchParam) { console.info("onNewWant want:" + JSON.stringify(want)); if (want.parameters.params !== undefined) { let params = JSON.parse(want.parameters.params); console.info("onNewWant router targetPage:" + params.targetPage); selectPage = params.targetPage; } if (currentWindowStage != null) { this.onWindowStageCreate(currentWindowStage); } } onWindowStageCreate(windowStage: window.WindowStage) { let targetPage; // 根据传递的targetPage不同，选择拉起不同的页面 switch (selectPage) { case 'funA': targetPage = 'pages/FunA'; break; case 'funB': targetPage = 'pages/FunB'; break; default: targetPage = 'pages/Index'; } if (currentWindowStage === null) { currentWindowStage = windowStage; } windowStage.loadContent(targetPage, (err, data) => { if (err && err.code) { console.info('Failed to load the content. Cause: %{public}s', JSON.stringify(err)); return; } }); } };
使用call事件拉起指定UIAbility到后台
许多应用希望借助卡片的能力，实现和应用在前台时相同的功能。例如音乐卡片，卡片上提供播放、暂停等按钮，点击不同按钮将触发音乐应用的不同功能，进而提高用户的体验。在卡片中使用postCardAction接口的call能力，能够将卡片提供方应用的指定UIAbility拉到后台。同时，call能力提供了调用应用指定方法、传递数据的功能，使应用在后台运行时可以通过卡片上的按钮执行不同的功能。
通常使用按钮控件来触发call事件，示例代码如下：
-
在卡片页面中布局两个按钮，点击其中一个按钮时调用postCardAction向指定UIAbility发送call事件，并在事件内定义需要调用的方法和传递的数据。需要注意的是，method参数为必选参数，且类型需要为string类型，用于触发UIAbility中对应的方法。
@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生命周期中监听所需的方法。
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)); } } };
