Skip to main content

QueryClient

QueryClient可用于与缓存交互：

import { QueryClient } from "@tanstack/react-query";

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: Infinity,
    },
  },
});

await queryClient.prefetchQuery({ queryKey: ["posts"], queryFn: fetchPosts });

其可用的方法有：

  • queryClient.fetchQuery
  • queryClient.fetchInfiniteQuery
  • queryClient.prefetchQuery
  • queryClient.prefetchInfiniteQuery
  • queryClient.getQueryData
  • queryClient.ensureQueryData
  • queryClient.getQueriesData
  • queryClient.setQueryData
  • queryClient.getQueryState
  • queryClient.setQueriesData
  • queryClient.invalidateQueries
  • queryClient.refetchQueries
  • queryClient.cancelQueries
  • queryClient.removeQueries
  • queryClient.resetQueries
  • queryClient.isFetching
  • queryClient.isMutating
  • queryClient.getLogger
  • queryClient.getDefaultOptions
  • queryClient.setDefaultOptions
  • queryClient.getQueryDefaults
  • queryClient.setQueryDefaults
  • queryClient.getMutationDefaults
  • queryClient.setMutationDefaults
  • queryClient.getQueryCache
  • queryClient.getMutationCache
  • queryClient.clear
  • queryClient.resumePausedMutations

Options(选项)​

  • queryCache?: QueryCache

    • 可选的
    • 此客户端连接到的查询缓存

  • mutationCache?: MutationCache

    • 可选的
    • 此客户端连接到的突变缓存

  • logger?: Logger

    • 可选的
    • 此客户端用于记录调试信息、警告和错误的日志记录器。如果未设置，console 则为默认记录器

  • defaultOptions?: DefaultOptions

    • 可选的
    • 使用此 queryClient 为所有查询和突变定义默认值

queryClient.fetchQuery​

fetchQuery是一种异步方法，可用于获取和缓存查询。它将使用数据解析或抛出错误。如果您只想获取查询而不需要结果，请使用prefetchQuery方法。 如果查询存在，并且数据没有失效或比给定的 staleTime 早，则将返回缓存中的数据。否则它将尝试获取最新数据。

使用 fetchQuery 和 setQueryData 之间的区别在于，fetchQuery 是异步的，并将确保在获取数据时，不会使用相同查询的 useQuery 实例创建重复的查询请求。

try {
  const data = await queryClient.fetchQuery(queryKey, queryFn);
} catch (error) {
  console.log(error);
}

指定一个 staleTime，仅在数据超过一定时间时获取：

try {
  const data = await queryClient.fetchQuery(queryKey, queryFn, {
    staleTime: 10000,
  });
} catch (error) {
  console.log(error);
}

Options​

fetchQuery的选项与useQuery的选项完全相同，除了以下内容：enabled, refetchInterval, refetchIntervalInBackground, refetchOnWindowFocus, refetchOnReconnect, notifyOnChangeProps, onSuccess, onError, onSettled, useErrorBoundary, select, suspense, keepPreviousData, placeholderData;  严格适用于 useQuery 和 useInfiniteQuery。您可以查看源代码以获得更清晰的信息。

queryClient.fetchInfiniteQuery​

fetchInfiniteQuery类似于fetchQuery，但可用于获取和缓存无限查询

try {
  const data = await queryClient.fetchInfiniteQuery(queryKey, queryFn);
  console.log(data.pages);
} catch (error) {
  console.log(error);
}

Options​

fetchInfiniteQuery的选项与fetchQuery的选项完全相同。

Returns​

  • Promise<InfiniteData<TData>>

queryClient.prefetchQuery​

prefetchQuery是一种异步方法，可用于在需要查询或与useQuery好友一起呈现之前预取查询。该方法的工作原理与fetchQuery相同，只是它不会抛出或返回任何数据。

await queryClient.prefetchQuery(queryKey, queryFn);

您甚至可以在配置中将其与默认的 queryFn 一起使用！

await queryClient.prefetchQuery(queryKey);

Options​

prefetchQuery的选项与fetchQuery的选项完全相同。

Returns​

  • Promise<void>
    • 返回一个 promise，如果不需要获取，它将立即解析，或者在执行查询之后解析。它不会返回任何数据或抛出任何错误

queryClient.prefetchInfiniteQuery​

prefetchInfiniteQuery类似于prefetchQuery，但可用于预取和缓存无限查询。

await queryClient.prefetchInfiniteQuery(queryKey, queryFn);

Options​

prefetchInfiniteQuery的选项与fetchQuery的选项完全相同。

Returns​

  • Promise<void>
    • 返回一个 promise，如果不需要获取，它将立即解析，或者在执行查询之后解析。它不会返回任何数据或抛出任何错误

queryClient.getQueryData​

getQueryData是一个同步函数，可用于获取现有查询的缓存数据。如果查询不存在，将返回undefined。

const data = queryClient.getQueryData(queryKey);

Options​

Returns​

data: TData | undefined

  • 缓存查询的数据，如果查询不存在,则为undefined。

queryClient.getQueriesData​

Options​

queryKey: QueryKey查询键 | filters: QueryFilters：查询过滤器。

Returns​

  • [queryKey:QueryKey, data:TData | unknown][]
    • 匹配查询键的元组数组，如果没有匹配项，则为[]。元组是查询键及其关联数据
info

因为每个元组中返回的数据可以是不同的结构（例如：使用过滤器返回“active”查询可以返回不同的数据类型），TData 泛型默认为 unknown。如果您为 TData 提供更具体的类型，则假定您确定每个元组的数据条目都是相同的类型。 这种区别对于 ts 开发者来说更“方便”，因为他们知道将返回哪个结构。

queryClient.setQueryData​

setQueryData是一个同步函数，可用于立即更新查询的缓存数据。如果查询不存在，则会创建它。如果在默认的 5 分钟 cacheTime 中查询钩子没有使用该查询，则该查询将被垃圾回收。要一次更新多个查询并部分匹配查询键，您需要 queryClient.setQueriesData 代替。

使用 setQueryData 和 fetchQuery 之间的区别在于，setQueryData 是同步的，假设您已经同步地拥有可用的数据。如果您需要异步获取数据，建议您重新获取查询键或用于 fetchQuery 处理异步获取。

queryClient.setQueryData(queryKey, updater);
  • queryKey: QueryKey: 查询键

Options​

  • updater: TData | (oldData: TData | undefined) => TData | undefined
    • 如果传入的是非函数，数据会更新到此值
    • 如果传递了一个函数，它将接收旧数据值并希望返回一个新数据值

使用更新器值​

setQueryData(queryKey, newData);

如果值为 undefined，则不更新查询数据。

使用更新器函数​

为了语法方便，您还可以传递一个更新器函数，该函数接收当前数据值并返回新值：

setQueryData(queryKey, (oldData) => newData);

如果更新器函数返回undefined，则查询数据不会被更新。如果更新器函数接收到 undefined 作为输入，您可以返回 undefined 以退出更新，因此不会创建新的缓存条目。

queryClient.getQueryState​

getQueryState是一个同步函数，可用于获取现有查询的状态。如果查询不存在，将返回undefined。

Options​

queryKey?: QueryKey：查询键。 filters? : QueryFilters：查询过滤器

queryClient.setQueriesData​

setQueriesData是一个同步函数，可以通过使用过滤函数或者部分匹配查询键来立即更新多个查询的缓存数据。只有与传递的 queryKey 或 queryFilter 匹配的查询才会被更新——不会创建新的缓存条目。在底层，setQueryData每个查询都会调用。

Options​

  • queryKey: QueryKey查询键 | filters: QueryFilters：查询过滤器。

    • 如果将 queryKey 作为第一个参数传递，则部分匹配此参数的 queryKey 将被更新
    • 如果传递了一个过滤器，则匹配过滤器的 queryKeys 将被更新

  • updater: TData | (oldData: TData | undefined) => TData的选项与fetchQuery的选项完全相同。

    • setQueryData 更新函数或新数据，将为每个匹配的 queryKey 调用

queryClient.invalidateQueries​

该invalidateQueries方法可用于根据查询键或查询的任何其他功能可访问的属性/状态使缓存中的单个或多个查询无效和重新获取。默认情况下，所有匹配的查询都会立即标记为无效，并且在后台重新获取活动查询。

  • 如果您不想重新获取活动查询，而只是将其标记为无效，则可以使用该 refetchType: 'none'选项。
  • 如果您还希望重新获取非活动查询，请使用该 refetchTye: 'all'选项
await queryClient.invalidateQueries(
  ["posts"],
  {
    exact,
    refetchType: "active",
  },
  { throwOnError, cancelRefetch }
);

Options​

prefetchQuery的选项与fetchQuery的选项完全相同。

Returns​

  • queryKey?: QueryKey:查询键

  • filters?: QueryFilters: 查询过滤器

    • refetchType?: 'active' | 'inactive' | 'all' | 'none'

      • 默认为'active'
      • 当设置为active时，只有匹配 refetch 谓词并且通过useQuery和朋友主动呈现的查询才会在后台重新获取
      • 当设置为inactive时，只有匹配 refetch 谓词并且没有通过useQuery和朋友主动呈现的查询才会在后台重新获取
      • 当设置为all时，所有匹配 refetch 谓词的查询都将在后台重新获取
      • 当设置为none时，不会重新获取任何查询，并且与重新获取谓词匹配的查询将仅标记为无效

    • refetchPage: (page: TData, index: number, allPages: TData[]) => boolean

      • 仅适用于无限查询
      • 使用此函数可指定应重新获取哪些页面

  • options?: InvalidateOptions

    • throwOnError?: boolean
      • 当设置为true时，如果任何查询重新获取任务失败，此方法将抛出
    • cancelRefetch?: boolean
      • 默认为true
        • 默认情况下，当前正在运行的请求将在发出新请求之前被取消
      • 设置为false时，如果已经有请求在运行，则不会重新获取

queryClient.refetchQueries​

该refetchQueries方法可用于根据特定条件重新获取查询。

// refetch all queries:
await queryClient.refetchQueries();
// refetch all stale queries:
await queryClient.refetchQueries({ stale: true });
// refetch all active queries partially matching a query key:
await queryClient.refetchQueries(["posts"], { type: "active" });
// refetch all active queries exactly matching a query key:
await queryClient.refetchQueries(["posts", 1], { type: "active", exact: true });

Options​

  • queryKey?: QueryKey: 查询键
  • filters?: QueryFilters: 查询键
    • refetchPage: (page: TData, index: number, allPages: TData[]) => boolean
      • 仅适用于无限查询
      • 使用此函数指定应重新获取哪些页面
  • options?: RefetchOptions:
    • throwOnError?: boolean
      • 当设置为true时，如果任何查询重新获取任务失败，此方法将抛出
    • cancelRefetch?: boolean
      • 默认为true
        • 默认情况下，当前正在运行的请求将在发出新请求之前被取消
      • 设置为 false 时，如果已经有请求在运行，则不会重新获取

Returns​

此函数返回一个promise，该promise将在所有查询完成重新获取时解析。默认情况下，如果这些查询中的任何一个重新获取失败，它都不会抛出错误，但这可以通过将throwOnError选项设置为true

##############

queryClient.cancelQueries​

该cancelQueries方法可用于根据查询键或查询的任何其他功能可访问的属性/状态取消传出查询。 这在执行乐观更新时最有用，因为您可能需要取消任何传出查询重新获取，以便它们在解析时不会破坏您的乐观更新。

await queryClient.cancelQueries(["posts"], { exact: true });

Options​

  • queryKey?: QueryKey: 查询键
  • filters?: QueryFilters: 查询过滤器

Returns​

此方法不返回任何内容

queryClient.removeQueries​

queryClient.removeQueries(queryKey, { exact: true });

该removeQueries方法可用于根据查询键或查询的任何其他功能可访问的属性/状态从缓存中删除查询。

Options​

  • queryKey?: QueryKey: 查询键
  • filters?: QueryFilters: 查询过滤器

Returns​

此方法不返回任何内容

queryClient.resetQueries​

该resetQueries方法可用于根据查询键或查询的任何其他功能可访问的属性/状态将缓存中的查询重置为其初始状态。 这将通知订阅者——不像 clear 会删除所有订阅者——并将查询重置为其预加载状态——不像invalidateQueries。如果查询有initialData，则查询的数据将被重置为initialData。如果查询处于活动状态，它将被重新获取。

queryClient.resetQueries(queryKey, { exact: true });

Options​

  • queryKey?: QueryKey: 查询键
  • filters?: QueryFilters: 查询过滤器
    • refetchPage: (page: TData, index: number, allPages: TData[]) => boolean
      • 仅适用于无限查询
      • 使用此函数指定应重新获取哪些页面
  • options?: ResetOptions:
    • throwOnError?: boolean
      • 当设置为true时，如果任何查询重新获取任务失败，此方法将抛出
    • cancelRefetch?: boolean
      • 默认为true
        • 默认情况下，当前正在运行的请求将在发出新请求之前被取消
      • 设置为 false 时，如果已经有请求在运行，则不会重新获取

Returns​

此方法返回一个 promise，该 promise 在重新获取所有活动查询时解析。

queryClient.isFetching​

此isFetching方法返回一个integer表示缓存中当前正在获取多少查询（如果有）的值（包括后台获取、加载新页面或加载更多无限查询结果）。

if (queryClient.isFetching()) {
  console.log("At least one query is fetching!");
}

React Query 还导出了一个方便的useIsFetching钩子，它可以让您在组件中订阅此状态，而无需创建对查询缓存的手动订阅。

Options​

  • queryKey?: QueryKey: 查询键
  • filters?: QueryFilters: 查询过滤器

Returns​

此方法返回获取查询的数量。

queryClient.isMutating​

此isMutating方法返回一个integer表示缓存中当前正在获取多少突变（如果有）的值。

if (queryClient.isMutating()) {
  console.log("At least one mutation is fetching!");
}

React Query 还导出了一个方便的useIsMutating钩子，它可以让您在组件中订阅此状态，而无需创建对突变缓存的手动订阅。

Options​

filters: MutationFilters: 变异过滤器

Returns​

此方法返回获取突变的数量

queryClient.getLogger​

const logger = queryClient.getLogger();

queryClient.getDefaultOptions​

该getDefaultOptions方法返回在创建客户端时或使用时设置的setDefaultOptions默认选项。

const defaultOptions = queryClient.getDefaultOptions();

queryClient.setDefaultOptions​

该setDefaultOptions方法可用于动态设置此 queryClient 的默认选项。先前定义的默认选项将被覆盖。

queryClient.setDefaultOptions({
  queries: {
    staleTime: Infinity,
  },
});

queryClient.getQueryDefaults​

该getQueryDefaults方法返回为特定查询设置的默认选项：

const defaultOptions = queryClient.getQueryDefaults(["posts"]);

请注意，如果多个查询默认值与给定查询键匹配，则返回第一个匹配的。 这可能会导致意外行为。见 setQueryDefaults。

queryClient.setQueryDefaults​

setQueryDefaults可用于为特定查询设置默认选项：

queryClient.setQueryDefaults(["posts"], { queryFn: fetchPosts });

function Component() {
  const { data } = useQuery(["posts"]);
}

Options​

  • queryKey: QueryKey: 查询键
  • options: QueryOptions

    如 getQueryDefaults 中所述，查询默认值的注册顺序确实很重要。由于第一个匹配的默认值由 返回 getQueryDefaults，因此注册应按以下顺序进行：从最不通用的键到最通用的键。这样，在特定键的情况下，第一个匹配的将是预期的。

queryClient.getMutationDefaults​

该getMutationDefaults方法返回为特定突变设置的默认选项：

const defaultOptions = queryClient.getMutationDefaults(["addPost"]);

queryClient.setMutationDefaults​

setMutationDefaults可用于为特定突变设置默认选项：

queryClient.setMutationDefaults(["addPost"], { mutationFn: addPost });

function Component() {
  const { data } = useMutation(["addPost"]);
}

Options​

  • mutationKey: string | unknown[]
  • options: MutationOptions

    与setQueryDefaults类似，这里的注册顺序很重要

queryClient.getQueryCache​

该 getQueryCache 方法返回此客户端连接到的查询缓存。

const queryCache = queryClient.getQueryCache();

queryClient.getMutationCache​

该 getMutationCache 方法返回此客户端连接到的突变缓存。

const mutationCache = queryClient.getMutationCache();

queryClient.clear​

该 clear 方法清除所有连接的缓存。

queryClient.clear();

queryClient.resumePausedMutations​

可用于恢复因没有网络连接而暂停的突变。

queryClient.resumePausedMutations();