useLocalStorage

用于管理浏览器本地存储的 Hook，提供响应式的数据持久化功能，支持自动序列化、跨标签页同步等特性。

基础用法

最简单的用法是存储和读取字符串数据。

用户名:

存储的值: (空)

显示代码

存储对象数据

可以直接存储和管理复杂的对象数据，Hook 会自动处理序列化。

用户设置

深色模式

语言:

zh

• 中文
• English
• 日本語

当前设置:

{
  "darkMode": false,
  "language": "zh"
}

显示代码

计数器演示

展示数值类型的持久化存储，页面刷新后数据依然保留。

0

页面刷新后数值会保留

显示代码

表单数据持久化

在表单填写过程中自动保存数据，避免意外丢失。

姓名:

年龄:

邮箱:

城市:

• 北京
• 上海
• 广州
• 深圳

表单数据:

{
  "name": "",
  "age": "",
  "email": "",
  "city": ""
}

显示代码

数组数据管理

管理列表数据，支持增删改查操作。

待办事项列表

📝 暂无待办事项，添加一个开始吧！

显示代码

自定义序列化器

对于特殊数据类型（如 Date），可以提供自定义的序列化器。

上次访问时间:

存储的时间: 未设置

显示代码

跨标签页同步

启用跨标签页同步功能，多个标签页之间的数据会自动同步。

购物车 (跨标签页同步)

💡 打开多个标签页测试同步效果

🛒 购物车为空

显示代码

API

参数

参数	类型	默认值	说明
key	string	-	localStorage 的键名
defaultValue	T	-	默认值
options	UseLocalStorageOptions<T>	{}	配置选项

UseLocalStorageOptions

属性	类型	默认值	说明
serializer	StorageSerializer<T>	JSON	自定义序列化器
syncAcrossTabs	boolean	false	是否跨标签页同步
onError	(error: Error) => void	console.error	错误处理函数

返回值

返回一个数组 [storedValue, setValue, removeValue]：

索引	名称	类型	说明
0	storedValue	Ref<T>	存储的值（响应式）
1	setValue	SetStorageFunction<T>	设置值函数
2	removeValue	RemoveStorageFunction	移除值函数

类型定义

/**
 * 设置存储值函数类型
 * @param value 要设置的值
 */
type SetStorageFunction<T> = (value: T) => void;

/**
 * 移除存储值函数类型
 */
type RemoveStorageFunction = () => void;

/**
 * useLocalStorage 返回值类型
 * @example
 * const [value, setValue, removeValue] = useLocalStorage('key', 'default');
 */
type UseLocalStorageReturn<T> = [
  /** 存储的值（响应式） */ Ref<T>,
  /** 设置值函数 */ SetStorageFunction<T>,
  /** 移除值函数 */ RemoveStorageFunction,
];

/**
 * 存储序列化器接口
 */
interface StorageSerializer<T> {
  /** 读取时的反序列化函数 */
  read: (value: string) => T;
  /** 写入时的序列化函数 */
  write: (value: T) => string;
}

/**
 * useLocalStorage 配置选项
 */
interface UseLocalStorageOptions<T> {
  /** 自定义序列化器 */
  serializer?: StorageSerializer<T>;
  /** 是否跨标签页同步 */
  syncAcrossTabs?: boolean;
  /** 错误处理函数 */
  onError?: (error: Error) => void;
}

/**
 * 本地存储钩子
 * @param key localStorage 的键名
 * @param defaultValue 默认值
 * @param options 配置选项
 * @returns UseLocalStorageReturn
 * @example
 * const [username, setUsername, removeUsername] = useLocalStorage('username', '');
 */
function useLocalStorage<T>(key: string, defaultValue: T, options?: UseLocalStorageOptions<T>): UseLocalStorageReturn<T>;

注意事项

1. 浏览器兼容性 - 需要浏览器支持 localStorage API
2. 序列化 - 默认使用 JSON 序列化，复杂对象需要自定义序列化器
3. 存储限制 - localStorage 有大小限制（通常 5-10MB）
4. 错误处理 - 当 localStorage 不可用时会使用内存存储
5. 跨标签页同步 - 启用后会监听 storage 事件实现同步
6. SSR 支持 - 在服务端渲染时会使用默认值

使用场景

• 用户偏好设置
• 表单数据持久化
• 购物车状态保存
• 主题切换状态
• 用户登录状态
• 应用配置信息