docs-i18n 0.8.1 → 0.8.3

package/template/content/query/zh-hans/guides/pagination.md

@@ -0,0 +1,98 @@
+---
+title: 分页
+description: 了解如何使用 TanStack Query 实现分页查询
+---
+
+# 分页
+
+渲染分页数据是非常常见的 UI 模式，在 TanStack Query 中，只需将页面信息包含在查询键中即可"自然生效"。
+
+## 基本分页示例
+
+```tsx
+const fetchProjects = async (page: number) => {
+  const res = await fetch(`/api/projects?page=${page}`)
+  return res.json()
+}
+
+function Projects() {
+  const [page, setPage] = React.useState(1)
+
+  const { data, isPreviousData, isLoading } = useQuery({
+    queryKey: ['projects', page],
+    queryFn: () => fetchProjects(page),
+    placeholderData: keepPreviousData,
+  })
+
+  return (
+    <div>
+      {isLoading ? (
+        <div>加载中...</div>
+      ) : (
+        <>
+          {data.projects.map((project) => (
+            <p key={project.id}>{project.name}</p>
+          ))}
+        </>
+      )}
+      <div className="flex gap-2">
+        <button
+          onClick={() => setPage((old) => Math.max(old - 1, 1))}
+          disabled={page === 1}
+        >
+          上一页
+        </button>
+        <span>第 {page} 页</span>
+        <button
+          onClick={() => {
+            if (!isPreviousData && data.hasMore) {
+              setPage((old) => old + 1)
+            }
+          }}
+          disabled={isPreviousData || !data?.hasMore}
+        >
+          下一页
+        </button>
+      </div>
+    </>
+  )
+}
+```
+
+## 使用 `keepPreviousData`
+
+`keepPreviousData` 选项对流畅的分页体验至关重要。启用后，即使查询键发生变化，在请求新数据时仍可使用上次成功获取的数据。
+
+> [!NOTE]
+> `keepPreviousData` 在 v5 中从 `previousData` 重命名而来。如果您是从 v4 迁移，请相应更新代码。
+
+## 预取下一页
+
+为了更流畅的用户体验，可以在用户导航之前预取下一页：
+
+```tsx
+const queryClient = useQueryClient()
+
+React.useEffect(() => {
+  if (data?.hasMore) {
+    queryClient.prefetchQuery({
+      queryKey: ['projects', page + 1],
+      queryFn: () => fetchProjects(page + 1),
+    })
+  }
+}, [data, page, queryClient])
+```
+
+## 无限查询
+
+对于"加载更多"和无限滚动模式，TanStack Query 提供了 `useInfiniteQuery` Hook。详情请参阅[无限查询指南](/en/query/docs/guides/infinite-queries)。
+
+| 功能 | `useQuery` + 分页 | `useInfiniteQuery` |
+|---|---|---|
+| 页面导航 | 上一页/下一页按钮 | 加载更多/无限滚动 |
+| 数据结构 | 单页 | 累积页面 |
+| 内存使用 | 较低（一页） | 较高（所有已加载页面） |
+| URL 同步 | 简单 | 更复杂 |
+
+> [!WARNING]
+> 不要将 `useInfiniteQuery` 用于传统的页面导航。它专为"加载更多"模式设计，即之前加载的数据保持可见。

package/template/content/query/zh-hans/guides/queries.md

@@ -0,0 +1,120 @@
+---
+title: 查询
+description: 了解 TanStack Query 中查询的工作原理
+---
+
+# 查询
+
+查询是对异步数据源的声明式依赖，与唯一键绑定。查询可以与任何基于 Promise 的方法（包括 GET 和 POST 方法）一起使用，从服务器获取数据。
+
+## 查询基础
+
+要在组件中订阅查询，至少需要传入一个唯一键和一个返回 Promise 的函数来调用查询 Hook：
+
+<!-- ::start:react -->
+
+```tsx
+import { useQuery } from '@tanstack/react-query'
+
+function Example() {
+  const { data, isLoading, error } = useQuery({
+    queryKey: ['todos'],
+    queryFn: fetchTodoList,
+  })
+}
+```
+
+<!-- ::end:react -->
+
+<!-- ::start:vue -->
+
+```vue
+<script setup>
+import { useQuery } from '@tanstack/vue-query'
+
+const { data, isLoading, error } = useQuery({
+  queryKey: ['todos'],
+  queryFn: fetchTodoList,
+})
+</script>
+```
+
+<!-- ::end:vue -->
+
+<!-- ::start:solid -->
+
+```tsx
+import { createQuery } from '@tanstack/solid-query'
+
+function Example() {
+  const query = createQuery(() => ({
+    queryKey: ['todos'],
+    queryFn: fetchTodoList,
+  }))
+}
+```
+
+<!-- ::end:solid -->
+
+## 查询键
+
+查询键用于唯一标识一个查询。它可以是一个简单的字符串，也可以是包含多个字符串和嵌套对象的数组：
+
+```ts
+// 简单字符串键
+useQuery({ queryKey: ['todos'], ... })
+
+// 带变量的键
+useQuery({ queryKey: ['todo', todoId], ... })
+
+// 带对象的键
+useQuery({ queryKey: ['todos', { type: 'done', page: 1 }], ... })
+```
+
+## 查询函数
+
+查询函数可以是任何返回 Promise 的函数。返回的 Promise 应该解析数据或抛出错误：
+
+```ts
+const { data } = useQuery({
+  queryKey: ['todos'],
+  queryFn: async () => {
+    const response = await fetch('/api/todos')
+    if (!response.ok) {
+      throw new Error('Network response was not ok')
+    }
+    return response.json()
+  },
+})
+```
+
+## 查询状态
+
+在任意时刻，查询可以处于以下状态之一：
+
+- **`isPending`** — 查询尚无数据
+- **`isError`** — 查询遇到错误
+- **`isSuccess`** — 查询成功，数据可用
+
+```tsx
+function Todos() {
+  const { data, isPending, isError, error } = useQuery({
+    queryKey: ['todos'],
+    queryFn: fetchTodos,
+  })
+
+  if (isPending) return <span>加载中...</span>
+  if (isError) return <span>错误：{error.message}</span>
+
+  return (
+    <ul>
+      {data.map((todo) => (
+        <li key={todo.id}>{todo.title}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
+> [!NOTE]
+> 在 TanStack Query v5 中，`isLoading` 已被重命名为 `isPending` 以保持一致性。

package/template/content/query/zh-hans/installation.md

@@ -0,0 +1,95 @@
+---
+title: 安装
+description: 了解如何在项目中安装和配置 TanStack Query
+---
+
+# 安装
+
+TanStack Query 兼容 React v18+，支持 ReactDOM 和 React Native。
+
+## 安装依赖
+
+使用你喜欢的包管理器安装：
+
+```bash
+npm install @tanstack/react-query
+```
+
+或者使用其他包管理器：
+
+```bash
+# pnpm
+pnpm add @tanstack/react-query
+
+# yarn
+yarn add @tanstack/react-query
+
+# bun
+bun add @tanstack/react-query
+```
+
+## 配置 QueryClient
+
+在应用根组件中创建一个 `QueryClient` 实例，并用 `QueryClientProvider` 包裹应用：
+
+```tsx
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+
+// 创建一个 QueryClient 实例
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 1000 * 60, // 1 分钟
+      retry: 1,
+    },
+  },
+})
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <YourApp />
+    </QueryClientProvider>
+  )
+}
+```
+
+## 安装开发工具
+
+开发工具有助于调试和可视化查询状态。推荐在开发环境中使用：
+
+```bash
+npm install @tanstack/react-query-devtools
+```
+
+```tsx
+import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <YourApp />
+      <ReactQueryDevtools initialIsOpen={false} />
+    </QueryClientProvider>
+  )
+}
+```
+
+> [!NOTE]
+> 开发工具仅在开发环境中加载。在生产构建中会自动被 tree-shake 移除，不会增加生产包体积。
+
+## TypeScript 配置
+
+TanStack Query 使用 TypeScript 编写，开箱即用提供完整的类型支持。建议使用 TypeScript 4.7 或更高版本以获得最佳体验。
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "moduleResolution": "bundler"
+  }
+}
+```
+
+> [!WARNING]
+> 请确保你的 TypeScript 版本不低于 4.7。旧版本可能无法正确推断某些类型。

package/template/content/query/zh-hans/overview.md

@@ -0,0 +1,72 @@
+---
+title: TanStack Query 概述
+description: 强大的异步状态管理，支持 TS/JS、React、Vue、Solid、Svelte 和 Angular
+---
+
+# TanStack Query
+
+TanStack Query（前身为 React Query）让您在 Web 应用中轻松实现数据获取、缓存、同步和更新服务器状态。
+
+## 动机
+
+大多数核心 Web 框架并没有提供一套统一的数据获取或更新方案。开发者往往需要自己构建元框架来封装数据获取的逻辑，或者自行发明数据获取方式。这通常意味着将基于组件的状态和副作用拼凑在一起，或者使用通用的状态管理库来存储和提供异步数据。
+
+## 特性
+
+- **传输/协议/后端无关** 的数据获取（REST、GraphQL、Promise 等皆可！）
+- **自动缓存** 并支持请求去重
+- **自动重新获取** 采用 stale-while-revalidate 策略
+- **窗口焦点重新获取** 保持数据最新
+- **轮询/实时** 查询，可配置间隔
+- **并行和依赖查询** 满足复杂数据需求
+- **变更操作** 支持乐观更新
+- **分页和无限滚动** 开箱即用
+- **专用开发工具** 便于调试
+
+## 支持的框架
+
+TanStack Query 支持以下框架：
+
+```ts
+// React
+import { useQuery } from '@tanstack/react-query'
+
+// Vue
+import { useQuery } from '@tanstack/vue-query'
+
+// Solid
+import { createQuery } from '@tanstack/solid-query'
+
+// Svelte
+import { createQuery } from '@tanstack/svelte-query'
+
+// Angular
+import { injectQuery } from '@tanstack/angular-query-experimental'
+```
+
+## 快速示例
+
+```tsx
+import { useQuery } from '@tanstack/react-query'
+
+function App() {
+  const { data, isLoading, error } = useQuery({
+    queryKey: ['todos'],
+    queryFn: () => fetch('/api/todos').then(res => res.json()),
+  })
+
+  if (isLoading) return <div>加载中...</div>
+  if (error) return <div>错误：{error.message}</div>
+
+  return (
+    <ul>
+      {data.map(todo => (
+        <li key={todo.id}>{todo.title}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
+> [!NOTE]
+> TanStack Query v5 是最新版本，包含大量改进，例如简化的 API 和更好的 TypeScript 支持。

package/template/content/query/zh-hans/quick-start.md

@@ -0,0 +1,108 @@
+---
+title: 快速开始
+description: 几分钟内上手 TanStack Query
+---
+
+# 快速开始
+
+本指南将帮助您尽快上手 TanStack Query。
+
+## 设置 Provider
+
+使用 `QueryClientProvider` 包裹您的应用，并传入一个 `QueryClient` 实例：
+
+```tsx
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+
+const queryClient = new QueryClient()
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <MyApp />
+    </QueryClientProvider>
+  )
+}
+```
+
+## 您的第一个查询
+
+使用 `useQuery` Hook 来获取数据：
+
+```tsx
+import { useQuery } from '@tanstack/react-query'
+
+function Todos() {
+  const { data, isLoading, error } = useQuery({
+    queryKey: ['todos'],
+    queryFn: fetchTodos,
+  })
+
+  if (isLoading) return <span>加载中...</span>
+  if (error) return <span>错误：{error.message}</span>
+
+  return (
+    <ul>
+      {data.map((todo) => (
+        <li key={todo.id}>{todo.title}</li>
+      ))}
+    </ul>
+  )
+}
+
+async function fetchTodos() {
+  const res = await fetch('https://jsonplaceholder.typicode.com/todos')
+  if (!res.ok) throw new Error('Failed to fetch')
+  return res.json()
+}
+```
+
+## 您的第一个变更操作
+
+使用 `useMutation` 来创建、更新或删除数据：
+
+```tsx
+import { useMutation, useQueryClient } from '@tanstack/react-query'
+
+function AddTodo() {
+  const queryClient = useQueryClient()
+
+  const mutation = useMutation({
+    mutationFn: (newTodo: { title: string }) =>
+      fetch('/api/todos', {
+        method: 'POST',
+        body: JSON.stringify(newTodo),
+      }).then((res) => res.json()),
+    onSuccess: () => {
+      // 使缓存失效并重新获取
+      queryClient.invalidateQueries({ queryKey: ['todos'] })
+    },
+  })
+
+  return (
+    <button onClick={() => mutation.mutate({ title: 'New Todo' })}>
+      添加待办事项
+    </button>
+  )
+}
+```
+
+## 添加开发工具
+
+添加 React Query Devtools 进行调试：
+
+```tsx
+import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <MyApp />
+      <ReactQueryDevtools initialIsOpen={false} />
+    </QueryClientProvider>
+  )
+}
+```
+
+> [!NOTE]
+> 开发工具在生产构建中会自动排除。

package/template/content/router/docs.config.json

@@ -0,0 +1,18 @@
+{
+  "sections": [
+    {
+      "label": "Getting Started",
+      "children": [
+        { "label": "Overview", "to": "overview" },
+        { "label": "Installation", "to": "installation" },
+        { "label": "Quick Start", "to": "quick-start" }
+      ]
+    },
+    {
+      "label": "Guides",
+      "children": [
+        { "label": "Routing Concepts", "to": "guides/routing-concepts" }
+      ]
+    }
+  ]
+}

package/template/content/router/en/guides/routing-concepts.md

@@ -0,0 +1,131 @@
+---
+title: Routing Concepts
+description: Understand the core routing concepts in TanStack Router
+---
+
+# Routing Concepts
+
+TanStack Router is built on a few core concepts that make it powerful and flexible. Understanding these concepts will help you build better applications.
+
+## Route Trees
+
+TanStack Router uses a route tree to define the structure of your application. Routes can be nested to create layouts and hierarchies:
+
+```tsx
+import { createRootRoute, createRoute, createRouter } from '@tanstack/react-router'
+
+const rootRoute = createRootRoute({
+  component: RootLayout,
+})
+
+const indexRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: '/',
+  component: HomePage,
+})
+
+const aboutRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: '/about',
+  component: AboutPage,
+})
+
+const routeTree = rootRoute.addChildren([indexRoute, aboutRoute])
+
+const router = createRouter({ routeTree })
+```
+
+## File-Based Routing
+
+For most applications, TanStack Router supports file-based routing through a plugin. Your file structure becomes your route structure:
+
+```
+app/
+  routes/
+    __root.tsx        → Root layout
+    index.tsx         → /
+    about.tsx         → /about
+    posts.tsx         → /posts (layout)
+    posts.index.tsx   → /posts/
+    posts.$postId.tsx → /posts/:postId
+```
+
+> [!NOTE]
+> File-based routing is powered by the `@tanstack/router-plugin` package, which generates the route tree automatically at build time.
+
+## Search Params
+
+TanStack Router treats search params as first-class citizens with full type safety:
+
+```tsx
+const productsRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: '/products',
+  validateSearch: (search: Record<string, unknown>) => {
+    return {
+      page: Number(search.page) || 1,
+      filter: (search.filter as string) || '',
+      sort: (search.sort as 'asc' | 'desc') || 'asc',
+    }
+  },
+  component: ProductsPage,
+})
+
+function ProductsPage() {
+  const { page, filter, sort } = productsRoute.useSearch()
+
+  return (
+    <div>
+      <p>Page: {page}, Filter: {filter}, Sort: {sort}</p>
+    </div>
+  )
+}
+```
+
+## Data Loading
+
+Routes can define loaders that fetch data before the route renders:
+
+```tsx
+const postRoute = createRoute({
+  getParentRoute: () => postsRoute,
+  path: '$postId',
+  loader: async ({ params }) => {
+    const post = await fetchPost(params.postId)
+    return { post }
+  },
+  component: PostPage,
+})
+
+function PostPage() {
+  const { post } = postRoute.useLoaderData()
+  return <article>{post.title}</article>
+}
+```
+
+| Feature | Description |
+|---|---|
+| Route Trees | Hierarchical route definitions with parent-child relationships |
+| File-Based Routing | Automatic route generation from file system |
+| Search Params | Type-safe URL search parameters with validation |
+| Data Loading | Pre-fetch data before route renders |
+| Pending States | Built-in loading indicators during navigation |
+| Error Boundaries | Per-route error handling |
+
+## Path Params
+
+Dynamic segments in the path are prefixed with `$`:
+
+```tsx
+// Single param
+'/posts/$postId'
+
+// Multiple params
+'/users/$userId/posts/$postId'
+
+// Splat/catch-all
+'/files/$'
+```
+
+> [!WARNING]
+> Unlike some other routers, TanStack Router does not use `:` for dynamic segments. Always use `$` as the prefix.

package/template/content/router/en/installation.md

@@ -0,0 +1,57 @@
+---
+title: Installation
+description: How to install TanStack Router in your project
+---
+
+# Installation
+
+## Install the Package
+
+```bash
+npm install @tanstack/react-router
+```
+
+```bash
+pnpm add @tanstack/react-router
+```
+
+```bash
+yarn add @tanstack/react-router
+```
+
+```bash
+bun add @tanstack/react-router
+```
+
+## Vite Plugin (Recommended)
+
+For the best experience with file-based routing and automatic route generation, install the Vite plugin:
+
+```bash
+npm install -D @tanstack/router-plugin
+```
+
+Then add it to your `vite.config.ts`:
+
+```ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import { TanStackRouterVite } from '@tanstack/router-plugin/vite'
+
+export default defineConfig({
+  plugins: [TanStackRouterVite(), react()],
+})
+```
+
+## Devtools
+
+Install the devtools for route debugging:
+
+```bash
+npm install @tanstack/router-devtools
+```
+
+## Requirements
+
+- React 18+
+- TypeScript 5.0+ (strongly recommended)