卡片跳转到应用页面（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 开发步骤

分为三个主要部分：

1. 创建动态卡片（ArkTS卡片）
2. 在卡片中布局按钮并发送router事件
3. 在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 ability
    hilog.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);
    }
  }

7.效果展示