持久存储状态

用于将 React 状态与浏览器存储同步的 Hook。

Toolpad Core 提供了一组 Hook，用于抽象处理浏览器中全局状态的持久化。通过这些 Hook，您可以将 React 状态与本地存储或会话存储同步，或者在 URL 中作为查询参数同步。这些 Hook 都遵循类似的理念：它们使用唯一的键标识其数据，并通过使用编解码器支持丰富的数据类型。

这些 Hook 的签名有意地类似于 React.useState Hook。其中，第一个参数表示在浏览器中存储状态的键，第二个参数对应于初始值。可选的第三个参数可用于配置 Hook。

本地存储

字符串值

Hook 的默认行为是读取和写入字符串值。您只需提供一个存储键，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` 参数来声明用于序列化和反序列化的方法。编解码器包含 `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 开始编辑

编解码器使以类型安全的方式使用此 Hook 成为可能。

错误处理

当本地存储由于某种原因不可用时，`useLocalStorageState` Hook 返回 `null`。编解码器的 `parse` 方法中的错误将始终传播。如果您想处理解析错误，则必须在编解码器中进行处理。

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 开始编辑