useQuery

useQuery

const {
    data,
    dataUpdatedAt,
    error,
    errorUpdatedAt,
    failureCount,
    failureReason,
    fetchStatus,
    isError,
    isFetched,
    isFetchedAfterMount,
    isFetching,
    isInitialLoading,
    isLoading,
    isLoadingError,
    isPaused,
    isPending,
    isPlaceholderData,
    isRefetchError,
    isRefetching,
    isStale,
    isSuccess,
    refetch,
    status,
} = useQuery(
    {
        queryKey,
        queryFn,
        gcTime,
        enabled,
        networkMode,
        initialData,
        initialDataUpdatedAt,
        meta,
        notifyOnChangeProps,
        placeholderData,
        queryKeyHashFn,
        refetchInterval,
        refetchIntervalInBackground,
        refetchOnMount,
        refetchOnReconnect,
        refetchOnWindowFocus,
        retry,
        retryOnMount,
        retryDelay,
        select,
        staleTime,
        structuralSharing,
        throwOnError,
    },
    queryClient
);

配置项

• queryKey:unknown []

  • Require

  • 用于唯一标识查询的键。这将被传递给queryFn以获取数据。

  • 请参阅查询键以获取更多信息。
  • 当queryKey更改时，查询将被重新获取。

• queryFn: (context: QueryFunctionContext) => Promise<TDate>

  • Required，

  • 用于获取数据的函数。这个函数将接收一个QueryFunctionContext对象，其中包含有关查询的信息。

  • 必须返回一个Promise，该Promise将解析为查询到的数据或抛出错误。数据不能是undefined。

• enable: boolean

  • 可选，默认为true

  • 如果设置为false，则查询将不会在挂载时自动获取。如果查询已经在缓存中，则不会获取。

  • 如果设置为false，查询将不会在挂载时自动获取。如果查询已经在缓存中，则不会获取。

• networkMode: 'online' | 'always' | 'offlineFirst'

  • 可选，默认为 online，请参阅网络模式

  • online：默认值。查询将在在线时获取，但不会在离线时获取。

  • always：查询将始终获取，无论在线还是离线。

  • offlineFirst：查询将在离线时获取，但不会在在线时获取。

• retry：boolean | number | (failureCount:number, error: TError) => boolran

  • 如果为 false，则默认情况下不会重试失败的查询。

  • 如果 true，失败的查询将无限次重试。

  • 如果设置为 number，失败的查询将重试指定的次数。

  • 客户端默认为 3，服务器默认为 0

• retryOnMount：boolean

  • 如果设置为 false，如果包函错误，则不会在挂载时重试查询。默认为 true。

• retryDelay: number | (retryAttempt: number, error: TError) => number

  • 此函数接收一个retryAttempt整数和实际 Error，并返回在下一次尝试之前应用的延迟（毫秒）

  • 像attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)应用指数退避。

  • 像attempt => attempt * 1000的函数应用线性退避。

• staleTime: number | Infinity

  • 可选，默认为 0

  • 数据被认为过时后的时间（毫秒）。此值仅适用于定义它的挂钩

  • 如果设置为 Infinity，数据将永远不会被视为过气。

• gcTime: number | Infinity

  • SSR 期间默认为5 * 60 * 100（5 分钟）或 Infinity

  • 未使用/非活动缓存数据将保留在内存中的时间（毫秒）。当查询的缓存变为未使用或非活动时，该缓存数据将在此持续时间后被垃圾回收。当指定不同的垃圾回收机制时间时，将使用最长的时间。

  • 如果设置为Infinity，将禁用垃圾回收机制

• queryKeyHashFn: (queryKey: QueryKey) => string

  • 可选。如果指定，此函数将用于 queryKey 散列为字符串

• refetchInterval: number | false | ((query: Query) => number | false | undefined)

  • 可选

  • 如果设置为数字，所有查询将以毫秒为为单位以该频率连续重新获取。

  • 如果设置为函数，该函数将与查询一起执行计算频率

• refetchIntervalInBackground: boolean

  • 可选的。

  • 如果设置为true，则设置为refetchInterval 持续重新获取的查询将在其选项卡/窗口处于后台时继续重新获取

• refetchOnMount: boolean | "always" | ((query: Query) => boolean | "always")

  • 可选。默认为 true

  • 如果设置为true，则如果数据过时，查询将在挂载时重新获取。

  • 如果设置为false，查询将不会在挂载时重新获取。

  • 如果设置为"always"，查询将始终在挂载时重新获取。

  • 如果设置为函数，该函数将与查询一起执行

• refetchOnWindowFocus: boolean | "always" | ((query: Query) => boolean | "always")

  • 可选。默认值为 true

  • 如果设置为true，则如果数据过时，查询将在窗口获取焦点时执行。

  • 如果设置为false，查询将不会在窗口获取焦点时重新获取。

  • 如果设置为"always"，查询将始终在窗口获取焦点时重新获取。

  • 如果设置为函数，该函数将与查询函数一起执行

• refetchOnReconnect: boolean | "always" | ((query: Query) => boolean | "always")

  • 可选。默认为 true

  • 如果设置为true，则如果数据过时，查询将在重新连接时重新获取。

  • 如果设置为false，查询将不会在重新连接时重新获取。

  • 如果设置为"always"，查询将始终在重新连接时重新获取。

  • 如果设置为函数，该函数将与查询一起执行

• notifyOnChangeProps: string[] | "all" | (() => string[] | "all")

  • 可选

  • 如果设置，则仅当列出的属性更改时，组件才会重新渲染。例如，如果设置为['data', 'error']，组件将仅在data或error属性更改时重新渲染。

  • 如果设置为"all"，组件将选择所有属性，并且每当任何属性更改时都会重新渲染。

  • 如果设置为函数，则将执行该函数以计算属性列表。

  • 默认情况下，对属性的访问将被跟踪，并且组件只会在跟踪的属性之一更改时重新呈现。

• select: (data: TData) => unknown

  • 可选

  • 此选项可用于转换或选择查询函数返回的部分数据。它影响返回的data值，但不影响存储在查询缓存中的内容。

  • 仅当select更改或对select函数本身的引用更改时，data函数才会运行。要优化，请将函数包装在useCallback。

• initialData: TData | () => TData

  • 可选

  • 如果设置，此值将用作查询缓存的初始数据（只要尚未创建或缓存查询）

  • 如果设置为函数，该函数将在共享/根查询初始化期间被调用一次，并被期望同步返回 startalData

  • 默认情况下，初始数据被认为是陈旧的，除非设置了staleTime。

  • initialData 被持久化到缓存

• initialDataUpdatedAt: number | (() => number | undefined)

  • 可选

  • 如果设置，此值将用作上次更新initialData本身的时间（以毫秒为单位）。

• placeholderData: TData | (previousValue: TData | undefined; previousQuery: Query | undefined,) => TData

  • 可选

  • 如果设置，则此值将用作此特定查询观察者的占位符数据，而查询仍处于pending状态。

  • placeholderData是不持久化到缓存

  • 如果您为placeholderData提供了一个函数，作为第一个参数，您将收到以前监视的查询数据（如果可用），第二个参数将是完整的 previousQuery 实例。

• structuralSharing: boolean | (oldData: unknown | undefined, newData: unknown) => unknown)

  • 可选

  • 默认为true

  • 如果设置为false，查询结果之间的结构共享将被禁用。

  • 如果设置为函数，则新旧数据值将通过该函数传递，该函数应将它们组合成查询的已解析数据。这样，即使数据包含不可序列化的值，您也可以保留对旧数据的引用以提高性能。

• throwOnError: undefined | boolean | (error: TError, query: Query) => boolean

  • 默认为全局查询配置的throwOnError值，undefined

  • 把这设定为true

  • 将此设置为false以禁用suspense将错误抛出到错误边界的默认行为。

  • 如果设置为一个函数，它将传递错误和查询，它应该返回一个布尔值，指示是在错误边界显示错误（true）还是以状态返回错误（false）

• meta: Record<string, unknown>

  • 可选

  • 如果设置，则存储有关查询缓存条目的附加信息，可以根据需要使用。只要query可用，就可以访问它，它也是提供给QueryFunctionContext的queryFn的一部分。

• queryClient?: QueryClient

  • 使用它来使用自定义 QueryClient。否则，将使用最近上下文中的那个。

返回值

• status: QueryStatus

  • pending，如果没有缓存数据，也没有查询尝试完成。

  • error，如果查询尝试导致错误。相应的error属性包含从尝试获取收到的错误

  • success，如果查询收到没有错误的响应并准备好显示其数据。查询上的相应data属性是从成功获取中接收到的数据，或者如果查询的enabled属性设置为false并且尚未获取，则data是初始化时提供给查询的第一个initialData。

• isPending: boolean

  • 为方便起见，从上面的status变量派生的布尔值。

• isSuccess: boolean

  • 为方便起见，从上面的status变量派生的布尔值。

• isError: boolean

  • 为方便起见，从上面的status变量派生的布尔值。

• isLoadingError: boolean

  • 如果第一次获取时查询失败，则true。

• isRefetchError: boolean

  • 如果重新刻录时查询失败，则true。

• data: TData

  • 默认为undefined。

  • 查询的最后一个成功解析的数据。

• dataUpdatedAt: number

  • 查询最近返回status为"success"的时间戳。

• error: null | TError

  • 默认为null

  • 如果抛出错误，则查询的错误对象。

• errorUpdatedAt: number

  • 查询最近返回status为"error"的时间戳。

• isStale: boolean

  • Will be true if the data in the cache is invalidated or if the data is older than the given staleTime.

• isPlaceholderData: boolean

  • Will be true if the data shown is the placeholder data.

• isFetched: boolean

  • Will be true if the query has been fetched.

• isFetchedAfterMount: boolean

  • Will be true if the query has been fetched after the component mounted.

  • This property can be used to not show any previously cached data.

• fetchStatus: FetchStatus

  • fetching: Is true whenever the queryFn is executing, which includes initial pending as well as background refetches.

  • paused: The query wanted to fetch, but has been paused.

  • idle: The query is not fetching.

  • see Network Mode for more information.
• isFetching: boolean

  • A derived boolean from the fetchStatus variable above, provided for convenience.

• isPaused: boolean

  • A derived boolean from the fetchStatus variable above, provided for convenience.

• isRefetching: boolean

  • 是true每当背景重新蚀刻是在飞行中，这不包括初始pending

  • 与isFetching && !isPending

• isLoading: boolean

  • 当查询的第一次获取正在进行中时true

  • 与isFetching && isPending

• isInitialLoading: boolean

  • 已弃用

  • 下一个主要版本将删除isLoading的别名。

• failureCount: number

  • 查询的失败计数。

  • 每次查询失败时增加。

  • 查询成功时重置为0。

• failureReason: null | TError

  • 查询重试的失败原因。

  • 查询成功时重置为null。

• errorUpdateCount: number

  • 所有错误的总和。

• refetch: (options: { throwOnError: boolean, cancelRefetch: boolean }) => Promise

  • 手动重新获取查询的函数。

  • 如果查询错误，则只会记录错误。如果您希望抛出错误，请传递throwOnError: true选项

  • cancelRefetch?: boolean

    • 默认为 true

      • 默认情况下，当前运行的请求将在发出新请求之前被取消

    • 当设置为false时，如果已经有请求在运行，则不会进行重新蚀刻。