persistQueryClient

这是一组用于与“持久化器”交互的实用程序，用于保存您的 queryClient 以供以后使用。不同的持久化器可用于将您的客户端和缓存存储到许多不同的存储层。

工作原理

重要提示 - 为了使持久化正常工作，您可能需要传递 QueryClient 一个 gcTime 值，以在水合期间覆盖默认值（如上所示）。

如果在创建 QueryClient 实例时未设置，则水合的默认值为 300000（5 分钟），并且存储的缓存将在不活动 5 分钟后被丢弃。这是默认的垃圾回收行为。

它应设置为与 persistQueryClient 的 maxAge 选项相同或更高的值。例如，如果 maxAge 为 24 小时（默认值），则 gcTime 应为 24 小时或更长。如果低于 maxAge，垃圾回收将启动并早于预期丢弃存储的缓存。

您还可以将其传递为 Infinity 以完全禁用垃圾回收行为。

由于 Javascript 的限制，允许的最大 gcTime 大约为 24 天（请参阅更多）。

tsx

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      gcTime: 1000 * 60 * 60 * 24, // 24 hours
    },
  },
})

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      gcTime: 1000 * 60 * 60 * 24, // 24 hours
    },
  },
})

缓存失效

有时您可能会对您的应用程序或数据进行更改，这些更改会立即使任何和所有缓存数据失效。如果发生这种情况，您可以传递一个 buster 字符串选项。如果找到的缓存也没有该 buster 字符串，它将被丢弃。以下几个函数接受此选项

tsx

persistQueryClient({ queryClient, persister, buster: buildHash })
persistQueryClientSave({ queryClient, persister, buster: buildHash })
persistQueryClientRestore({ queryClient, persister, buster: buildHash })

persistQueryClient({ queryClient, persister, buster: buildHash })
persistQueryClientSave({ queryClient, persister, buster: buildHash })
persistQueryClientRestore({ queryClient, persister, buster: buildHash })

移除

如果发现数据属于以下任何一种情况

已过期（请参阅 maxAge）
已失效（请参阅 buster）
错误（例如：throws ...）
空（例如：undefined）

持久化器 removeClient() 被调用，缓存立即被丢弃。

API

persistQueryClientSave

您的查询/突变被脱水并由您提供的持久化器存储。
createSyncStoragePersister 和 createAsyncStoragePersister 限制此操作最多每 1 秒发生一次，以节省可能昂贵的写入操作。查看它们的文档以了解如何自定义它们的限制时间。

您可以使用它来显式地在您选择的时刻持久化缓存。

tsx

persistQueryClientSave({
  queryClient,
  persister,
  buster = '',
  dehydrateOptions = undefined,
})

persistQueryClientSave({
  queryClient,
  persister,
  buster = '',
  dehydrateOptions = undefined,
})

persistQueryClientSubscribe

每当您的 queryClient 的缓存更改时，都会运行 persistQueryClientSave。例如：您可能会在用户登录并选中“记住我”时启动 subscribe。

它返回一个 unsubscribe 函数，您可以使用它来停止监视；结束对持久化缓存的更新。
如果您想在 unsubscribe 后擦除持久化缓存，您可以发送一个新的 buster 到 persistQueryClientRestore，这将触发持久化器的 removeClient 函数并丢弃持久化缓存。

tsx

persistQueryClientSubscribe({
  queryClient,
  persister,
  buster = '',
  dehydrateOptions = undefined,
})

persistQueryClientSubscribe({
  queryClient,
  persister,
  buster = '',
  dehydrateOptions = undefined,
})

persistQueryClientRestore

尝试从持久化器中水合先前持久化的脱水查询/突变缓存到传递的查询客户端的查询缓存中。
如果找到的缓存比 maxAge（默认情况下为 24 小时）旧，则会被丢弃。您可以根据需要自定义此时间。

您可以使用它在您选择的时刻恢复缓存。

tsx

persistQueryClientRestore({
  queryClient,
  persister,
  maxAge = 1000 * 60 * 60 * 24, // 24 hours
  buster = '',
  hydrateOptions = undefined,
})

persistQueryClientRestore({
  queryClient,
  persister,
  maxAge = 1000 * 60 * 60 * 24, // 24 hours
  buster = '',
  hydrateOptions = undefined,
})

采取以下操作

立即恢复任何持久化缓存（参见 persistQueryClientRestore）
订阅查询缓存并返回 unsubscribe 函数（参见 persistQueryClientSubscribe）。

此功能从 3.x 版本开始保留。

tsx

persistQueryClient({
  queryClient,
  persister,
  maxAge = 1000 * 60 * 60 * 24, // 24 hours
  buster = '',
  hydrateOptions = undefined,
  dehydrateOptions = undefined,
})

persistQueryClient({
  queryClient,
  persister,
  maxAge = 1000 * 60 * 60 * 24, // 24 hours
  buster = '',
  hydrateOptions = undefined,
  dehydrateOptions = undefined,
})

选项

所有可用的选项如下

tsx

interface PersistQueryClientOptions {
  /** The QueryClient to persist */
  queryClient: QueryClient
  /** The Persister interface for storing and restoring the cache
   * to/from a persisted location */
  persister: Persister
  /** The max-allowed age of the cache in milliseconds.
   * If a persisted cache is found that is older than this
   * time, it will be **silently** discarded
   * (defaults to 24 hours) */
  maxAge?: number
  /** A unique string that can be used to forcefully
   * invalidate existing caches if they do not share the same buster string */
  buster?: string
  /** The options passed to the hydrate function
   * Not used on `persistQueryClientSave` or `persistQueryClientSubscribe` */
  hydrateOptions?: HydrateOptions
  /** The options passed to the dehydrate function
   * Not used on `persistQueryClientRestore` */
  dehydrateOptions?: DehydrateOptions
}

interface PersistQueryClientOptions {
  /** The QueryClient to persist */
  queryClient: QueryClient
  /** The Persister interface for storing and restoring the cache
   * to/from a persisted location */
  persister: Persister
  /** The max-allowed age of the cache in milliseconds.
   * If a persisted cache is found that is older than this
   * time, it will be **silently** discarded
   * (defaults to 24 hours) */
  maxAge?: number
  /** A unique string that can be used to forcefully
   * invalidate existing caches if they do not share the same buster string */
  buster?: string
  /** The options passed to the hydrate function
   * Not used on `persistQueryClientSave` or `persistQueryClientSubscribe` */
  hydrateOptions?: HydrateOptions
  /** The options passed to the dehydrate function
   * Not used on `persistQueryClientRestore` */
  dehydrateOptions?: DehydrateOptions
}

实际上有三个可用的接口

PersistedQueryClientSaveOptions 用于 persistQueryClientSave 和 persistQueryClientSubscribe（不使用 hydrateOptions）。
PersistedQueryClientRestoreOptions 用于 persistQueryClientRestore（不使用 dehydrateOptions）。
PersistQueryClientOptions 用于 persistQueryClient

与 React 一起使用

persistQueryClient 将尝试恢复缓存并自动订阅进一步的更改，从而将您的客户端同步到提供的存储。

但是，恢复是异步的，因为所有持久化器本质上都是异步的，这意味着如果您在恢复时渲染您的 App，如果查询在同时挂载和获取时，您可能会遇到竞争条件。

此外，如果您在 React 组件生命周期之外订阅更改，您将无法取消订阅

tsx

// 🚨 never unsubscribes from syncing
persistQueryClient({
  queryClient,
  persister: localStoragePersister,
})

// 🚨 happens at the same time as restoring
ReactDOM.createRoot(rootElement).render(<App />)

// 🚨 never unsubscribes from syncing
persistQueryClient({
  queryClient,
  persister: localStoragePersister,
})

// 🚨 happens at the same time as restoring
ReactDOM.createRoot(rootElement).render(<App />)

对于此用例，您可以使用 PersistQueryClientProvider。它将确保根据 React 组件生命周期正确订阅/取消订阅，并且还将确保在我们仍在恢复时查询不会开始获取。查询仍然会渲染，但它们将被置于 fetchingState: 'idle'，直到数据恢复为止。然后，除非恢复的数据足够新鲜，否则它们将重新获取，并且 initialData 也将受到尊重。它可以代替普通的 QueryClientProvider 使用

tsx

import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client'
import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      gcTime: 1000 * 60 * 60 * 24, // 24 hours
    },
  },
})

const persister = createSyncStoragePersister({
  storage: window.localStorage,
})

ReactDOM.createRoot(rootElement).render(
  <PersistQueryClientProvider
    client={queryClient}
    persistOptions={{ persister }}
  >
    <App />
  </PersistQueryClientProvider>,
)

import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client'
import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      gcTime: 1000 * 60 * 60 * 24, // 24 hours
    },
  },
})

const persister = createSyncStoragePersister({
  storage: window.localStorage,
})

ReactDOM.createRoot(rootElement).render(
  <PersistQueryClientProvider
    client={queryClient}
    persistOptions={{ persister }}
  >
    <App />
  </PersistQueryClientProvider>,
)

Props

PersistQueryClientProvider 采用与 QueryClientProvider 相同的 props，以及另外的

persistOptions: PersistQueryClientOptions
- 您可以传递给 persistQueryClient 的所有选项，减去 QueryClient 本身
onSuccess?: () => Promise<unknown> | unknown
- 可选
- 将在初始恢复完成时调用
- 可用于 resumePausedMutations
- 如果返回 Promise，它将被等待；恢复在此之前被视为正在进行中

useIsRestoring

如果您正在使用 PersistQueryClientProvider，您还可以使用 useIsRestoring hook 与之一起检查当前是否正在进行恢复。useQuery 和朋友们也在内部检查这一点，以避免恢复和挂载查询之间的竞争条件。

持久化器

持久化器接口

持久化器具有以下接口

tsx

export interface Persister {
  persistClient(persistClient: PersistedClient): Promisable<void>
  restoreClient(): Promisable<PersistedClient | undefined>
  removeClient(): Promisable<void>
}

export interface Persister {
  persistClient(persistClient: PersistedClient): Promisable<void>
  restoreClient(): Promisable<PersistedClient | undefined>
  removeClient(): Promisable<void>
}

持久化客户端条目具有以下接口

tsx

export interface PersistedClient {
  timestamp: number
  buster: string
  cacheState: any
}

export interface PersistedClient {
  timestamp: number
  buster: string
  cacheState: any
}

您可以导入这些（以构建持久化器）

tsx

import {
  PersistedClient,
  Persister,
} from '@tanstack/react-query-persist-client'

import {
  PersistedClient,
  Persister,
} from '@tanstack/react-query-persist-client'

构建持久化器

您可以随意持久化。这是一个关于如何构建 Indexed DB 持久化器的示例。与 Web Storage API 相比，Indexed DB 更快，存储超过 5MB，并且不需要序列化。这意味着它可以轻松存储 Javascript 原生类型，例如 Date 和 File。

tsx

import { get, set, del } from 'idb-keyval'
import {
  PersistedClient,
  Persister,
} from '@tanstack/react-query-persist-client'

/**
 * Creates an Indexed DB persister
 * @see https://mdn.org.cn/en-US/docs/Web/API/IndexedDB_API
 */
export function createIDBPersister(idbValidKey: IDBValidKey = 'reactQuery') {
  return {
    persistClient: async (client: PersistedClient) => {
      await set(idbValidKey, client)
    },
    restoreClient: async () => {
      return await get<PersistedClient>(idbValidKey)
    },
    removeClient: async () => {
      await del(idbValidKey)
    },
  } satisfies Persister
}

import { get, set, del } from 'idb-keyval'
import {
  PersistedClient,
  Persister,
} from '@tanstack/react-query-persist-client'

/**
 * Creates an Indexed DB persister
 * @see https://mdn.org.cn/en-US/docs/Web/API/IndexedDB_API
 */
export function createIDBPersister(idbValidKey: IDBValidKey = 'reactQuery') {
  return {
    persistClient: async (client: PersistedClient) => {
      await set(idbValidKey, client)
    },
    restoreClient: async () => {
      return await get<PersistedClient>(idbValidKey)
    },
    removeClient: async () => {
      await del(idbValidKey)
    },
  } satisfies Persister
}

persistQueryClient

构建持久化器

工作原理

缓存失效

移除

API

persistQueryClientSave

persistQueryClientSubscribe

persistQueryClientRestore

persistQueryClient

选项

与 React 一起使用

PersistQueryClientProvider

Props

useIsRestoring

持久化器

持久化器接口

构建持久化器

想要跳过文档？

想要跳过文档？