首页 › HTML › HTML5 API › Web Storage

Web Storage 提供了在浏览器中持久化存储数据的能力，比 Cookie 更大、更易用。

localStorage vs sessionStorage

特性	localStorage	sessionStorage	Cookie
生命周期	手动清除	关闭标签页/窗口	可设置过期时间
容量	~5MB	~5MB	~4KB
发送到服务器	❌	❌	✅（每次请求自动发送）
同一站点跨标签	✅ 共享	❌ 隔离	取决于设置
API	同步 Key-Value	同步 Key-Value	需要手动操作

基本操作

// 存储
localStorage.setItem('username', '张三');
localStorage.setItem('theme', 'dark');

// 读取
const name = localStorage.getItem('username');     // "张三"
const theme = localStorage.getItem('theme');       // "dark"
const notExist = localStorage.getItem('notHere');  // null

// 删除单个
localStorage.removeItem('theme');

// 清空所有
localStorage.clear();

// 获取数量
const len = localStorage.length;

// 按索引获取 key
const firstKey = localStorage.key(0);

存储对象

Storage 只能存字符串，对象需要 JSON.stringify / JSON.parse：

// 保存对象
const user = { id: 1, name: '张三', preferences: { theme: 'dark', lang: 'zh' } };
localStorage.setItem('user', JSON.stringify(user));

// 读取对象
const saved = JSON.parse(localStorage.getItem('user'));
console.log(saved.name);             // "张三"
console.log(saved.preferences.theme); // "dark"

// 更新对象
saved.preferences.theme = 'light';
localStorage.setItem('user', JSON.stringify(saved));

storage 事件

同源下其他标签页修改 Storage 时触发（当前页不会触发）：

window.addEventListener('storage', (event) => {
  console.log('变化的 key:', event.key);       // 'theme'
  console.log('旧值:', event.oldValue);         // null
  console.log('新值:', event.newValue);         // 'dark'
  console.log('来源 URL:', event.url);          // 'https://example.com'
  console.log('Storage 区域:', event.storageArea); // localStorage
});

用途：多标签页同步设置。例如修改主题色后其他标签页立即更新。

实用示例：主题存储

// 读取已保存的主题，无则默认 light
const savedTheme = localStorage.getItem('theme') || 'light';
document.documentElement.setAttribute('data-theme', savedTheme);

// 切换主题并保存
function toggleTheme() {
  const current = document.documentElement.getAttribute('data-theme');
  const next = current === 'dark' ? 'light' : 'dark';
  document.documentElement.setAttribute('data-theme', next);
  localStorage.setItem('theme', next);
}

小结

API	作用
setItem(key, value)	存储
getItem(key)	读取
removeItem(key)	删除
clear()	清空
storage 事件	跨标签同步
JSON 序列化	存储对象/数组

上一节：SVG 基础 下一节：Geolocation 与 History API

贡献者: 布欧-Lewyon