TanStack Query 配置选项详解
TanStack Query (以前称为 React Query) 是一个用于获取、缓存、同步和更新服务器状态的强大的数据同步库。它简化了在 React 应用中管理异步操作的复杂性，并提供了许多配置选项，可以根据具体需求微调其行为。本文将深入探讨 TanStack Query 的各种配置选项，帮助你充分利用其强大的功能。
全局配置 (queryClient)
在使用 TanStack Query 时，通常会创建一个 QueryClient 实例，并使用 QueryClientProvider 将其提供给你的 React 组件树。QueryClient 构造函数接受一个配置对象，可以用来设置全局默认行为。
“`typescript
import { QueryClient } from ‘@tanstack/react-query’;
const queryClient = new QueryClient({
defaultOptions: {
queries: {
// … query options
},
mutations: {
// … mutation options
}
}
});
“`
defaultOptions.queries
这是配置查询默认行为的核心部分。以下是一些常用的配置选项：
cacheTime: 查询结果在缓存中保留的时间 (毫秒)。默认为 5 分钟 (300000 毫秒)。设置为Infinity永久缓存，直到手动失效。staleTime: 查询结果在被视为“过期”之前保持“新鲜”的时间 (毫秒)。默认为 0，这意味着查询结果一旦获取就会立即变为“过期”，下次使用时将重新获取。refetchOnWindowFocus: 当窗口重新获得焦点时是否重新获取数据。默认为true。refetchOnReconnect: 当网络重新连接时是否重新获取数据。默认为true。refetchInterval: 定期重新获取数据的间隔时间 (毫秒)。设置为 0 或false禁用定期重新获取。refetchIntervalInBackground: 当窗口失去焦点时是否继续定期重新获取数据。默认为false。retry: 出现错误时重试的次数。可以设置为数字或函数，返回重试次数或false以停止重试。retryDelay: 每次重试之间的延迟时间 (毫秒)。可以设置为数字或函数，返回延迟时间。keepPreviousData: 在重新获取数据时是否保留之前的数据。默认为false。select: 用于转换查询结果的函数。这允许你在将数据传递给组件之前修改或过滤数据。queryFn: 执行实际数据获取的函数。它接收一个QueryFunctionContext对象作为参数，并返回一个 Promise。enabled: 控制查询是否自动执行。默认为true。设置为false将禁用查询，直到手动调用refetch。placeholderData: 在查询数据可用之前显示的占位符数据。initialData: 查询的初始数据。这对于服务器端渲染或预取数据非常有用。suspense: 启用 suspense 模式。useErrorBoundary: 启用错误边界。onError: 查询出错时的回调函数。onSuccess: 查询成功时的回调函数。onSettled: 查询完成（无论成功或失败）时的回调函数。
defaultOptions.mutations
用于配置 mutation 的默认行为。以下是一些常用的配置选项：
mutationFn: 执行 mutation 的函数。它接收 mutation 的参数，并返回一个 Promise。onError: mutation 出错时的回调函数。onSuccess: mutation 成功时的回调函数。onSettled: mutation 完成（无论成功或失败）时的回调函数。retry: 出现错误时重试的次数。retryDelay: 每次重试之间的延迟时间。mutationKey: mutation 的唯一标识符。
使用 useQuery 和 useMutation 时的配置选项
除了全局配置外，你还可以通过 useQuery 和 useMutation 钩子的第二个参数来覆盖全局配置。
“`typescript
import { useQuery } from ‘@tanstack/react-query’;
const { data, isLoading } = useQuery([‘todos’], fetchTodos, {
staleTime: Infinity, // 覆盖全局 staleTime
enabled: false // 覆盖全局 enabled
});
import { useMutation } from ‘@tanstack/react-query’;
const mutation = useMutation(addTodo, {
onSuccess: () => {
queryClient.invalidateQueries(‘todos’); // mutation 成功后使 todos 查询失效
},
});
“`
其他配置选项:
queryClient.setQueryDefaults: 可以为特定查询键设置默认选项。queryClient.setMutationDefaults: 可以为特定 mutation 键设置默认选项。queryClient.prefetchQuery: 预取查询数据。queryClient.invalidateQueries: 使查询失效并重新获取数据。queryClient.resetQueries: 重置查询缓存。queryClient.cancelQueries: 取消进行中的查询。
构建自定义 hooks
利用 TanStack Query 的配置选项，我们可以构建自定义 hooks 来封装常用的数据获取逻辑，提高代码复用性。
“`typescript
import { useQuery } from ‘@tanstack/react-query’;
function useTodos() {
return useQuery([‘todos’], fetchTodos, {
staleTime: Infinity
});
}
“`
最佳实践:
- 根据具体需求调整
staleTime和cacheTime，以平衡数据新鲜度和性能。 - 使用
enabled选项控制查询的执行时机。 - 使用
select选项转换查询结果，避免在组件中进行不必要的数据处理. - 利用
queryClient提供的方法管理查询缓存。 - 构建自定义 hooks 封装常用的数据获取逻辑。
通过灵活运用 TanStack Query 的各种配置选项，可以极大地简化数据管理的复杂性，提高应用的性能和用户体验。 理解这些选项，并根据实际情况进行配置，是充分利用 TanStack Query 的关键。 希望本文的详细解释能够帮助你更好地掌握 TanStack Query，并在你的 React 应用中发挥其强大的作用。