DevEco Studio页面跳转详解：从配置到实战，轻松驾驭HarmonyOS导航

本文介绍了HarmonyOS应用开发中基于Stage模型的页面跳转技术。主要内容包括：1）Stage模型与FA模型的区别；2）通过Router模块实现基本跳转、参数传递和页面返回；3）目标页面接收参数的方法；4）高级技巧如返回结果处理、条件跳转和动画配置；5）常见问题解决方案。文章强调掌握这些技术要点对构建复杂导航结构的重要性，并建议开发者通过实践掌握不同场景下的跳转方式。

像是套了虚弱散

1078人浏览 · 2025-09-03 17:05:03

像是套了虚弱散 · 2025-09-03 17:05:03 发布

在HarmonyOS应用开发中，页面跳转是实现应用导航和交互的核心功能。无论是简单的界面切换还是复杂的数据传递，掌握DevEco Studio中的页面跳转技术都至关重要。本文将带你全面了解Stage模型下的页面跳转机制。

一、两种模型的选择：Stage与FA

在开始之前，需要了解HarmonyOS的两种应用模型：

•FA（Feature Ability）模型：早期模型，适用于API 8及更低版本
•Stage模型：当前主推模型，从API 9开始引入，提供更好的性能和应用生命周期管理

强烈建议新项目直接使用Stage模型，这是未来的发展方向。本文所有示例均基于Stage模型。

二、Stage模型页面跳转核心：Router模块

1. 基础环境搭建

首先，在需要跳转的页面中导入router模块：

import router from '@ohos.router';

2. 路由配置

在module.json5文件中配置页面路由路径：

{
  "module": {
    "pages": [
      "./pages/Index",        // 路径默认为空（首页）
      "./pages/Detail",       // 路径：'pages/Detail'
      "./pages/UserProfile"   // 路径：'pages/UserProfile'
    ]
  }
}

3. 基本跳转方法

a) 普通跳转（无参数）

// 跳转到Detail页面
router.pushUrl({
  url: 'pages/Detail'
});

b) 带参数跳转

// 跳转并传递参数
router.pushUrl({
  url: 'pages/Detail',
  params: {
    productId: '12345',
    productName: 'HarmonyOS手机',
    price: 4999
  }
});

c) 替换当前页面

// 用新页面替换当前页面（无返回）
router.replaceUrl({
  url: 'pages/Login'
});

d) 返回上一页

// 简单返回
router.back();

// 返回并传递数据给上一页
router.back({
  url: 'pages/Index',
  params: {
    refresh: true,
    message: '操作成功'
  }
});

三、目标页面接收参数

在跳转到的页面中，通过router.getParams()方法获取传递的参数：

import router from '@ohos.router';

// 定义参数接口
interface ProductParams {
  productId: string;
  productName: string;
  price: number;
}

@Entry
@Component
struct DetailPage {
  // 接收参数
  private productInfo: ProductParams = router.getParams() as ProductParams;

  build() {
    Column() {
      Text(`产品ID: ${this.productInfo.productId}`)
        .fontSize(20)
        .margin(10)
      
      Text(`产品名称: ${this.productInfo.productName}`)
        .fontSize(18)
        .margin(10)
      
      Text(`价格: ￥${this.productInfo.price}`)
        .fontSize(18)
        .margin(10)
      
      Button('返回首页')
        .onClick(() => {
          router.back();
        })
        .margin(20)
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

四、高级用法与实战技巧

1. 页面返回结果处理

首页设置回调接收返回数据：

import router from '@ohos.router';

@Entry
@Component
struct IndexPage {
  @State message: string = '欢迎使用';

  onPageShow() {
    // 页面显示时检查是否有返回参数
    const params = router.getParams();
    if (params && params['message']) {
      this.message = params['message'] as string;
    }
  }

  build() {
    Column() {
      Text(this.message)
        .fontSize(20)
      
      Button('前往详情页')
        .onClick(() => {
          router.pushUrl({
            url: 'pages/Detail',
            params: { from: '首页' }
          });
        })
        .margin(20)
    }
  }
}

2. 条件跳转与路由守卫

// 检查登录状态后跳转
function navigateToProfile() {
  if (isLoggedIn) {
    router.pushUrl({
      url: 'pages/UserProfile'
    });
  } else {
    router.pushUrl({
      url: 'pages/Login',
      params: { redirect: 'UserProfile' }
    });
  }
}

3. 跳转动画配置

router.pushUrl({
  url: 'pages/Detail',
  params: { id: 123 },
  routerOptions: {
    // 设置跳转动画
    enterAnimation: { 
      duration: 500, 
      curve: Curve.Linear 
    },
    exitAnimation: {
      duration: 500,
      curve: Curve.Linear
    }
  }
});

五、常见问题与解决方案

1. 路由路径错误

问题：Error: page not found for given url...

解决：检查module.json5中的路径配置，确保与跳转时使用的路径完全一致。

2. 参数类型不匹配

问题：参数获取时类型断言错误

解决：使用接口明确定义参数类型，并进行安全转换：

interface MyParams {
  id: number;
  name: string;
}

const params = router.getParams();
if (params && 'id' in params && 'name' in params) {
  const safeParams = params as MyParams;
  // 使用safeParams
}