template-10579/docs/NAVIGATION_MIGRATION_GUIDE.md

# 导航工具迁移指南

## 🎯 迁移目标

将项目中的 `Taro.navigateTo`、`Taro.switchTab` 等调用替换为新的导航工具函数。

## 📋 迁移对照表

### 1. 基础导航

```typescript
// 旧写法 ❌
Taro.navigateTo({ url: '/pages/product/detail' })

// 新写法 ✅
goTo('product/detail')
```

### 2. 带参数导航

```typescript
// 旧写法 ❌
Taro.navigateTo({ 
  url: `/pages/search/index?keywords=${encodeURIComponent(keywords)}` 
})

// 新写法 ✅
goTo('search/index', { keywords })
```

### 3. TabBar 页面

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

// 新写法 ✅
switchTab('index/index')
```

### 4. 页面替换

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

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

### 5. 重新启动

```typescript
// 旧写法 ❌
Taro.reLaunch({ url: '/pages/home/index' })

// 新写法 ✅
reLaunch('home/index')
```

## 🔄 具体迁移示例

### 示例1：搜索页面

```typescript
// 旧代码
const onQuery = () => {
  Taro.navigateTo({
    url: `/shop/search/index?keywords=${encodeURIComponent(keywords.trim())}`
  });
}

// 新代码
import { goTo } from '@/utils/navigation';

const onQuery = () => {
  goTo('shop/search/index', { keywords: keywords.trim() });
}
```

### 示例2：商品详情

```typescript
// 旧代码
const viewProduct = (productId: number) => {
  Taro.navigateTo({
    url: `/pages/product/detail?id=${productId}&from=list`
  });
}

// 新代码
import { goTo } from '@/utils/navigation';

const viewProduct = (productId: number) => {
  goTo('product/detail', { id: productId, from: 'list' });
}
```

### 示例3：TabBar切换

```typescript
// 旧代码
const goHome = () => {
  Taro.switchTab({ url: '/pages/index/index' });
}

// 新代码
import { switchTab } from '@/utils/navigation';

const goHome = () => {
  switchTab('index/index');
}
```

### 示例4：登录跳转

```typescript
// 旧代码
const handleLogin = () => {
  Taro.redirectTo({ url: '/pages/login/index' });
}

// 新代码
import { redirectTo } from '@/utils/navigation';

const handleLogin = () => {
  redirectTo('login/index');
}
```

## 🛠️ 批量替换脚本

可以使用以下正则表达式进行批量替换：

### 1. 简单导航替换

```bash
# 查找
Taro\.navigateTo\(\{\s*url:\s*['"`]([^'"`]+)['"`]\s*\}\)

# 替换为
goTo('$1')
```

### 2. switchTab替换

```bash
# 查找
Taro\.switchTab\(\{\s*url:\s*['"`]([^'"`]+)['"`]\s*\}\)

# 替换为
switchTab('$1')
```

### 3. redirectTo替换

```bash
# 查找
Taro\.redirectTo\(\{\s*url:\s*['"`]([^'"`]+)['"`]\s*\}\)

# 替换为
redirectTo('$1')
```

## 📦 导入语句

在每个需要使用导航的文件顶部添加：

```typescript
import { goTo, switchTab, redirectTo, reLaunch, goBack } from '@/utils/navigation';
```

## ⚠️ 注意事项

### 1. 路径格式化

新工具会自动处理路径格式：

```typescript
// 这些写法都会被自动转换为 /pages/product/detail
goTo('product/detail')
goTo('/product/detail')
goTo('pages/product/detail')
goTo('/pages/product/detail')
```

### 2. 参数处理

```typescript
// 旧写法需要手动编码
const url = `/pages/search?keyword=${encodeURIComponent(keyword)}&type=${type}`;

// 新写法自动处理编码
goTo('search', { keyword, type });
```

### 3. 特殊路径

对于非 `/pages/` 开头的路径（如分包页面），工具会保持原样：

```typescript
goTo('/subPages/vip/index')  // 保持不变
goTo('/packageA/user/profile')  // 保持不变
```

## 🎉 迁移收益

### 1. 代码更简洁

```typescript
// 旧：42个字符
Taro.navigateTo({ url: '/pages/product/detail' })

// 新：22个字符
goTo('product/detail')
```

### 2. 参数处理更方便

```typescript
// 旧：需要手动拼接和编码
const url = `/pages/search?q=${encodeURIComponent(query)}&page=${page}`;
Taro.navigateTo({ url });

// 新：自动处理
goTo('search', { q: query, page });
```

### 3. 错误处理更统一

```typescript
// 新工具自动包含错误处理
goTo('some/page').catch(error => {
  // 自动显示错误提示
});
```

### 4. TypeScript支持更好

```typescript
// 完整的类型提示和检查
navigateTo({
  url: 'product/detail',
  params: { id: 123 },
  success: () => console.log('成功'),
  fail: (error) => console.error(error)
});
```

## 📋 迁移检查清单

- [ ] 替换所有 `Taro.navigateTo` 调用
- [ ] 替换所有 `Taro.switchTab` 调用  
- [ ] 替换所有 `Taro.redirectTo` 调用
- [ ] 替换所有 `Taro.reLaunch` 调用
- [ ] 添加必要的导入语句
- [ ] 测试所有页面跳转功能
- [ ] 验证参数传递正确性
- [ ] 检查错误处理是否正常

完成迁移后，你的导航代码将更加简洁、安全和易维护！