template-10579/docs/NAVIGATION_USAGE.md

# 导航工具使用指南

## 📖 概述

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

## 🚀 主要特性

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

## 📦 导入方式

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

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

## 🎯 使用方法

### 1. 基础导航

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

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

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

### 2. 带参数导航

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

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

### 3. 不同导航方式

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

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

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

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

// 返回上一页
goBack()

// 返回多页
goBack(2)
```

### 4. 高级用法

```typescript
// 完整选项配置
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
})
```

## 🛠️ 路径格式化规则

### 自动添加前缀

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

### 特殊路径处理

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

## 🎨 实际使用示例

### 在组件中使用

```typescript
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>
  )
}
```

### 在页面中使用

```typescript
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 (
    // 登录页面内容
  )
}
```

## 🔧 工具函数

```typescript
// 获取当前页面路径
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 编码

## 🎉 迁移指南

### 替换现有代码

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

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

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

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

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