# TanStack 中文文档

> 面向初学者与 AI Agent 的原创 TanStack 双轨知识索引。

需要完整解释时选择 Learn；需要直接执行的工程契约时选择 Agent。每次只获取最相关的单篇 Markdown。

## Learn：完整解释

- [TanStack 不是一个框架](/zh-cn/learn/ecosystem-map.md): 先别急着安装依赖。用一张地图理解 Start、Router 和 Query 如何各司其职。
- [创建第一个 Start 应用](/zh-cn/learn/first-start-app.md): 使用官方 CLI 创建最小项目，认识路由树、根文档和开发服务器。
- [用文件组成路由树](/zh-cn/learn/file-routes.md): 创建 Issue 列表和详情页，理解文件名、路径参数和类型推断如何连在一起。
- [把筛选条件放进 URL](/zh-cn/learn/url-state.md): 用经过验证的 Search Params 实现可分享、可刷新、有类型的 Issue 筛选。
- [让 Loader 预热 Query 缓存](/zh-cn/learn/loader-query-cache.md): Router 决定何时导航，Query 决定数据如何缓存；用同一份 queryOptions 把两者接起来。
- [从 Server Function 写回缓存](/zh-cn/learn/mutations.md): 验证网络边界上的输入，通过 Mutation 表达写入状态，再用服务端响应不可变地更新 Query 缓存。
- [把错误关在正确的路由里](/zh-cn/learn/error-boundaries.md): 用全局默认错误界面兜底，用 route errorComponent 隔离局部数据或渲染失败。
- [把外部入口放进 Server Route](/zh-cn/learn/server-routes.md): 区分应用内部 RPC 与公开 HTTP 端点，并用原生 Response 明确表达状态码、正文和缓存策略。
- [用 Router Context 传递依赖](/zh-cn/learn/route-context.md): 在根路由声明类型化依赖，再通过 beforeLoad 为一棵子路由追加经过推导的上下文。
- [先定义数据何时算新鲜](/zh-cn/learn/query-freshness.md): 分清 staleTime 与 gcTime，用共享 queryOptions 把查询键、请求函数和时间策略放在一起。
- [用 Middleware 组合请求边界](/zh-cn/learn/start-middleware.md): 区分请求中间件与 Server Function 中间件，并用 next() 组合日志、上下文和安全检查。
- [在离开脏表单前阻止导航](/zh-cn/learn/navigation-blocking.md): 用 useBlocker 同时处理路由内导航与浏览器卸载，并为自定义确认界面建立明确状态。
- [让 Query 取消真正传到网络层](/zh-cn/learn/query-cancellation.md): 消费 queryFn 提供的 AbortSignal，让失效的 fetch 停止并理解取消后的缓存状态。
- [在加载子路由前确认身份](/zh-cn/learn/authenticated-routes.md): 用类型化 Router Context 和 pathless layout 的 beforeLoad 保护一组页面，同时保留正确的登录回跳地址。
- [让无限列表保持有界和可恢复](/zh-cn/learn/infinite-queries.md): 用 initialPageParam、游标和 maxPages 建立明确的翻页契约，同时保持 pages 与 pageParams 的结构一致。
- [在请求之间隔离并流式恢复 Query](/zh-cn/learn/ssr-query-streaming.md): 用 Router SSR Query 集成自动完成脱水、恢复和流式传输，并为每个服务端请求创建独立缓存。
- [让乐观更新可以安全回滚](/zh-cn/learn/optimistic-updates.md): 先选择 UI 级临时结果或缓存级更新，再用取消、快照、回滚和重新验证处理失败与并发。
- [把 Issue 数据组织成无头表格](/zh-cn/learn/headless-issue-table.md): 用类型化列定义、核心行模型和 flexRender 连接数据与语义化 table 标记，同时保留完整的样式控制权。
- [让字段、校验与提交共享同一类型](/zh-cn/learn/typed-issue-form.md): 用 useForm、Field 与 Subscribe 建立受控表单，把校验时机、错误显示和异步提交状态写成显式契约。

## Agent：执行契约

### TanStack Start

- [创建只在服务端执行的函数](/zh-cn/agents/start/server-function.md): 使用 createServerFn 定义同源、类型安全的服务端 RPC。
- [创建外部可调用的 Server Route](/zh-cn/agents/start/server-route.md): 为第三方调用方建立原生 HTTP 端点，并显式返回状态、缓存和安全响应。
- [建立 Start Middleware 执行链](/zh-cn/agents/start/middleware-chain.md): 明确请求级与函数级作用域，通过 next() 组合上下文，并保留认证和 CSRF 边界。

### TanStack Router

- [创建带路径参数的文件路由](/zh-cn/agents/router/file-route.md): 在 React 应用中创建 /posts/$postId，并从路由实例读取类型安全的 postId。
- [验证分页与筛选参数](/zh-cn/agents/router/validated-search.md): 将不可信的 URL 搜索参数转换为稳定、有类型的路由输入。
- [隔离路由 Loader 与渲染错误](/zh-cn/agents/router/route-error-boundary.md): 为全局 Router 设置默认错误组件，并在需要独立恢复的路由上覆盖 errorComponent。
- [建立类型化 Router Context](/zh-cn/agents/router/typed-router-context.md): 在根路由声明依赖，并通过 beforeLoad 为子树追加可推导的派生上下文。
- [保护脏表单的离页导航](/zh-cn/agents/router/navigation-blocker.md): 用 useBlocker 的 resolver 状态实现可访问的离页确认，并按脏状态注册 beforeunload。
- [用 beforeLoad 保护路由子树](/zh-cn/agents/router/auth-before-load.md): 在 pathless layout 中读取类型化认证 Context，阻止未登录用户加载子路由，并保留经过约束的回跳 URL。

### TanStack Query

- [Router Loader 还是 Query？](/zh-cn/agents/query/router-loader-or-query.md): 根据导航关键性和数据生命周期选择 Loader、Query 或两者组合。
- [在路由 Loader 中预取 Query](/zh-cn/agents/query/loader-prefetch.md): 为 SSR 创建请求级 QueryClient，并让 Loader 与 useSuspenseQuery 使用相同 queryOptions。
- [用 Mutation 响应更新缓存](/zh-cn/agents/query/mutation-cache-update.md): 当写入响应包含完整实体时用 setQueryData；无法推导正确缓存时改用 invalidateQueries。
- [定义 Query 新鲜度契约](/zh-cn/agents/query/freshness-policy.md): 根据数据变化频率设置 staleTime，并独立决定 inactive 缓存的 gcTime。
- [消费 Query 的 AbortSignal](/zh-cn/agents/query/abort-signal.md): 将 queryFn signal 传入底层请求，使取消停止 I/O，并保留明确的缓存回滚语义。
- [建立有界的游标 Infinite Query](/zh-cn/agents/query/infinite-cursor.md): 用一份 queryKey 管理整个列表，让服务端游标驱动 pageParam，并用 maxPages 控制缓存与重取成本。
- [配置 Query SSR 与流式恢复](/zh-cn/agents/query/ssr-streaming.md): 为每个 SSR 请求创建 QueryClient，通过官方 Router 集成脱水与恢复，并明确阻塞和流式查询。
- [实现可回滚的乐观更新](/zh-cn/agents/query/optimistic-rollback.md): 取消冲突重取、保存缓存快照、不可变写入草稿，并在失败时回滚、完成时重新验证。

### TanStack Table

- [协调服务端表格的排序与分页状态](/zh-cn/agents/table/server-grid-state.md): 让 Table 管视图状态、Query 管远程数据，并用 manualSorting、manualPagination 与 rowCount 避免只处理当前页。

### TanStack Form

- [为字段异步校验建立安全边界](/zh-cn/agents/form/async-validation.md): 先同步过滤无效输入，再用内置 debounce 执行异步校验，并把提前反馈与最终服务端验证明确分开。

## 机器可读索引

- [Agent catalog JSON](/agents/catalog.json)
- [Ecosystem catalog JSON](/ecosystem/catalog.json)
- [Content manifest JSON](/content/manifest.json)
- [Agent search JSON](/agents/search.json?locale=zh-cn&q=search-params)
- [Knowledge graph JSON](/agents/graph.json?locale=zh-cn)