hydration

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

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
  • 必需
  • 应该被 dehydrate 的 queryClient
• options: DehydrateOptions
  • 可选
  • shouldDehydrateMutation: (mutation: Mutation) => boolean
    • 可选
    • 是否 dehydrate mutations。
    • 该函数为缓存中的每个 mutation 调用
      • 返回 true 以将此 mutation 包含在 dehydration 中，否则返回 false
    • 默认为仅包含暂停的 mutations
    • 如果您想扩展该函数，同时保留默认行为，请导入并执行 defaultShouldDehydrateMutation 作为 return 语句的一部分
  • shouldDehydrateQuery: (query: Query) => boolean
    • 可选
    • 是否 dehydrate queries。
    • 该函数为缓存中的每个 query 调用
      • 返回 true 以将此 query 包含在 dehydration 中，否则返回 false
    • 默认为仅包含成功的 queries
    • 如果您想扩展该函数，同时保留默认行为，请导入并执行 defaultShouldDehydrateQuery 作为 return 语句的一部分
  • serializeData?: (data: any) => any 用于在 dehydration 期间转换（序列化）数据的函数。
  • shouldRedactErrors?: (error: unknown) => boolean
    • 可选
    • 是否在 dehydration 期间从服务器编辑错误。
    • 该函数为缓存中的每个错误调用
      • 返回 true 以编辑此错误，否则返回 false
    • 默认为编辑所有错误

返回值

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

某些存储系统（例如浏览器 Web Storage API）要求值是 JSON 可序列化的。如果您需要 dehydrate 无法自动序列化为 JSON 的值（例如 Error 或 undefined），则必须自己序列化它们。由于默认情况下仅包含成功的 query，因此要也包含 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 将先前 dehydrate 的状态添加到 cache 中。

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

hydrate(queryClient, dehydratedState, options)

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

hydrate(queryClient, dehydratedState, options)

选项

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

如果您尝试 hydrate 的 query 已经存在于 queryCache 中，则仅当数据比缓存中存在的数据更新时，hydrate 才会覆盖它们。否则，它将不会被应用。

HydrationBoundary 将先前 dehydrate 的状态添加到 useQueryClient() 将返回的 queryClient 中。如果客户端已包含数据，则将根据更新时间戳智能合并新 query。

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>
}

注意：只有 queries 可以通过 HydrationBoundary 进行 dehydrate。

选项

• state: DehydratedState
  • 要 hydrate 的状态
• options: HydrateOptions
  • 可选
  • defaultOptions: QueryOptions
    • 用于 hydrate 的 queries 的默认 query 选项。
  • queryClient?: QueryClient,
    • 使用此项以使用自定义 QueryClient。否则，将使用来自最近上下文的 QueryClient。