TanStackQuery v5
自动
框架
版本
菜单
入门指南
指南和概念
API 参考
ESLint
社区资源
示例
插件

createSyncStoragePersister

已弃用

此插件已弃用，并将在下一个主要版本中删除。 您可以改用 '@tanstack/query-async-storage-persister'。

安装

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

bash
npm install @tanstack/query-sync-storage-persister @tanstack/react-query-persist-client

npm install @tanstack/query-sync-storage-persister @tanstack/react-query-persist-client

或者

bash
pnpm add @tanstack/query-sync-storage-persister @tanstack/react-query-persist-client

pnpm add @tanstack/query-sync-storage-persister @tanstack/react-query-persist-client

或者

bash
yarn add @tanstack/query-sync-storage-persister @tanstack/react-query-persist-client

yarn add @tanstack/query-sync-storage-persister @tanstack/react-query-persist-client

或者

bash
bun add @tanstack/query-sync-storage-persister @tanstack/react-query-persist-client

bun add @tanstack/query-sync-storage-persister @tanstack/react-query-persist-client

用法
  • 导入 createSyncStoragePersister 函数
  • 创建一个新的 syncStoragePersister
  • 将其传递给 persistQueryClient 函数
tsx
import { persistQueryClient } 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 小时
    },
  },
})

const localStoragePersister = createSyncStoragePersister({
  storage: window.localStorage,
})
// const sessionStoragePersister = createSyncStoragePersister({ storage: window.sessionStorage })

persistQueryClient({
  queryClient,
  persister: localStoragePersister,
})

import { persistQueryClient } 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 小时
    },
  },
})

const localStoragePersister = createSyncStoragePersister({
  storage: window.localStorage,
})
// const sessionStoragePersister = createSyncStoragePersister({ storage: window.sessionStorage })

persistQueryClient({
  queryClient,
  persister: localStoragePersister,
})

重试

持久化可能会失败，例如，如果大小超过存储的可用空间。可以通过向持久化程序提供 retry 函数来优雅地处理错误。

retry 函数接收它尝试保存的 persistedClient，以及 error 和 errorCount 作为输入。它应该返回一个新的 PersistedClient，然后它会再次尝试持久化。如果返回 undefined，则不会再尝试持久化。

tsx
export type PersistRetryer = (props: {
  persistedClient: PersistedClient
  error: Error
  errorCount: number
}) => PersistedClient | undefined

export type PersistRetryer = (props: {
  persistedClient: PersistedClient
  error: Error
  errorCount: number
}) => PersistedClient | undefined

预定义策略

默认情况下，不会发生重试。您可以使用预定义的策略之一来处理重试。它们可以从 @tanstack/react-query-persist-client 导入：

  • removeOldestQuery
    • 将返回一个删除了最旧查询的新 PersistedClient。
tsx
const localStoragePersister = createSyncStoragePersister({
  storage: window.localStorage,
  retry: removeOldestQuery,
})

const localStoragePersister = createSyncStoragePersister({
  storage: window.localStorage,
  retry: removeOldestQuery,
})

API

createSyncStoragePersister

调用此函数以创建一个 syncStoragePersister，您稍后可以将其与 persistQueryClient 一起使用。

tsx
createSyncStoragePersister(options: CreateSyncStoragePersisterOptions)

createSyncStoragePersister(options: CreateSyncStoragePersisterOptions)

选项
tsx
interface CreateSyncStoragePersisterOptions {
  /** 用于从缓存中设置和检索项目的存储客户端 (window.localStorage 或 window.sessionStorage) */
  storage: Storage | undefined | null
  /** 存储缓存时使用的键 */
  key?: string
  /** 为避免垃圾邮件，
   * 传递一个以毫秒为单位的时间来限制将缓存保存到磁盘的频率 */
  throttleTime?: number
  /** 如何将数据序列化到存储 */
  serialize?: (client: PersistedClient) => string
  /** 如何从存储中反序列化数据 */
  deserialize?: (cachedString: string) => PersistedClient
  /** 如何在出错时重试持久化 **/
  retry?: PersistRetryer
}

interface CreateSyncStoragePersisterOptions {
  /** 用于从缓存中设置和检索项目的存储客户端 (window.localStorage 或 window.sessionStorage) */
  storage: Storage | undefined | null
  /** 存储缓存时使用的键 */
  key?: string
  /** 为避免垃圾邮件，
   * 传递一个以毫秒为单位的时间来限制将缓存保存到磁盘的频率 */
  throttleTime?: number
  /** 如何将数据序列化到存储 */
  serialize?: (client: PersistedClient) => string
  /** 如何从存储中反序列化数据 */
  deserialize?: (cachedString: string) => PersistedClient
  /** 如何在出错时重试持久化 **/
  retry?: PersistRetryer
}

默认选项是：

tsx
{
  key = `REACT_QUERY_OFFLINE_CACHE`,
  throttleTime = 1000,
  serialize = JSON.stringify,
  deserialize = JSON.parse,
}

{
  key = `REACT_QUERY_OFFLINE_CACHE`,
  throttleTime = 1000,
  serialize = JSON.stringify,
  deserialize = JSON.parse,
}

serialize 和 deserialize 选项

localStorage 中可存储的数据量有限。 如果您需要在 localStorage 中存储更多数据，可以使用诸如 lz-string 之类的库来压缩和解压缩数据，从而覆盖 serialize 和 deserialize 函数。

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

import { compress, decompress } from 'lz-string'

const queryClient = new QueryClient({
  defaultOptions: { queries: { staleTime: Infinity } },
})

persistQueryClient({
  queryClient: queryClient,
  persister: createSyncStoragePersister({
    storage: window.localStorage,
    serialize: (data) => compress(JSON.stringify(data)),
    deserialize: (data) => JSON.parse(decompress(data)),
  }),
  maxAge: Infinity,
})

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

import { compress, decompress } from 'lz-string'

const queryClient = new QueryClient({
  defaultOptions: { queries: { staleTime: Infinity } },
})

persistQueryClient({
  queryClient: queryClient,
  persister: createSyncStoragePersister({
    storage: window.localStorage,
    serialize: (data) => compress(JSON.stringify(data)),
    deserialize: (data) => JSON.parse(decompress(data)),
  }),
  maxAge: Infinity,
})
在 GitHub 上编辑
persistQueryClient
createAsyncStoragePersister