useLocalStorage 本地存储钩子
最后更新：2026-10-28
useLocalStorage 本地存储钩子
useLocalStorage 把 useState 的读写同步到 localStorage：初始化时惰性读取已存值，更新时自动写回磁盘，刷新页面后状态仍在。它是「自定义 Hook 包装原生 API」的典型示范。
| 分组 | 组件模式 |
|---|---|
| 类型 | Hook |
| 引入版本 | React 16.8 |
ℹ️ 说明 编辑器将 JSX 转译为 JavaScript 后在沙箱中渲染真实界面；组件自动挂载，无需手写 render 调用。
📝 语法
function useLocalStorage(key, initial) {
const [value, setValue] = useState(() => {
const saved = localStorage.getItem(key) // 惰性初始化：只读一次
return saved !== null ? JSON.parse(saved) : initial
})
useEffect(() => {
localStorage.setItem(key, JSON.stringify(value))
}, [key, value])
return [value, setValue]
}⚙️ 参数
| key | localStorage 的存储键名，建议带应用前缀避免冲突。 |
|---|---|
| initial | 本地没有存值时的初始值，支持任意可 JSON 序列化的类型。 |
返回值：返回 [value, setValue] 二元组，用法与 useState 完全一致，但读写已自动持久化到 localStorage。
▶ 示例
示例可直接运行：展开后自动渲染，编辑代码即时生效。
输出结果：
点按钮计数增加并写入 localStorage；刷新或重开页面后计数仍在，点「清零」归零。💡 要点
💡 提示 初始化传函数做惰性读取，避免每次渲染都访问 localStorage（同步 IO，开销不小）。
ℹ️ 说明 存对象/数组要用 JSON 序列化；读取时建议 try/catch 防御脏数据或手改过的值。
⚠️ 注意 localStorage 同源共享且有约 5MB 上限，敏感数据（如 token）不建议明文存放。
🏷️ 组件模式相关
💡 相关案例
更多案例整理中，敬请期待。
📚 相关教程
❓ 常见问题
Q SSR 下会报错吗？
A 会，服务端没有 window/localStorage。需在读取处判空（typeof window）或放到 useEffect 里。
Q 和直接用 useState 的区别？
A 多了一层持久化：初始值来自磁盘、每次变更自动写回，API 与 useState 保持一致。
Q 存对象为什么要 JSON.stringify？
A localStorage 只能存字符串；不序列化会得到 "[object Object]"，读回来无法还原。
