持久化儲存狀態

用於將 React 狀態與瀏覽器儲存同步的 Hook。

Toolpad Core 提供了一組 Hook，用於抽象化處理在瀏覽器中持久化全域狀態。透過這些 Hook，您可以將 React 狀態與 local storage 或 session storage 同步，或在 URL 中作為查詢參數。這些 Hook 都遵循相似的理念：它們使用唯一的 key 來識別其資料，並透過 codec 的使用來支援豐富的資料類型。

Hook 的簽名刻意地類似於 React.useState hook。第一個參數代表在瀏覽器中儲存狀態的 key，第二個參數對應於初始值。可使用選用的第三個參數來配置 hook。

Local Storage

字串值

Hook 的預設行為是讀取和寫入字串值。您只需提供一個儲存 key，hook 就會完成剩下的工作。您可以將初始值作為第二個參數提供。就像 React.useState hook 一樣，您可以提供一個初始化器函式，以防計算初始值是一個繁重的操作。Hook 在 SSR 和 hydration 期間將始終返回 null。

const [value, setValue] = useLocalStorageState('string-value', 'Initial Value');

const [value, setValue] = useLocalStorageState('string-value', 'Initial Value');

按下 Enter 鍵開始編輯

在另一個分頁中開啟此頁面，以查看 hook 的實際運作。

重要將 null 傳遞給 setState 會導致從儲存中移除該值。

豐富的資料類型

如果您需要儲存字串以外的值，可以使用 hook 選項中的 codec 參數來宣告用於序列化和反序列化的方法。Codec 包含一個 parse 方法和 stringify 方法。

基本日期選擇器

const DAYJS_CODEC: Codec<Dayjs> = {
  parse: (dateString) => dayjs(dateString),
  stringify: (date) => date.toISOString(),
};

export default function LocalStorageStateCustom() {
  const [value, setValue] = useLocalStorageState('custom-value', null, {
    codec: DAYJS_CODEC,
  });
  // ...

const DAYJS_CODEC: Codec<Dayjs> = {
  parse: (dateString) => dayjs(dateString),
  stringify: (date) => date.toISOString(),
};

export default function LocalStorageStateCustom() {
  const [value, setValue] = useLocalStorageState('custom-value', null, {
    codec: DAYJS_CODEC,
  });
  // ...

按下 Enter 鍵開始編輯

Codec 使以類型安全的方式使用此 hook 成為可能。

錯誤處理

當 local storage 因某些原因不可用時，useLocalStorageState hook 會返回 null。Codec 的 parse 方法中的錯誤將始終被傳播。如果您想處理解析錯誤，則必須在 codec 中執行此操作。

value: null

const CODEC_JSON: Codec<unknown> = {
  parse: (value) => {
    try {
      return JSON.parse(value);
    } catch {
      return { _error: 'parse failed' };
    }
  },
  stringify: (value) => JSON.stringify(value),
};

const CODEC_JSON: Codec<unknown> = {
  parse: (value) => {
    try {
      return JSON.parse(value);
    } catch {
      return { _error: 'parse failed' };
    }
  },
  stringify: (value) => JSON.stringify(value),
};

按下 Enter 鍵開始編輯

自訂驗證

對於複雜的資料類型，您可以將這些 hook 與類型化的驗證函式庫（例如 zod）配對使用。

const schema = z.enum(['foo', 'bar', 'baz']).default('foo');

type SchemaType = z.infer<typeof schema>;

const CODEC: Codec<SchemaType> = {
  parse: (value) => {
    try {
      return schema.parse(JSON.parse(value));
    } catch {
      return 'foo';
    }
  },
  stringify: (value) => JSON.stringify(value),
};

const schema = z.enum(['foo', 'bar', 'baz']).default('foo');

type SchemaType = z.infer<typeof schema>;

const CODEC: Codec<SchemaType> = {
  parse: (value) => {
    try {
      return schema.parse(JSON.parse(value));
    } catch {
      return 'foo';
    }
  },
  stringify: (value) => JSON.stringify(value),
};

按下 Enter 鍵開始編輯

持久化儲存狀態

Local Storage

字串值

豐富的資料類型

錯誤處理

自訂驗證

Session storage

搜尋參數

Hook API