当前位置：首页 > news >正文

卡片跳转到应用页面（router事件）

news 2025/7/1 10:23:31

卡片跳转到应用页面（router事件）

ArkTS卡片提供页面交互能力，包括卡片与卡片提供方（例如：应用）的页面跳转、卡片拉起卡片提供方进程、卡片与卡片提供方的消息传递。其中动态卡片可以使用postCardAction接口、静态卡片使用FormLink实现页面交互功能。并且postCardAction和FormLink，均支持router、message和call三种类型的事件，具体使用场景如下：

router事件：可以使用router事件跳转到指定UIAbility，以完成点击卡片跳转至应用内页面的功能。对于非系统应用仅支持跳转到自己应用内的UIAbility。
call事件：可以使用call事件拉起指定UIAbility到后台，再通过UIAbility申请对应后台长时任务完成音乐播放等功能。
message事件：可以使用message拉起FormExtensionAbility，通过onFormEvent接口回调通知，以完成点击卡片控件后传递消息给应用的功能。

1.router事件

1.1.1概述

目的：在动态卡片中，通过postCardAction接口的router能力，快速拉起卡片提供方应用的指定UIAbility（页面）。
应用场景：例如相机卡片，提供拍照、录像等按钮，点击不同按钮拉起相机应用的不同页面，提升用户体验。
注意：本文仅适用于动态卡片。静态卡片的跳转请参考FormLink。

1.1.2 开发步骤

分为三个主要部分：

创建动态卡片（ArkTS卡片）
在卡片中布局按钮并发送router事件
在UIAbility中处理router事件，根据参数跳转不同页面

2.实现步骤

1.新建动态卡片

2.构建卡片页面

@Entry
@Component
struct ShoppingCard {build() {Column() {Button('进入应用').onClick(() => {postCardAction(this, {action: 'router',abilityName: 'EntryAbility',params: { targetPage: 'funA' }})})Button('进入应用B').onClick(() => {postCardAction(this, {action: 'router',abilityName: 'EntryAbility',params: { targetPage: 'funB' }})}).margin(10)Button('进入应用C').onClick(() => {postCardAction(this, {action: 'router',abilityName: 'EntryAbility',params: { targetPage: 'funC' }})})}.padding(10).height('100%').width('100%').backgroundImage($r('app.media.img'))}
}

效果如图所示

3.UIAbility事件处理

  //1.Ability（应用的核心单元创建的回调）//want:Want 包含启动的信息 （谁启动的、如何启动的、谁携带的参数）//launchParam-启动参数onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {// 获取router事件中传递的targetPage参数   调试时查看应用启动时的参数hilog.info(DOMAIN_NUMBER, TAG, `Ability onCreate: ${JSON.stringify(want?.parameters)}`);if (want?.parameters?.params) {//检查参数是否存在//安全操作符 ?.:防止参数不存在时报错//检查条件：是否存在want.parameters.params//来源：这个params是从卡片跳转的时候传递过来的（来自postCardAction的params）// want.parameters.params 对应 postCardAction() 中 params 内容let params: Record<string, Object> = JSON.parse(want.parameters.params as string);//解析参数//为什么需要解析参数   postCardAction传入的参数是一个json字符串   JSON.parse()将字符串转化为一个JavaScript对象//转化结果 params是一个字典this.selectPage = params.targetPage as string;hilog.info(DOMAIN_NUMBER, TAG, `onCreate selectPage: ${this.selectPage}`);}}

4.根据参数路由决定跳转的页面

  onWindowStageCreate(windowStage: window.WindowStage): void {// Main window is created, set main page for this abilityhilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate');let targetPage:string;switch (this.selectPage){case 'funA':targetPage = 'pages/Index';break ;case 'funB':targetPage = 'pages/Index1';break;case 'funC':targetPage = 'pages/Index2'break;default :targetPage = 'pages/Index3'}if(this.currentWindowStage === null){this.currentWindowStage = windowStage}windowStage.loadContent(targetPage);}

5.页面效果

6.缺陷发现

当应用已经在后台运行时点击卡片按钮：

不会触发：onCreate、onWindowStageCreate
只会触发：onNewWant、onForeground

所以多次点击时，selectPage 值会更新，但页面加载逻辑没有重新执行，导致显示的还是第一个加载的页面。缺少 onNewWant 实现：未处理应用已在后台时的路由更新

解决方法

/*** 当UIAbility已经在后台运行（即使没有创建新的Ability实例），并且有新的Want(意图，包含启动信息)传递过来时，系统会调用这个方法* 例如：当用户点击卡片上的不同按钮跳转到同一个UIAbility的不同功能页面时，如果UIAbility已经在后台，就会触发onNewWant而不是创建新的实例**/// 如果UIAbility已在后台运行，在收到Router事件后会触发onNewWant生命周期回调onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void {hilog.info(DOMAIN_NUMBER, TAG, `Ability onNewWant: ${JSON.stringify(want?.parameters)}`);if (want?.parameters?.params) {// want.parameters.params 对应 postCardAction() 中 params 内容let params: Record<string, Object> = JSON.parse(want.parameters.params as string);this.selectPage = params.targetPage as string;hilog.info(DOMAIN_NUMBER, TAG, `onNewWant selectPage: ${this.selectPage}`);}if (this.currentWindowStage !== null) {this.onWindowStageCreate(this.currentWindowStage);}}