Router5 从 5.x 迁移到 6.x 版本指南

Router5 从 5.x 迁移到 6.x 版本指南

前言

Router5 是一个功能强大的客户端路由库，在 6.0.0 版本中对路由选项进行了重大重构，使其更加直观和灵活。本文将详细介绍从 5.x 升级到 6.x 版本需要注意的关键变化和迁移策略。

核心特性变化

1. 导航选项处理方式变更

在 6.x 版本中，导航选项现在会被添加到状态对象的 meta 属性中。这一变化使得：

• 状态对象包含了完整的导航上下文信息
• 开发者可以自定义导航选项，这些选项会被添加到状态对象中
• 自定义插件和中间件可以更方便地访问这些选项

2. 新增配置选项

6.x 版本引入了两个重要的新配置选项：

caseSensitive (默认为 false)

• 控制路径匹配是否区分大小写
• 5.x 版本默认是区分大小写的，6.x 改为不区分

queryParams

• 全新的查询参数配置方式
• 可以精细控制查询参数的构建和解析行为

React 集成改进

对于使用 React 的开发者，6.x 版本提供了新的组件实现方式：

1. 新增了基于渲染函数的组件
2. 这些组件利用了 React 16.3+ 的新 Context API
3. 原有的高阶组件(HOC)仍然保留，不会被废弃
4. 未来高阶组件也将迁移到使用新的 Context API

重要修复

1. 修复了在 IE11 浏览器下，使用 hash 模式时手动修改 URL 的导航问题
2. 重构了过渡阶段处理逻辑，确保中间件中使用 done 回调或 Promise 时的状态变更能正确工作

破坏性变更详解

1. 路径匹配行为变更

• 5.x: 默认区分大小写
• 6.x: 默认不区分大小写(可通过 caseSensitive 选项配置)

2. 查询参数定义语法变更

• 不再支持使用 [] 定义查询参数
• 需要移除原有的方括号语法

3. 选项重命名

| 5.x 选项 | 6.x 选项 | 说明 | |---------|---------|------| | trailingSlash | strictTrailingSlash | 默认值改为 false | | useTrailingSlash | trailingSlashMode | 新增更多模式 | | strictQueryParams | queryParamsMode | 新增更多模式 |

4. 查询参数处理行为变更

• 布尔值默认转为 'true'/'false' 字符串
• null 值默认转为不带等号的形式(?param)
• 要保持 5.x 行为需设置：
  • queryParams.nullFormat = 'hidden'
  • queryParams.booleanFormat = 'empty-true'

新选项配置详解

1. trailingSlashMode 尾斜杠模式

• 'default': 遵循路径定义
• 'none': 构建时移除尾斜杠
• 'always': 构建时添加尾斜杠

2. queryParamsMode 查询参数模式

• 'default': 匹配时允许额外参数，构建时不包含
• 'strict': 严格匹配定义参数，构建时不包含额外参数
• 'loose': 匹配允许额外参数，构建时也包含

3. queryParams 查询参数配置

arrayFormat 数组格式

• 'none': 简单重复参数名(role=member&role=admin)
• 'brackets': 添加方括号(role[]=member&role[]=admin)
• 'index': 添加索引(role[0]=member&role[1]=admin)

booleanFormat 布尔值格式

• 'none': 转为字符串(true/false)
• 'empty-true': true 值不带值(istrue&isfalse=false)
• 'string': 转为字符串但解析为布尔
• 'unicode': 使用特殊字符表示(✓/✗)

nullFormat null值格式

• 'default': 不带等号和值(isnull)
• 'string': 转为 'null' 字符串(isnull=null)
• 'hidden': 不输出

迁移建议

1. 首先检查项目中是否使用了方括号定义查询参数，需要移除
2. 评估路径匹配是否需要区分大小写，必要时设置 caseSensitive
3. 根据项目需求配置 queryParams 相关选项，特别是布尔值和 null 值的处理方式
4. React 项目可以考虑迁移到新的基于渲染函数的组件
5. 测试所有手动修改 URL 的场景，特别是在 IE11 下的行为

通过合理配置新选项，可以确保升级后保持与 5.x 版本相同的行为，同时享受 6.x 版本带来的灵活性和改进。