前言

在 HarmonyOS ArkUI 多页面项目开发中，页面跳转、跨页面数据传递是核心必备能力。系统提供router路由工具实现页面切换、参数携带，搭配main_pages.json页面注册配置、onPageShow页面生命周期完成完整业务。 本文结合登录跳转首页实战案例，包含页面注册配置、登录表单页面、首页接收参数三段完整代码，从底层配置到交互逻辑全覆盖。

一、main_pages.json 页面注册配置

文件路径：entry/src/main/resources/base/profile/main_pages.json 作用：系统识别所有可路由页面，未注册页面无法跳转，数组第一项为 APP 启动首页。 完整注册配置：

{
  "src": [
    "pages/Index",
    "pages/Second",
    "pages/Logins",
    "pages/Register",
    "pages/RouterDemo",
    "pages/PageOne",
    "pages/Home",
    "pages/LoginRouter",
    "pages/HomePage"
  ]
}

注意：

配置完成后点击同步！！！

本次案例用到两个核心页面：

1. pages/LoginRouter：登录页面（程序默认首页，数组第一个可调整为此项）
2. pages/HomePage：登录成功跳转的首页

二、登录页面 LoginRouter.ets

页面功能

1. 双输入框分别绑定账号、密码状态，密码框隐藏明文；
2. 蓝色圆角登录按钮，点击校验账号密码；
3. 账号密码匹配成功，使用router.pushUrl跳转到首页，同步传递用户名；
4. 账号密码错误弹出弹窗提示，不执行页面跳转。

完整代码

// 导入路由工具，实现页面跳转与传参
import { router } from '@kit.ArkUI'

@Entry
@Component
struct LoginRouter{
  // 响应式变量：存储账号输入内容，输入框变化自动刷新UI
  @State username:string=""
  // 响应式变量：存储密码输入内容
  @State password:string=""

  build() {
    Column({space:30}){
      Text('登录')
        .fontSize(32)
        .fontWeight(FontWeight.Bolder)

      // 账号输入框，双向绑定username
      TextInput({text:this.username,placeholder:"请输入账号"})
        .width('100%')
        .height(50)  
        // 监听输入内容变化，实时同步到username变量
        .onChange((valus:string)=>{
          this.username=valus
        })

      // 密码输入框，双向绑定password
      TextInput({text:this.password,placeholder:"请输入密码"})
        .width('100%')
        .height(50)
        // 输入文字实时赋值给password
        .onChange((value:string)=>{
          this.password=value
        })

      // 登录按钮，点击执行校验+跳转逻辑
      Button('登录')
        .height(50)
        .width('100%')
        .fontSize(22)
        .onClick(()=>{
          // 判断：账号、密码都不为空才允许跳转
          if (this.username!=""&&this.password!="") {
            // 路由跳转到首页HomePage
            router.pushUrl({
              url: "pages/HomePage", // 目标页面路径，和json注册名保持一致
              // params：需要传递给下一页的参数对象
              params:{
                username:this.username, // 传递账号
                password:this.password  // 传递密码
              }
            })
          }
          else {
            // 账号/密码为空，弹出提示弹窗
            AlertDialog.show({
              title:"登录失败",
              message:`用户名或密码不能为空`
            })
          }
        })
    }
    .width('100%')  
    .height('100%') 
    .padding(15)   
  }
}

效果

三、首页 HomePage.ets

页面功能

1. 页面生命周期onPageShow触发时，读取路由传递过来的 username；
2. 将用户名存入@State变量，Text 动态渲染欢迎文字；
3. 接收参数逻辑放在生命周期，保证每次进入页面都能拿到数据。

完整代码

import { router } from '@kit.ArkUI'
@Entry
@Component
struct HomePage{
  // 存储接收过来的用户名
  @State name:string=""

  // 页面每次显示自动执行，用来接收路由传参
  onPageShow(): void {
    // 获取上一页传递的全部参数
    const params=router.getParams() as Record<string,string>
    // 判断参数存在，赋值给状态变量
    if (params) {
      this.name = params.username
    }
  }

  build() {
    Column(){
      // 模板字符串渲染接收的用户名
      Text(`欢迎你，${this.name}`)
        .fontSize(28)
        .margin({top:60})
    }
    .width('100%')
    .height('100%')
  }
}

效果

参数接收代码拆解

1. router.getParams()：读取上一页params携带的全部数据；
2. as Record<string,string>：类型断言，约束参数键与值均为字符串，消除编译报错；
3. if(params)空值判断：避免直接打开首页无参数导致代码报错；
4. this.name = params.username：提取传递的用户名存入响应式变量，UI 自动刷新文字。

核心知识点汇总

1. 路由开发完整四步流程

1. 新建页面，在main_pages.json的src数组注册页面路径；
2. 跳转页面文件顶部导入router路由模块；
3. 按钮点击事件调用router.pushUrl，填写目标 url 与传递参数；
4. 目标页面在onPageShow生命周期内接收并处理参数。

2. main_pages.json 开发规范

1. 新增页面必须同步注册路径，否则路由跳转失效；
2. 数组第一项为 APP 默认启动首页，可自由调整顺序；
3. 路径名称必须和 pages 文件夹内页面文件名完全一致。

3. 生命周期 onPageShow 使用场景

• 接收路由跨页传递参数（最优场景）；
• 页面返回、重新进入时刷新数据；
• 页面打开时发起网络请求加载内容。

4. 高频踩坑与解决方案

1. 点击登录页面空白无跳转 排查：目标页面未在main_pages.json注册 /pushUrl 内 url 拼写、大小写不匹配；
2. 首页不显示用户名，文字空白 排查：参数接收逻辑写在 build 函数内，必须迁移至onPageShow；
3. 直接打开首页程序崩溃 解决方案：添加if(params)判空逻辑，无参数时不赋值；
4. 代码标红提示 router 不存在 解决方案：文件首行补充导入语句import { router } from '@kit.ArkUI'。