HarmonyOS 实现点击卡片跳转乘车码全教程

一、为什么要学 “点击卡片跳转乘车码”？

在日常出行中，我们经常需要打开 APP 找乘车码，步骤繁琐。而 “点击桌面卡片直接跳乘车码” 的功能，能让用户 3 秒内完成操作，是公交地铁类 APP 的 “必备技能”。

本文将用最简单的语言，带新手从零学会在 HarmonyOS（鸿蒙系统）中实现这个功能，包含完整代码、步骤拆解和常见问题解答。

二、效果长什么样？先看直观演示

简单说：桌面点一下，二维码直接跳出来，就这么方便！

三、核心技术是什么？一句话讲清楚

这个功能的核心是FormLink 组件，它就像 “卡片和 APP 之间的桥梁”。通过设置 FormLink 的 “跳转规则”，让卡片知道点击后该打开 APP 的哪个页面。

类比理解：就像快递单上的 “收货地址”，FormLink 的参数就是告诉系统 “点卡片后要送到哪个页面”。

四、准备工作：开发环境搭起来

在开始写代码前，必须确保你的工具符合要求，不然可能会报错哦！

安装 DevEco Studio 后，记得在设置里勾选 “HarmonyOS SDK 5.0.5+”，并等待自动下载完成。

五、工程文件长什么样？目录结构详解

打开项目后，文件目录就像 “书架上的书”，每个文件夹都有明确分工。新手不用记全，知道核心文件在哪就行：

├── entry/src/main/ets  // 代码主要存放地
│  ├── components       // 自定义按钮、导航栏等组件
│  ├── constants        // 常量（比如固定的页面名称）
│  ├── entryability     // 应用入口能力（类似APP的“大门”）
│  ├── pages            // 页面文件（重点！）
│  │  ├── QrCodeCard.ets  // 桌面卡片的样式代码
│  │  ├── QrCodePage.ets  // 乘车二维码页面代码
│  ├── router           // 路由管理（控制页面跳转）
│  └── util             // 工具类（比如日期处理、存储工具）
└── resources           // 图片、文字等资源（比如卡片上的文字）

新手重点关注：pages文件夹（页面长什么样）和router文件夹（怎么跳转）。

六、一步一步写代码：从卡片到跳转全实现

6.1 第一步：定义卡片的样式（QrCodeCard.ets）

先让桌面卡片显示出来，包含 “地铁出行” 文字和 “点击查看二维码” 按钮。

// pages/QrCodeCard.ets
@Entry
@Component
struct QrCodeCard {
  // 定义跳转需要的参数
  private actionType: string = 'router'  // 固定值，代表跳转操作
  private abilityName: string = 'EntryAbility'  // 入口能力名称（大门名称）
  private message: string = '点击卡片跳乘车码'  // 传递的消息

  build() {
    Column() {
      // 卡片标题
      Text('地铁出行')
        .fontSize(18)
        .margin(10)
      
      // 点击区域（核心：用FormLink实现跳转）
      FormLink({
        action: this.actionType,  // 告诉系统：这是一个跳转操作
        abilityName: this.abilityName,  // 告诉系统：从哪个入口进APP
        params: {  // 跳转的“详细地址”
          message: this.message,  // 附带的消息（可选）
          linkType: 'form_card',  // 标记这是卡片跳转
          router: 'QrCodePage'  // 目标页面：QrCodePage.ets
        }
      }) {
        // FormLink内部的样式：点击按钮
        Button('点击查看二维码')
          .backgroundColor('#007DFF')
          .textColor('white')
          .padding({ left: 20, right: 20 })
      }
    }
    .width('100%')
    .height(100)
    .backgroundColor('#F5F5F5')
    .borderRadius(10)
  }
}

代码解释：

• FormLink是 “跳转桥梁”，里面的params是关键，router: 'QrCodePage'表示要跳转到QrCodePage页面。
• Button是卡片上的点击按钮，样式可以自己改颜色、大小。

6.2 第二步：编写乘车码页面（QrCodePage.ets）

这是点击后最终显示的页面，简单放一个二维码图片和 “乘车码” 标题。

// pages/QrCodePage.ets
@Entry
@Component
struct QrCodePage {
  build() {
    Column() {
      Text('乘车码')
        .fontSize(20)
        .margin(20)
      
      // 这里用图片占位，实际项目中替换成真实二维码
      Image($r('app.media.qrcode'))  // 图片放在resources/media目录下
        .width(200)
        .height(200)
        .margin(10)
      
      Text('靠近闸机扫码即可')
        .fontSize(14)
        .color('#666666')
    }
    .width('100%')
    .height('100%')
    .backgroundColor('white')
  }
}

新手提示：如果没有二维码图片，先用文字Text('乘车二维码')代替，后续再替换。

6.3 第三步：配置路由（让系统知道页面在哪）

路由就像 “地图”，告诉系统QrCodePage这个页面的位置。

// router/RouterConfig.ets
export default class RouterConfig {
  // 定义页面路由表：key是页面名称，value是页面路径
  static routes = {
    QrCodePage: '/pages/QrCodePage'  // 关键：QrCodePage对应pages/QrCodePage.ets
  }
}

再写一个路由工具类，简化跳转代码：

// router/RouterUtil.ets
import Router from '@ohos.router'
import RouterConfig from './RouterConfig'

export default class RouterUtil {
  // 跳转到指定页面的方法
  static pushPage(pageName: string) {
    Router.pushUrl({
      url: RouterConfig.routes[pageName]  // 从路由表中找路径
    })
  }
}

6.4 第四步：处理卡片点击事件（EntryAbility.ets）

当用户点击卡片时，系统会触发这个入口能力，调用路由工具跳转到目标页面。

// entryability/EntryAbility.ets
import UIAbility from '@ohos.app.ability.UIAbility'
import Window from '@ohos.window'
import RouterUtil from '../router/RouterUtil'

export default class EntryAbility extends UIAbility {
  // 当APP被卡片启动时调用
  onNewWant(want: Want) {
    super.onNewWant(want)
    // 从want中获取跳转参数（就是FormLink里的params）
    const routerPage = want.params?.router
    if (routerPage) {
      // 调用路由工具跳转到目标页面
      RouterUtil.pushPage(routerPage)
    }
  }

  // 初始化窗口（不用改，固定写法）
  onWindowStageCreate(windowStage: Window.WindowStage) {
    windowStage.loadContent('pages/QrCodeCard', (err, data) => {
      if (err.code) {
        console.error('加载页面失败：', err.message)
        return
      }
    })
  }
}

代码解释：onNewWant方法会接收卡片传递的router: 'QrCodePage'，然后调用RouterUtil跳转到对应页面。

用大白话讲流程：

1. 用户点卡片 → 2. 卡片告诉系统 “要去 QrCodePage” → 3. 系统找这个页面在哪 → 4. 打开页面显示二维码。

八、常见问题：新手容易踩的坑（附解决办法）

九、总结：新手入门的 3 个关键

1. FormLink 是桥梁：记住它的params里要写router: '目标页面名'。
2. 路由要配置：目标页面必须在RouterConfig中注册路径。
3. 入口能力要处理：EntryAbility的onNewWant方法负责接收跳转指令。

按照这个教程，即使是新手也能在 1 小时内实现 “点击卡片跳乘车码” 功能。快去动手试试，让你的 APP 也拥有这个实用功能吧！