template-10550/docs/NAVIGATION_USAGE.md

导航工具使用指南

📖 概述

封装了 Taro 的导航方法，提供更便捷和统一的页面跳转功能。

🚀 主要特性

• ✅ 自动路径格式化 - 自动添加 /pages/ 前缀
• ✅ 参数自动编码 - 自动处理 URL 参数编码
• ✅ 多种导航方式 - 支持所有 Taro 导航方法
• ✅ 错误处理 - 统一的错误处理和提示
• ✅ TypeScript 支持 - 完整的类型定义

📦 导入方式

// 导入主要函数
import { navigateTo, goTo, redirectTo, reLaunch, switchTab, goBack } from '@/utils/navigation'

// 或者导入默认函数
import navigateTo from '@/utils/navigation'

🎯 使用方法

1. 基础导航

// 最简单的用法 - 自动格式化路径
goTo('coupon/index')  // 自动转换为 /pages/coupon/index

// 等价于
navigateTo('coupon/index')

// 传统写法对比
Taro.navigateTo({ url: '/pages/coupon/index' })

2. 带参数导航

// 传递参数
goTo('product/detail', { 
  id: 123, 
  type: 'hot' 
})
// 结果: /pages/product/detail?id=123&type=hot

// 复杂参数自动编码
goTo('search/result', {
  keyword: '优惠券',
  category: '美食',
  price: [10, 100]
})

3. 不同导航方式

// 普通跳转（默认）
goTo('user/profile')

// 替换当前页面
redirectTo('login/index')

// 重新启动应用
reLaunch('home/index')

// 切换到 tabBar 页面
switchTab('home/index')

// 返回上一页
goBack()

// 返回多页
goBack(2)

4. 高级用法

// 完整选项配置
navigateTo({
  url: 'order/detail',
  params: { orderId: '12345' },
  success: () => {
    console.log('跳转成功')
  },
  fail: (error) => {
    console.error('跳转失败:', error)
  }
})

// 不同导航类型
navigateTo({
  url: 'login/index',
  replace: true,  // 使用 redirectTo
  params: { from: 'profile' }
})

navigateTo({
  url: 'home/index',
  switchTab: true  // 使用 switchTab
})

🛠️ 路径格式化规则

自动添加前缀

// 输入 -> 输出
'coupon/index'           -> '/pages/coupon/index'
'/coupon/index'          -> '/pages/coupon/index'
'pages/coupon/index'     -> '/pages/coupon/index'
'/pages/coupon/index'    -> '/pages/coupon/index'

特殊路径处理

// 如果已经是完整路径，不会重复添加
'/pages/user/profile'    -> '/pages/user/profile'
'/subPages/vip/index'    -> '/subPages/vip/index'

🎨 实际使用示例

在组件中使用

import React from 'react'
import { Button } from '@nutui/nutui-react-taro'
import { goTo, switchTab } from '@/utils/navigation'

const ProductCard = ({ product }) => {
  const handleViewDetail = () => {
    goTo('product/detail', { 
      id: product.id,
      from: 'list'
    })
  }
  
  const handleGoHome = () => {
    switchTab('home/index')
  }
  
  return (
    <View>
      <Button onClick={handleViewDetail}>
        查看详情
      </Button>
      <Button onClick={handleGoHome}>
        返回首页
      </Button>
    </View>
  )
}

在页面中使用

import { useEffect } from 'react'
import { redirectTo, getCurrentRoute } from '@/utils/navigation'

const LoginPage = () => {
  useEffect(() => {
    // 检查登录状态
    const checkAuth = async () => {
      const isLoggedIn = await checkLoginStatus()
      if (isLoggedIn) {
        // 已登录，跳转到首页
        redirectTo('home/index')
      }
    }
    
    checkAuth()
  }, [])
  
  const handleLogin = async () => {
    try {
      await login()
      // 登录成功，跳转
      redirectTo('home/index')
    } catch (error) {
      console.error('登录失败:', error)
    }
  }
  
  return (
    // 登录页面内容
  )
}

🔧 工具函数

// 获取当前页面路径
const currentRoute = getCurrentRoute()
console.log(currentRoute) // 'pages/user/profile'

// 获取页面栈
const pages = getCurrentPages()
console.log(pages.length) // 当前页面栈深度

⚠️ 注意事项

1. tabBar 页面：使用 switchTab 时不能传递参数
2. 页面栈限制：小程序页面栈最多 10 层
3. 参数大小：URL 参数有长度限制，大数据建议使用全局状态
4. 特殊字符：参数值会自动进行 URL 编码

🎉 迁移指南

替换现有代码

// 旧写法
Taro.navigateTo({
  url: '/pages/product/detail?id=123&type=hot'
})

// 新写法
goTo('product/detail', { id: 123, type: 'hot' })

// 旧写法
Taro.redirectTo({
  url: '/pages/login/index'
})

// 新写法
redirectTo('login/index')

现在你可以在整个项目中使用这些便捷的导航函数了！