React Academy · 课时

设置 React Query 与 QueryClient

安装 TanStack Query，将应用包裹在 QueryClientProvider 中，并运行您的第一个 useQuery。

设置 React Query 与 QueryClient 是 CoddyKit 上的免费 React Academy 课时。这是第 1 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 React Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 React Academy 课程共包含 4 节课。

欢迎

在本课中，您将安装 TanStack Query，设置 QueryClient 和 QueryClientProvider，并首次运行 useQuery 从 API 获取数据。

什么是 React Query？

TanStack Query（原名 React Query）用于管理服务器状态：从远程来源获取、缓存、同步和更新数据。它替代了手动管理加载和错误状态，以及基于 useEffect 的数据获取方式。

安装

请安装核心软件包，并根据需要安装 DevTools。

npm install @tanstack/react-query
npm install @tanstack/react-query-devtools --save-dev

创建 QueryClient

创建一个 QueryClient 实例，用于保存所有缓存和配置。将它传递给包裹应用的 QueryClientProvider。

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

const queryClient = new QueryClient();

createRoot(document.getElementById('root')).render(
  <QueryClientProvider client={queryClient}>
    <App />
  </QueryClientProvider>
);

您的第一个 useQuery

使用 queryKey 数组和返回数据的 queryFn 调用 useQuery。该键会唯一标识缓存条目。

import { useQuery } from '@tanstack/react-query';

function Posts() {
  const { data, isLoading, isError } = useQuery({
    queryKey: ['posts'],
    queryFn: () => fetch('/api/posts').then(r => r.json()),
  });

  if (isLoading) return <p>Loading...</p>;
  if (isError) return <p>Error!</p>;
  return <ul>{data.map(p => <li key={p.id}>{p.title}</li>)}</ul>;
}

查询键

查询键是数组。将参数添加到键中，即可限定缓存条目的范围。键不同，缓存条目就不同。

// All posts
useQuery({ queryKey: ['posts'], queryFn: fetchPosts })

// Post with id 5
useQuery({ queryKey: ['posts', 5], queryFn: () => fetchPost(5) })

// Posts filtered by category
useQuery({ queryKey: ['posts', { category: 'react' }], queryFn: /* ... */ })

查询状态

useQuery 会返回多个状态属性：`isLoading`、`isFetching`、`isError`、`isSuccess`、`data` 和 `error`。即使是在后台重新获取数据时，`isFetching` 也为 true；只有首次加载时，`isLoading` 才为 true。

React Query DevTools

在开发环境中将 ReactQueryDevtools 添加到应用，即可查看所有缓存条目、它们的状态以及上次获取数据的时间。这对调试非常有帮助。

import { ReactQueryDevtools } from '@tanstack/react-query-devtools';

<QueryClientProvider client={queryClient}>
  <App />
  <ReactQueryDevtools initialIsOpen={false} />
</QueryClientProvider>

默认配置

在 QueryClient 上配置全局默认值：staleTime、gcTime（垃圾回收）、重试次数和 refetchOnWindowFocus。

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 60_000,     // data is fresh for 60s
      retry: 2,              // retry failed queries twice
      refetchOnWindowFocus: false,
    },
  },
});

自动重新获取

默认情况下，在以下情况发生时，React Query 会重新获取已过期的数据：窗口重新获得焦点、组件重新挂载，以及网络重新连接。您可以针对每个查询分别配置这些行为。

快速检查

useQuery 中的 queryKey 数组有什么作用？

回顾

安装 @tanstack/react-query，创建 QueryClient，使用 QueryClientProvider 包裹应用，并通过 queryKey 和 queryFn 调用 useQuery。添加 DevTools 以便查看运行情况。在 QueryClient 上配置全局默认值。

接下来

下一课：**缓存、过期时间与后台重新获取**——您将配置 staleTime 和 gcTime，以控制数据何时重新获取。

常见问题解答

「设置 React Query 与 QueryClient」课时是免费的吗？

是的 — 「设置 React Query 与 QueryClient」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 React Academy 课程的其余内容，请升级到 CoddyKit PRO。 React Academy 课程共包含 4 节课。

「设置 React Query 与 QueryClient」这节课中我会学到什么？

安装 TanStack Query，将应用包裹在 QueryClientProvider 中，并运行您的第一个 useQuery。你通过在浏览器中直接运行的动手代码来练习 React Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 React Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 React Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 1 节课，共 4 节。

「设置 React Query 与 QueryClient」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 React Academy 课中编写并运行代码吗？

能。每节 React Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 React Academy