TanStack Router 基础教程：React 框架下的路由实践-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_01173/article/details/148416202

TanStack Router 基础教程：React 框架下的路由实践

router TanStack/router: TanStack Router（前身为React Training的React Router）是一个强大的客户端路由库，适用于构建单页应用（SPA）。它使得React应用能够根据URL的变化来更新视图，实现页面间的无刷新跳转。项目地址: https://gitcode.com/gh_mirrors/ro/router

前言

在现代前端开发中，路由管理是构建单页应用(SPA)的核心环节。TanStack Router 作为一款强大的路由解决方案，为开发者提供了类型安全、高效灵活的路由管理能力。本文将深入浅出地介绍 TanStack Router 在 React 框架中的基础使用方法。

核心概念

1. 路由架构基础

TanStack Router 的核心思想是将整个应用的路由结构抽象为一棵路由树。这棵树的每个节点代表一个路由，包含路径、组件、加载器等配置信息。

// 创建路由实例的基本示例
import { createRouter } from '@tanstack/react-router'
import { routeTree } from './routeTree.gen'

const router = createRouter({
  routeTree,
  scrollRestoration: true, // 启用滚动位置恢复
})

2. 路由生成机制

TanStack Router 采用代码生成的方式创建路由树。开发者在定义路由后，系统会自动生成 routeTree.gen.ts 文件，其中包含完整的路由类型定义，确保整个应用的类型安全。

项目结构解析

1. 服务端入口 (SSR)

对于需要服务端渲染的应用，ssr.tsx 文件是核心入口：

import { createStartHandler } from '@tanstack/react-start/server'
import { createRouter } from './router'

export default createStartHandler({
  createRouter,
  // 其他配置...
})

关键点：

每个请求都会创建新的路由实例
支持流式渲染(Streaming)
可自定义渲染处理器

2. 客户端入口

客户端入口负责将服务端渲染的静态内容"激活"为交互式应用：

import { hydrateRoot } from 'react-dom/client'
import { StartClient } from '@tanstack/react-start'

hydrateRoot(document, <StartClient router={router} />)

3. 应用根组件

__root.tsx 作为应用的根路由，包裹所有其他路由：

export const Route = createRootRoute({
  component: () => (
    <html>
      <head>
        <HeadContent /> {/* 自动注入头部内容 */}
      </head>
      <body>
        <Outlet /> {/* 子路由渲染位置 */}
        <Scripts /> {/* 自动注入客户端脚本 */}
      </body>
    </html>
  )
})

路由定义与使用

1. 基础路由定义

// 定义首页路由
export const Route = createFileRoute('/')({
  component: Home,
  loader: () => fetchData(), // 数据预加载
})

function Home() {
  const data = Route.useLoaderData() // 获取预加载数据
  return <div>{data}</div>
}

2. 导航功能

TanStack Router 提供多种导航方式：

// 使用 Link 组件
<Link to="/about">关于我们</Link>

// 使用编程式导航
const navigate = useNavigate()
navigate({ to: '/about' })

高级功能

1. 服务端函数(RPC)

TanStack 提供了独特的服务端函数机制，实现前后端无缝调用：

// 定义服务端函数
const getData = createServerFn('GET')
  .validator(z.string()) // 使用 Zod 验证输入
  .handler(({ data }) => fetchFromDB(data))

// 客户端调用
const result = await getData({ data: '123' })

2. 数据加载策略

路由级数据加载支持多种高级特性：

export const Route = createFileRoute('/posts')({
  loader: async ({ params }) => {
    // 支持并行加载
    const [posts, comments] = await Promise.all([
      fetchPosts(params.id),
      fetchComments(params.id)
    ])
    return { posts, comments }
  },
  // 数据过期时间配置
  staleTime: 1000 * 60 * 5 // 5分钟
})

3. 数据变更与缓存失效

const updatePost = createServerFn('POST')
  .handler(async ({ data }) => {
    // 更新逻辑...
  })

function useUpdatePost() {
  const router = useRouter()
  const update = useServerFunction(updatePost)
  
  return async (post) => {
    await update({ data: post })
    router.invalidate() // 使缓存失效
  }
}