本技能讲解 TanStack Router 的类型安全写法。核心是:参数、搜索参数、context 与 loader 数据全部由路由树自动推断,不应再手动添加类型标注、断言或泛型参数,否则会掩盖真实类型错误并打断推断链。
唯一必需的类型标注是 Register 模块声明:创建 router 后通过 declare module '@tanstack/react-router' 注册 Register.router,注册后全应用的 Link、useNavigate、useSearch、useParams 才具备类型安全。
用法要点:Route.useParams/useSearch/useLoaderData 返回值已推断,无需标注;createRootRouteWithContext 是工厂函数需调用两次;context 经 beforeLoad 注入后在 loader 中自动可用。使用 from 对 hooks 与 Link 做收窄可避免返回全部路由的联合类型,提升检查速度与精度;跨路由共享组件用 strict:false;代码分割文件用 getRouteApi 而非直接导入 Route。
类型性能优化:大型路由树用对象语法 addChildren;loader 不返回未消费的复杂推断类型时可改为 void;Link 选项对象用 as const satisfies LinkProps 而非直接标注 LinkProps。自定义泛型组件可用 ValidateLinkOptions、ValidateNavigateOptions、ValidateRedirectOptions,或用 render props 在调用处收窄。渲染优化可配合 select 细粒度订阅与 structuralSharing(仅限 JSON 兼容数据)。
限制与注意:不要混用 Next.js 或 react-router-dom 的导入与文件结构;类型检查通过不等于运行时数据契约成立,字段增改需沿存储、校验、处理器输出、loader 数据到 UI 追踪,并补充运行时断言与构建测试。该页面为技能说明文档,许可与收费方式暂未提供。