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

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

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

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

场景	截图描述	操作效果
桌面卡片	桌面显示 “地铁出行 点击查看二维码” 卡片	静态展示，等待用户点击
点击后	自动打开 APP 并直接显示乘车二维码	无需手动找页面，一步到位

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

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

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

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

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

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

工具 / 版本	最低要求	新手建议
API 版本	API Version 17 Release 及以上	直接用最新版，避免兼容性问题
HarmonyOS SDK	5.0.5 Release 及以上	安装时勾选 “5.0.5 及以上” 版本
开发工具	DevEco Studio 5.0.5 Release 及以上	官网下载最新版，傻瓜式安装

安装 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. 打开页面显示二维码。

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

问题	原因	解决办法
卡片点了没反应	FormLink 的 action 没设为 'router'	检查action: this.actionType中actionType是否等于 'router'
跳转后是空白页	路由路径写错了	核对 RouterConfig 中QrCodePage的路径是否为/pages/QrCodePage
编译报错 “API 版本不够”	用了低于 17 的 API	在项目设置里把 API 版本改成 17 及以上
卡片不显示在桌面	没配置卡片能力	确保qrcodeformability文件夹下有QrCodeFormAbility.ets（参考官方示例）

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

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

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