浏览文档目录
第 05 课 · 导航与数据

让 Loader 预热 Query 缓存

Router 决定何时导航,Query 决定数据如何缓存;用同一份 queryOptions 把两者接起来。

TanStack Query核心22 分钟REV 02Markdown .md
完成后你将能够

能在 Loader 中预取关键数据,并在组件中读取同一个缓存条目。

01

只定义一次查询契约

queryOptions 把 queryKey 与 queryFn 放在一起,并保留类型推断。Loader 和组件必须引用同一个契约,避免同一资源被两个不相关的 key 重复请求。

src/features/issues/queries.tsts
import { queryOptions } from '@tanstack/react-query'

export const issuesQuery = queryOptions({
  queryKey: ['issues'],
  queryFn: () => getIssues(),
  staleTime: 30_000,
})
02

导航前填充,渲染时读取

ensureQueryData 会在缓存可用时复用它,否则等待请求完成。useSuspenseQuery 随后读取同一个条目;SSR 集成负责把服务端缓存脱水并在客户端恢复。

src/routes/issues/index.tsxtsx
import { useSuspenseQuery } from '@tanstack/react-query'
import { createFileRoute } from '@tanstack/react-router'
import { issuesQuery } from '~/features/issues/queries'

export const Route = createFileRoute('/issues/')({
  loader: ({ context }) =>
    context.queryClient.ensureQueryData(issuesQuery),
  component: IssuesPage,
})

function IssuesPage() {
  const { data } = useSuspenseQuery(issuesQuery)
  return <p>{data.length} issues</p>
}
实践

把本课变成可验证的能力

完成检查点

路由 Loader 使用同一份 queryOptions 预取数据,组件读取时不会再创建第二套 Query Key。

动手练习

为 Issue 详情建立 queryOptions 工厂,并在详情路由 Loader 中通过 issueId 预热缓存。

验证方法

首次导航只应出现一次详情请求;返回后再次进入时应遵循配置的新鲜度策略。

常见错误
  • Loader 与组件使用结构不同的 Query Key。
  • 在 Loader 中等待不影响首屏的独立请求。
SOURCE REFERENCES · CHECKED 2026-08-03https://tanstack.com/router/latest/docs/integrations/query