template-10550/docs/NAVIGATION_MIGRATION_GUIDE.md

导航工具迁移指南

🎯 迁移目标

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

📋 迁移对照表

1. 基础导航

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

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

2. 带参数导航

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

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

3. TabBar 页面

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

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

4. 页面替换

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

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

5. 重新启动

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

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

🔄 具体迁移示例

示例1：搜索页面

// 旧代码
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：商品详情

// 旧代码
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切换

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

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

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

示例4：登录跳转

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

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

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

🛠️ 批量替换脚本

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

1. 简单导航替换

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

# 替换为
goTo('$1')

2. switchTab替换

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

# 替换为
switchTab('$1')

3. redirectTo替换

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

# 替换为
redirectTo('$1')

📦 导入语句

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

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

⚠️ 注意事项

1. 路径格式化

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

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

2. 参数处理

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

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

3. 特殊路径

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

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

🎉 迁移收益

1. 代码更简洁

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

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

2. 参数处理更方便

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

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

3. 错误处理更统一

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

4. TypeScript支持更好

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

📋 迁移检查清单

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

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