存储中的 API
localStorage 与 sessionStorage
发布于 更新于
window.localStorage 和 window.sessionStorage 是按源存储字符串键值的 Storage 对象,适合保存少量标志和偏好设置。localStorage 的数据在标签页关闭、浏览器重启后仍会保留;sessionStorage 属于单个顶级浏览上下文,关闭对应标签页或窗口就会丢弃数据。两者都在主线程同步执行,worker 和 Service Worker 无法使用,应用数据应选用其他存储。
localStorage.setItem(key, value)localStorage.getItem(key)localStorage.removeItem(key)localStorage.clear()localStorage.key(index)localStorage.lengthsessionStorage 的接口完全相同。值以字符串存储:setItem('n', 1) 存入 "1",对象不先序列化就会存成 "[object Object]"。Chrome 4、Firefox 3.5、Safari 4 起支持(BCD api.Window.localStorage);没有安全上下文要求,但同一主机的两种 scheme 是不同的源,互不共享存储。
| 方法 | 参数 | 类型 | 含义 |
|---|---|---|---|
setItem |
key、value |
string、string | 创建或覆盖一条。非字符串参数经 String() 转换。 |
getItem |
key |
string | 返回值,键不存在时返回 null。空字符串是合法的存储值,返回 "" 而不是 null。 |
removeItem |
key |
string | 删除一条。删除不存在的键不报错。 |
clear |
无 | 删除该源在该存储区内的全部条目。 | |
key |
index |
unsigned long | 返回该位置的键,越界返回 null。顺序由实现决定,写入后会变。 |
每次调用都在主线程同步执行;Firefox 和 Chromium 用按源划分的磁盘数据库支撑它,循环写入大字符串会在整个过程中阻塞渲染。
可用性
链接到“可用性”一节Web Storage 存在于所有引擎(Chrome 4、Firefox 3.5、Safari 4;BCD api.Window.localStorage),包括 Android WebView 和 iOS 的 WebView,是唯一没有支持缺口的客户端存储。使用限制取决于上下文:worker 和 Service Worker 不提供这两个对象,不透明源访问时会抛出异常,每个源的容量上限也很小。
| 异常 | 位置 | 触发条件 |
|---|---|---|
QuotaExceededError DOMException |
setItem() |
写入将超出存储区上限。Firefox 把 localStorage 限制为每源 5 MiB(StaticPrefList.yaml 中的 dom.storage.default_quota,5 × 1024 KiB,github.com)。Chromium 在写入被拒绝时抛出该错误,报错文本为 Setting the value of '<key>' exceeded the quota.(storage_area.cc,chromium.googlesource.com)。 |
SecurityError DOMException |
读取 window.localStorage |
源是不透明源(没有 allow-same-origin 的沙箱 <iframe>、data: URL),或用户已为该站点拦截存储。getter 本身抛出,所以 'localStorage' in window 也不够,首次访问要包在 try 里。 |
Firefox 和 Chromium 的隐私窗口可以正常写入,隐私会话结束后才丢弃数据。MDN 指出,有些浏览器在隐私浏览模式下可能改为提供配额为零的空 localStorage,第一次 setItem() 就抛出 QuotaExceededError;「写一条再删一条」的探测同时覆盖这两种行为。
示例使用 localStorage;换成 sessionStorage 即为按标签页的状态,代码其余部分不变。
保存偏好并在另一个标签页响应
链接到“保存偏好并在另一个标签页响应”一节storage 事件在共享该存储区的其他同源文档上触发,不在写入的那个文档上触发。用它让两个打开的标签页保持同步,而不必轮询。
function setTheme(theme) { localStorage.setItem('theme', theme); applyTheme(theme); // 本标签页不会收到 storage 事件}
window.addEventListener('storage', (event) => { if (event.storageArea === localStorage && event.key === 'theme') { applyTheme(event.newValue ?? 'light'); // removeItem 之后 newValue 为 null }});event.storageArea 区分 localStorage 和 sessionStorage 的写入,clear() 之后 event.key 为 null。
带体积守卫地序列化结构化数据
链接到“带体积守卫地序列化结构化数据”一节容量上限按序列化字符串的字符数计算,写入前先检查长度。遇到 QuotaExceededError,将数据移到 IndexedDB,不要重试这次写入。
function saveSettings(settings) { const json = JSON.stringify(settings); try { localStorage.setItem('settings', json); return true; } catch (err) { if (err.name === 'QuotaExceededError') return false; // 太大:改存 IndexedDB throw err; }}超过几百 KB 的数据应放进 IndexedDB,它是异步的,并共享该源大得多的配额。
检测可用的存储区
链接到“检测可用的存储区”一节检测函数尝试写入一个键,再将它删除。不透明源(getter 抛出 SecurityError)、禁止存储的站点和旧版 Safari 的零配额隐私模式都会得到 false。
function storageAvailable(type) { if (!(type in window)) { return false; // 没有 Web Storage:本次会话把状态放在内存里 } try { const area = window[type]; const probe = '__probe__'; area.setItem(probe, probe); area.removeItem(probe); return true; } catch { return false; // 访问被拒或零配额:退回内存 }}启动时用 'localStorage' 调用一次并记住结果;它检测的条件在页面打开期间不会变化。
另请参阅
链接到“另请参阅”一节- HTML Standard: Web storage(whatwg.org)
- Using the Web Storage API(developer.mozilla.org)
- IndexedDB
- StorageManager.estimate()
- Clear-Site-Data 响应头
规范
| 规范 | 状态 |
|---|---|
| 无。 | |