createPersister (實驗性)
安裝
此工具程式以獨立套件形式提供，可透過 '@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_createPersister 函式
- 建立一個新的 experimental_createPersister
- 可傳入任何符合 AsyncStorage 或 Storage 介面的 storage
- 將該 persister 作為選項傳遞給你的 Query。可透過傳遞至 QueryClient 的 defaultOptions 或任何 useQuery hook 實例來實現。
- 若將此 persister 設為 defaultOptions，所有查詢將被持久化至提供的 storage 中。你還可透過傳遞 filters 進一步縮小範圍。與 persistClient 外掛不同，這不會將整個 query client 作為單一項目持久化，而是分別持久化每個查詢。查詢雜湊值 (query hash) 將被用作鍵名。
- 若將此 persister 提供給單一 useQuery hook，則僅該查詢會被持久化。
如此一來，你無需儲存整個 QueryClient，而是選擇應用程式中值得持久化的內容。每個查詢會以懶載入方式還原（當查詢首次被使用時）並持久化（在每次執行 queryFn 後），因此無需進行節流處理。還原查詢後也會遵守 staleTime，若資料被視為過時 (stale)，將在還原後立即重新擷取。若資料為最新 (fresh)，則不會執行 queryFn。
從記憶體中垃圾回收查詢不會影響持久化的資料。這意味著查詢可在記憶體中保留較短時間以提升記憶體效率。當下次使用時，它們將直接從持久化儲存中再次還原。
tsx
import { QueryClient } from '@tanstack/vue-query'
import { experimental_createPersister } from '@tanstack/query-persist-client-core'
const queryClient = new QueryClient({
defaultOptions: {
queries: {
gcTime: 1000 * 30, // 30 秒
persister: experimental_createPersister({
storage: localStorage,
maxAge: 1000 * 60 * 60 * 12, // 12 小時
}),
},
},
})
import { QueryClient } from '@tanstack/vue-query'
import { experimental_createPersister } from '@tanstack/query-persist-client-core'
const queryClient = new QueryClient({
defaultOptions: {
queries: {
gcTime: 1000 * 30, // 30 秒
persister: experimental_createPersister({
storage: localStorage,
maxAge: 1000 * 60 * 60 * 12, // 12 小時
}),
},
},
})
調整後的預設值
createPersister 外掛在技術上包裝了 queryFn，因此若 queryFn 未執行則不會進行還原。在此意義上，它扮演著查詢與網路之間的快取層。因此，當使用 persister 時，networkMode 預設為 'offlineFirst'，以便即使沒有網路連線時也能從持久化儲存中還原資料。
API
experimental_createPersister
tsx
experimental_createPersister(options: StoragePersisterOptions)
experimental_createPersister(options: StoragePersisterOptions)
選項
tsx
export interface StoragePersisterOptions {
/** 用於從快取中設定和檢索項目的儲存客戶端。
* 對於 SSR 請傳入 `undefined`。
*/
storage: AsyncStorage | Storage | undefined | null
/**
* 如何將資料序列化至儲存。
* @預設值 `JSON.stringify`
*/
serialize?: (persistedQuery: PersistedQuery) => string
/**
* 如何從儲存中反序列化資料。
* @預設值 `JSON.parse`
*/
deserialize?: (cachedString: string) => PersistedQuery
/**
* 用於強制使現有快取失效的唯一字串，
* 若它們未共用相同的 buster 字串
*/
buster?: string
/**
* 快取允許的最大存活時間（毫秒）。
* 若發現持久化的快取存活時間超過此設定，
* 將被捨棄
* @預設值 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
/**
* 如何將資料序列化至儲存。
* @預設值 `JSON.stringify`
*/
serialize?: (persistedQuery: PersistedQuery) => string
/**
* 如何從儲存中反序列化資料。
* @預設值 `JSON.parse`
*/
deserialize?: (cachedString: string) => PersistedQuery
/**
* 用於強制使現有快取失效的唯一字串，
* 若它們未共用相同的 buster 字串
*/
buster?: string
/**
* 快取允許的最大存活時間（毫秒）。
* 若發現持久化的快取存活時間超過此設定，
* 將被捨棄
* @預設值 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,
}
