useLocalStorage

操作浏览器 localStorage 的响应式 Hook，支持自动序列化和类型安全。

前置依赖

依赖参数

参数名	类型	说明
deps.localStorage	Storage	localStorage 对象
deps.consoleError	Console['error']	错误日志函数

环境要求

• 浏览器环境: 使用 localStorage API

const deps = {
  localStorage: window.localStorage,
  consoleError: console.error
}

函数签名

function useLocalStorage<T>(
  key: string,
  defaultValue: T,
  options?: StorageOptions<T>,
  deps: LocalStorageDeps
): [Ref<T>, (value: T) => void, () => void]

interface StorageOptions<T> {
  prefix?: string
  serializer?: {
    serialize: (value: T) => string
    deserialize: (value: string) => T
  }
}

interface LocalStorageDeps {
  localStorage: Storage
  consoleError: Console['error']
}

参数

参数名	类型	必填	默认值	说明
key	string	是	-	存储键名
defaultValue	T	是	-	默认值
options.prefix	string	否	''	键名前缀
options.serializer	object	否	JSON.stringify/parse	自定义序列化器
deps	LocalStorageDeps	是	-	依赖注入对象

返回值

类型	说明
[Ref<T>, (value: T) => void, () => void]	返回元组：[响应式值, 设置函数, 删除函数]

工作原理

1. 初始化：

   • 尝试从 localStorage 读取值
   • 如果存在：反序列化并使用
   • 如果不存在或反序列化失败：使用 defaultValue
   • 创建响应式 ref

2. 读取流程：

   • 使用 prefix + key 作为完整键名
   • 调用 localStorage.getItem
   • 使用 serializer.deserialize 反序列化（默认 JSON.parse）
   • 捕获异常，失败时返回 defaultValue

3. 设置函数：

   • 更新 ref 的值（触发响应式）
   • 使用 serializer.serialize 序列化（默认 JSON.stringify）
   • 调用 localStorage.setItem 存储

4. 删除函数：

   • 重置 ref 为 defaultValue
   • 调用 localStorage.removeItem 删除存储

5. 错误处理：

   • 所有操作使用 try-catch 包裹
   • 错误时输出到 consoleError
   • 不影响程序正常运行

支持自动序列化，可存储对象、数组等复杂类型。与 Vue 3 响应式系统集成。