Taro 路由相关 API 详解与实战

在多端应用开发中，页面路由是最基础也是最重要的功能之一。Taro 作为一款多端统一开发框架，提供了与微信小程序一致的路由 API，帮助开发者在小程序、H5、React Native 等平台上实现一致的页面跳转和路由管理。本文将详细介绍 Taro 路由相关的常用 API，包括：

Taro.navigateTo(options)
Taro.redirectTo(options)
Taro.switchTab(options)
Taro.reLaunch(options)
Taro.navigateBack(options)
Taro.getCurrentPages()

一、Taro.navigateTo(options)

作用：保留当前页面，跳转到应用内的某个非 tabBar 页面。跳转后，当前页面会被压入页面栈，用户可以通过 Taro.navigateBack 返回。

常见场景：详情页、编辑页等。

参数说明：

url：目标页面路径（必须是非 tabBar 页面，可以带参数）

示例：

js 复制代码

import Taro from '@tarojs/taro';

Taro.navigateTo({
  url: '/pages/detail/index?id=123'
});

二、Taro.redirectTo(options)

作用：关闭当前页面，跳转到应用内的某个非 tabBar 页面。跳转后，当前页面会被移出页面栈。

常见场景：表单提交成功后跳转到结果页，避免用户返回上一步。

参数说明：

url：目标页面路径（必须是非 tabBar 页面，可以带参数）

示例：

js 复制代码

Taro.redirectTo({
  url: '/pages/result/index?status=success'
});

三、Taro.switchTab(options)

作用：跳转到 tabBar 页面，并关闭其他所有非 tabBar 页面。

常见场景：底部导航栏切换，如首页、我的、发现等。

参数说明：

url：目标 tabBar 页面路径（必须是 tabBar 页面，不能带参数）

示例：

js 复制代码

Taro.switchTab({
  url: '/pages/home/index'
});

四、Taro.reLaunch(options)

作用：关闭所有页面，打开到应用内的某个页面。常用于登录、退出登录、重置流程等场景。

参数说明：

url：目标页面路径（可以是 tabBar 或非 tabBar 页面，可以带参数）

示例：

js 复制代码

Taro.reLaunch({
  url: '/pages/login/index'
});

五、Taro.navigateBack(options)

作用：关闭当前页面，返回上一页面或多级页面。

常见场景：返回按钮、操作完成后返回列表页等。

参数说明：

delta：返回的页面数，默认为 1

示例：

js 复制代码

Taro.navigateBack({
  delta: 1 // 返回上一级
});

六、Taro.getCurrentPages()

作用：获取当前页面栈的实例列表。页面栈按栈的顺序排列，栈顶为当前页面。

常见场景：获取页面参数、判断页面来源、页面间通信等。

示例：

js 复制代码

const pages = Taro.getCurrentPages();
const currentPage = pages[pages.length - 1];
console.log('当前页面路径:', currentPage.route);
console.log('当前页面参数:', currentPage.options);

七、路由 API 使用建议

页面路径要准确

跳转路径必须在 app.config.js 或 app.config.ts 的 pages 或 tabBar 配置中声明。
tabBar 页面只能用 switchTab 或 reLaunch 跳转

不能用 navigateTo 或 redirectTo 跳转到 tabBar 页面。
带参数跳转

可以在 url 后拼接参数，如 /pages/detail/index?id=123，在目标页面通过 useRouter 或 getCurrentInstance().router 获取参数。
页面栈限制

小程序页面栈最多 10 层，跳转过多会报错，需注意页面跳转的合理性。
页面间通信

可以通过页面栈获取前一个页面实例，实现页面间数据传递。

八、常见应用场景举例

商品列表跳转商品详情
Taro.navigateTo({ url: '/pages/product/detail?id=1001' })
登录成功后重定向到首页
Taro.reLaunch({ url: '/pages/home/index' })
表单提交后跳转结果页并禁止返回
Taro.redirectTo({ url: '/pages/result/index?status=ok' })
底部导航栏切换
Taro.switchTab({ url: '/pages/user/index' })
返回上一级页面
Taro.navigateBack({ delta: 1 })

九、总结

Taro 路由 API 设计简洁，功能强大，能够满足多端应用的各种页面跳转需求。合理使用这些 API，可以让你的应用页面流转更加顺畅，用户体验更佳。开发时建议结合实际业务场景，选择合适的路由跳转方式，并注意页面栈和参数传递等细节。

参考文档：
Taro 官方文档 - 路由