TypeScript中react-router-dom useHistory传参与跳转state的强类型定义问题

之前类型识别失效的核心原因 #

• History<unknown>写法：History接口的泛型参数是专门用来指定路由location.state的字段类型，传unknown会让state被推导为无具体结构的unknown类型，完全丢失类型校验能力，和写any没有本质区别
• History<Location>写法：泛型传递完全错位——这个写法相当于把state的类型定义为整个Location对象结构，和实际要传的自定义state字段完全不匹配，TS自然无法正确识别你定义的detail、response字段

分步实现强类型 #

• 第一步：抽离自定义路由state的独立类型
  把你跳转逻辑里携带的state结构定义为可复用的TS类型，放到项目models目录统一维护，和你现有代码的结构完全对齐：

  import type { IHttpResponse } from '../models/IHttpResponse';
  
  // 员工创建完成后跳转携带的路由state类型
  export type EmployeeCreateRouteState = {
    detail: 'reload'; // 对固定值做类型收窄，比宽泛的string更安全
    response: IHttpResponse;
  }
  

• 第二步：修正服务层的history参数类型
  注意：History类型需要从react-router v5的底层依赖history包导入（安装react-router-dom时会自动附带这个包，无需额外安装），替换掉原有的any类型：

  import type { History } from 'history';
  import type { EmployeeCreateRouteState } from '../models/RouteState';
  
  // 修正后的createEmployee方法签名
  export const createEmployee = async (
    body: IEmployee,
    // 把原有的any替换为带正确泛型的History类型
    history: History<EmployeeCreateRouteState>
  ) => {
    // 原有业务逻辑完全不需要改动
    // 此时TS会自动校验push时传入的state结构：
    // 漏传字段、字段值不符合约定都会直接触发类型报错
    history.push({
      pathname: '/',
      state: { detail: 'reload', response: response }
    })
  }
  

• 第三步：在组件层匹配对应泛型
  原组件中直接调用useHistory()拿到的是默认类型的history实例（state被推导为unknown），需要把对应的state类型通过泛型传给useHistory，保证传给服务层的实例和服务层定义的类型完全兼容：

  // AddEmployeeForm组件内的原调用
  // 改前：const history = useHistory();
  // 改后：通过泛型传入匹配的state类型
  const history = useHistory<EmployeeCreateRouteState>();
  

可选的全局类型优化（适配多场景项目） #

如果项目存在多个不同跳转场景、携带不同结构的路由state，可以把所有场景的state类型合并为联合类型，通过TS模块扩展能力全局重写useHistory的默认返回类型，避免每次调用都单独传泛型：

1. 在项目types目录下新建全局类型声明文件：

// src/types/react-router.d.ts
import 'react-router-dom';
import type { History } from 'history';
// 收集项目所有路由跳转的state类型为联合类型
type AppRouteState = 
  | EmployeeCreateRouteState
  | 其他场景下的路由state类型;

// 全局扩展useHistory的默认返回类型
declare module 'react-router-dom' {
  export function useHistory(): History<AppRouteState>;
}

2. 配置完成后，全项目调用useHistory时会自动匹配所有可能的state结构，同时跳转目标页通过useLocation读取state时，TS也能自动完成结构推导，不需要手动做类型断言。

最终实现效果 #

• 服务层编写history.push逻辑时，若state漏传字段、字段值不符合约定类型，TS会直接抛出类型错误
• 跳转目标页读取路由携带的state时，能直接获得完整的结构类型提示，无需强制类型断言
• 完全移除any类型的临时规避，实现从业务层到路由跳转的全链路类型安全

内容的提问来源于stack exchange，提问作者Rodney Wormsbecher