docs-i18n 0.8.1 → 0.8.2

package/template/content/query/ja/installation.md

@@ -0,0 +1,78 @@
+---
+title: インストール
+description: プロジェクトに TanStack Query をインストールする方法
+---
+
+# インストール
+
+TanStack Query は、サポートされている各フレームワーク向けの npm パッケージとして利用できます。
+
+## パッケージのインストール
+
+フレームワークに合わせたパッケージを選択してください：
+
+### React
+
+```bash
+npm install @tanstack/react-query
+```
+
+```bash
+pnpm add @tanstack/react-query
+```
+
+```bash
+yarn add @tanstack/react-query
+```
+
+```bash
+bun add @tanstack/react-query
+```
+
+### Vue
+
+```bash
+npm install @tanstack/vue-query
+```
+
+### Solid
+
+```bash
+npm install @tanstack/solid-query
+```
+
+### Svelte
+
+```bash
+npm install @tanstack/svelte-query
+```
+
+### Angular
+
+```bash
+npm install @tanstack/angular-query-experimental
+```
+
+## 必要要件
+
+- TypeScript 4.7+（型推論のため）
+- React 18+ / Vue 3+ / Solid 1.6+ / Svelte 4+
+
+## Devtools
+
+より良い開発体験のために、devtools のインストールもお勧めします：
+
+```bash
+npm install @tanstack/react-query-devtools
+```
+
+> [!NOTE]
+> Devtools は現在 React のみ対応しています。他のフレームワーク向けにはコミュニティ製の devtools があります。
+
+## CDN
+
+プロトタイピングには、CDN から TanStack Query を読み込めます：
+
+```html
+<script src="https://unpkg.com/@tanstack/react-query/build/umd/index.production.js"></script>
+```

package/template/content/query/ja/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戦略
+- **ウィンドウフォーカス再取得** でデータを最新に保つ
+- **ポーリング/リアルタイム** クエリ（間隔設定可能）
+- **並列・依存クエリ** で複雑なデータ要件に対応
+- **ミューテーション** — 楽観的更新をサポート
+- **ページネーション・無限スクロール** を標準サポート
+- **専用DevTools** でデバッグを支援
+
+## サポートされるフレームワーク
+
+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/guides/mutations.md

@@ -0,0 +1,126 @@
+---
+title: 变更操作
+description: 了解如何使用 TanStack Query 的变更操作创建、更新和删除数据
+---
+
+# 变更操作
+
+与查询不同，变更操作通常用于创建/更新/删除数据或执行服务端副作用。为此，TanStack Query 导出了 `useMutation` Hook。
+
+## 基本变更操作
+
+```tsx
+import { useMutation, useQueryClient } from '@tanstack/react-query'
+
+function AddTodo() {
+  const queryClient = useQueryClient()
+
+  const mutation = useMutation({
+    mutationFn: (newTodo: { title: string }) => {
+      return fetch('/api/todos', {
+        method: 'POST',
+        body: JSON.stringify(newTodo),
+        headers: { 'Content-Type': 'application/json' },
+      }).then((res) => res.json())
+    },
+    onSuccess: () => {
+      // 使待办事项列表缓存失效并重新获取
+      queryClient.invalidateQueries({ queryKey: ['todos'] })
+    },
+  })
+
+  return (
+    <button
+      onClick={() => mutation.mutate({ title: 'New Todo' })}
+      disabled={mutation.isPending}
+    >
+      {mutation.isPending ? '添加中...' : '添加待办事项'}
+    </button>
+  )
+}
+```
+
+## 变更状态
+
+在任意时刻，变更操作只能处于以下状态之一：
+
+| 状态 | 描述 |
+|---|---|
+| `isIdle` | 变更操作处于空闲或初始/重置状态 |
+| `isPending` | 变更操作正在执行 |
+| `isError` | 变更操作遇到错误 |
+| `isSuccess` | 变更操作成功，数据可用 |
+
+## 乐观更新
+
+乐观更新允许您在服务器确认变更之前更新 UI，提供更流畅的用户体验：
+
+```tsx
+const mutation = useMutation({
+  mutationFn: updateTodo,
+  onMutate: async (newTodo) => {
+    // 取消正在进行的重新获取，以避免覆盖乐观更新
+    await queryClient.cancelQueries({ queryKey: ['todos'] })
+
+    // 保存之前的值快照
+    const previousTodos = queryClient.getQueryData(['todos'])
+
+    // 乐观地更新为新值
+    queryClient.setQueryData(['todos'], (old: Todo[]) => [
+      ...old,
+      { ...newTodo, id: Date.now() },
+    ])
+
+    // 返回包含快照值的上下文对象
+    return { previousTodos }
+  },
+  onError: (_err, _newTodo, context) => {
+    // 出错时回滚到之前的值
+    queryClient.setQueryData(['todos'], context?.previousTodos)
+  },
+  onSettled: () => {
+    // 无论成功或失败都重新获取
+    queryClient.invalidateQueries({ queryKey: ['todos'] })
+  },
+})
+```
+
+> [!NOTE]
+> `onMutate` 处理函数在变更函数之前运行，并接收相同的变量。这是执行乐观更新的最佳位置。
+
+## 重试
+
+默认情况下，TanStack Query 不会重试失败的变更操作。您可以为每个变更操作单独配置：
+
+```tsx
+const mutation = useMutation({
+  mutationFn: addTodo,
+  retry: 3, // 失败的变更操作重试 3 次
+})
+```
+
+## 变更回调
+
+`useMutation` Hook 支持多个回调选项：
+
+```tsx
+useMutation({
+  mutationFn: addTodo,
+  onMutate: (variables) => {
+    // 在变更函数触发之前调用
+    // 接收变更函数将接收的相同变量
+  },
+  onError: (error, variables, context) => {
+    // 变更操作遇到错误时调用
+  },
+  onSuccess: (data, variables, context) => {
+    // 变更操作成功时调用
+  },
+  onSettled: (data, error, variables, context) => {
+    // 无论成功还是失败都会调用
+  },
+})
+```
+
+> [!WARNING]
+> `useMutation` 上的回调会在每个使用它的组件实例中触发。要确保副作用只执行一次，请使用 `mutate` 函数上的回调，或将变更操作提取到共享 Hook 中。

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 支持。