experimental_createQueryPersister

安装

此实用程序作为一个单独的包提供，可通过 '@tanstack/query-persist-client-core' 导入。

bash

npm install @tanstack/query-persist-client-core

npm install @tanstack/query-persist-client-core

或者

bash

pnpm add @tanstack/query-persist-client-core

pnpm add @tanstack/query-persist-client-core

或者

bash

yarn add @tanstack/query-persist-client-core

yarn add @tanstack/query-persist-client-core

或者

bash

bun add @tanstack/query-persist-client-core

bun add @tanstack/query-persist-client-core

用法

导入 experimental_createQueryPersister 函数
创建一个新的 experimental_createQueryPersister
- 您可以向其传递任何符合 AsyncStorage 或 Storage 接口的 storage - 下面的示例使用来自 React Native 的 async-storage。
将该 persister 作为选项传递给您的查询。这可以通过将其传递给 QueryClient 的 defaultOptions 或任何 useQuery 钩子实例来完成。
- 如果您将此 persister 作为 defaultOptions 传递，则所有查询都将持久化到提供的 storage 中。您还可以通过传递 filters 来进一步缩小范围。与 persistClient 插件相反，这不会将整个查询客户端持久化为单个项目，而是分别持久化每个查询。查询哈希用作键。
- 如果您将此 persister 提供给单个 useQuery 钩子，则仅持久化此查询。

这样，您无需存储整个 QueryClient，而是可以选择在应用程序中值得持久化的内容。每个查询都是延迟恢复（首次使用查询时）和持久化（每次运行 queryFn 后），因此不需要对其进行节流。恢复查询后也会遵守 staleTime，因此如果数据被认为是 stale，则在恢复后会立即重新获取。如果数据是 fresh，则不会运行 queryFn。

从内存中进行垃圾回收查询不会影响持久化数据。这意味着查询可以在内存中保留较短的时间以提高内存效率。如果下次使用它们，它们将再次从持久存储中恢复。

tsx

import { QueryClient } from '@tanstack/vue-query'
import { experimental_createQueryPersister } from '@tanstack/query-persist-client-core'

const persister = experimental_createQueryPersister({
  storage: AsyncStorage,
  maxAge: 1000 * 60 * 60 * 12, // 12 小时
})

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      gcTime: 1000 * 30, // 30 秒
      persister: persister.persisterFn,
    },
  },
})

import { QueryClient } from '@tanstack/vue-query'
import { experimental_createQueryPersister } from '@tanstack/query-persist-client-core'

const persister = experimental_createQueryPersister({
  storage: AsyncStorage,
  maxAge: 1000 * 60 * 60 * 12, // 12 小时
})

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      gcTime: 1000 * 30, // 30 秒
      persister: persister.persisterFn,
    },
  },
})

调整后的默认值

createPersister 插件在技术上包装了 queryFn，因此如果 queryFn 不运行，它就不会恢复。这样，它充当查询和网络之间的缓存层。因此，当使用持久化程序时，networkMode 默认为 'offlineFirst'，以便即使在没有网络连接的情况下也可以从持久存储中恢复。

API

tsx

experimental_createQueryPersister(options: StoragePersisterOptions)

experimental_createQueryPersister(options: StoragePersisterOptions)

选项

tsx

export interface StoragePersisterOptions {
  /** 用于从缓存中设置和检索项目的存储客户端。
   * 对于 SSR，请传入 `undefined`。
   */
  storage: AsyncStorage | Storage | undefined | null
  /**
   * 如何将数据序列化到存储。
   * @default `JSON.stringify`
   */
  serialize?: (persistedQuery: PersistedQuery) => string
  /**
   * 如何从存储中反序列化数据。
   * @default `JSON.parse`
   */
  deserialize?: (cachedString: string) => PersistedQuery
  /**
   * 一个唯一字符串，可用于强制使现有缓存失效，
   * 如果它们不共享相同的 buster 字符串
   */
  buster?: string
  /**
   * 缓存的最大允许存在时间（以毫秒为单位）。
   * 如果发现持久化缓存早于此
   * 时间，则将其丢弃
   * @default 24 小时
   */
  maxAge?: number
  /**
   * 用于存储键的前缀。
   * 存储键是前缀和查询哈希的组合，形式为 `prefix-queryHash`。
   */
  prefix?: string
  /**
   * 用于缩小应持久化的查询范围的过滤器。
   */
  filters?: QueryFilters
}

interface AsyncStorage {
  getItem: (key: string) => Promise<string | undefined | null>
  setItem: (key: string, value: string) => Promise<unknown>
  removeItem: (key: string) => Promise<void>
}

export interface StoragePersisterOptions {
  /** 用于从缓存中设置和检索项目的存储客户端。
   * 对于 SSR，请传入 `undefined`。
   */
  storage: AsyncStorage | Storage | undefined | null
  /**
   * 如何将数据序列化到存储。
   * @default `JSON.stringify`
   */
  serialize?: (persistedQuery: PersistedQuery) => string
  /**
   * 如何从存储中反序列化数据。
   * @default `JSON.parse`
   */
  deserialize?: (cachedString: string) => PersistedQuery
  /**
   * 一个唯一字符串，可用于强制使现有缓存失效，
   * 如果它们不共享相同的 buster 字符串
   */
  buster?: string
  /**
   * 缓存的最大允许存在时间（以毫秒为单位）。
   * 如果发现持久化缓存早于此
   * 时间，则将其丢弃
   * @default 24 小时
   */
  maxAge?: number
  /**
   * 用于存储键的前缀。
   * 存储键是前缀和查询哈希的组合，形式为 `prefix-queryHash`。
   */
  prefix?: string
  /**
   * 用于缩小应持久化的查询范围的过滤器。
   */
  filters?: QueryFilters
}

interface AsyncStorage {
  getItem: (key: string) => Promise<string | undefined | null>
  setItem: (key: string, value: string) => Promise<unknown>
  removeItem: (key: string) => Promise<void>
}

默认选项是：

tsx

{
  prefix = 'tanstack-query',
  maxAge = 1000 * 60 * 60 * 24,
  serialize = JSON.stringify,
  deserialize = JSON.parse,
}

{
  prefix = 'tanstack-query',
  maxAge = 1000 * 60 * 60 * 24,
  serialize = JSON.stringify,
  deserialize = JSON.parse,
}