hydration

dehydrate 会创建一个缓存的冻结表示，之后可以用 HydrationBoundary 或 hydrate 来进行水合。这对于将预取的查询从服务器传递到客户端，或将查询持久化到 localStorage 或其他持久化位置非常有用。默认情况下，它只包含当前成功的查询。

import { dehydrate } from '@tanstack/react-query'

const dehydratedState = dehydrate(queryClient, {
  shouldDehydrateQuery,
  shouldDehydrateMutation,
})

import { dehydrate } from '@tanstack/react-query'

const dehydratedState = dehydrate(queryClient, {
  shouldDehydrateQuery,
  shouldDehydrateMutation,
})

选项

• client: QueryClient
  • 必需
  • 需要脱水的 queryClient
• options: DehydrateOptions
  • Optional (可选)
  • shouldDehydrateMutation: (mutation: Mutation) => boolean
    • Optional (可选)
    • 是否脱变异。
    • 该函数会为缓存中的每个变异调用一次
      • 返回 true 以将此变异包含在脱水中，否则返回 false
    • 默认只包含暂停的变异
    • 如果您希望在保留默认行为的同时扩展该函数，请在 return 语句中导入并执行 defaultShouldDehydrateMutation
  • shouldDehydrateQuery: (query: Query) => boolean
    • Optional (可选)
    • 是否脱查询。
    • 该函数会为缓存中的每个查询调用一次
      • 返回 true 以将此查询包含在脱水中，否则返回 false
    • 默认只包含成功的查询
    • 如果您希望在保留默认行为的同时扩展该函数，请在 return 语句中导入并执行 defaultShouldDehydrateQuery
  • serializeData?: (data: any) => any 在脱水期间转换（序列化）数据的函数。
  • shouldRedactErrors?: (error: unknown) => boolean
    • Optional (可选)
    • 是否在脱水期间隐藏服务器错误。
    • 该函数会为缓存中的每个错误调用一次
      • 返回 true 以隐藏此错误，否则返回 false
    • 默认隐藏所有错误

Returns (返回)

• dehydratedState: DehydratedState
  • 这包含了之后水合 queryClient 所需的一切
  • 您不应依赖此响应的确切格式，它不是公共 API 的一部分，并且随时可能更改
  • 此结果不是序列化形式，如果需要，您需要自己进行序列化

某些存储系统（例如浏览器 Web Storage API）要求值是 JSON 可序列化的。如果您需要脱水那些不能自动序列化为 JSON 的值（例如 Error 或 undefined），您必须自己进行序列化。由于默认只包含成功的查询，要也包含 Errors，您必须提供 shouldDehydrateQuery，例如：

// server
const state = dehydrate(client, { shouldDehydrateQuery: () => true }) // to also include Errors
const serializedState = mySerialize(state) // transform Error instances to objects

// client
const state = myDeserialize(serializedState) // transform objects back to Error instances
hydrate(client, state)

// server
const state = dehydrate(client, { shouldDehydrateQuery: () => true }) // to also include Errors
const serializedState = mySerialize(state) // transform Error instances to objects

// client
const state = myDeserialize(serializedState) // transform objects back to Error instances
hydrate(client, state)

hydrate 将先前脱水状态添加到 cache 中。

import { hydrate } from '@tanstack/react-query'

hydrate(queryClient, dehydratedState, options)

import { hydrate } from '@tanstack/react-query'

hydrate(queryClient, dehydratedState, options)

选项

• client: QueryClient
  • 必需
  • 将状态水合到其中的 queryClient
• dehydratedState: DehydratedState
  • 必需
  • 要水合到客户端的状态
• options: HydrateOptions
  • Optional (可选)
  • defaultOptions: DefaultOptions
    • Optional (可选)
    • mutations: MutationOptions 为水合的变异使用的默认变异选项。
    • queries: QueryOptions 为水合的查询使用的默认查询选项。
    • deserializeData?: (data: any) => any 在数据放入缓存之前转换（反序列化）数据的函数。
  • queryClient?: QueryClient
    • 使用此选项可以使用自定义 QueryClient。否则，将使用最近上下文中的 QueryClient。

如果您尝试水合的查询已存在于 queryCache 中，hydrate 将仅在数据比缓存中现有数据更新时才覆盖它们。否则，它将不会应用。

HydrationBoundary 会将先前脱水状态添加到 queryClient 中，该状态由 useQueryClient() 返回。如果客户端已包含数据，则新查询将根据更新时间戳智能合并。

import { HydrationBoundary } from '@tanstack/react-query'

function App() {
  return <HydrationBoundary state={dehydratedState}>...</HydrationBoundary>
}

import { HydrationBoundary } from '@tanstack/react-query'

function App() {
  return <HydrationBoundary state={dehydratedState}>...</HydrationBoundary>
}

注意：HydrationBoundary 只能脱水 queries。

选项

• state: DehydratedState
  • 要水合的状态
• options: HydrateOptions
  • Optional (可选)
  • defaultOptions: QueryOptions
    • 为水合的查询使用的默认查询选项。
  • queryClient?: QueryClient
    • 使用此选项可以使用自定义 QueryClient。否则，将使用最近上下文中的 QueryClient。