讲解如何使用 localStorage 实现 JavaScript 购物车数据持久化存储,包括数据结构设计、安全读写封装、完整的增删改查代码、多标签页同步以及常见误区排查。
怎么使用localStorage实现JS购物车数据持久化存储
时间:2026-11-22
浏览:439
文章目录
要在纯前端页面中让购物车数据在刷新或关闭标签页后依然保留,核心做法是:把购物车数组通过 JSON.stringify() 序列化为字符串写入浏览器的 localStorage;页面重新加载时再通过 localStorage.getItem() 取出,并用 JSON.parse() 还原为数组,同时配合 try...catch 处理解析异常与存储限制。下文按数据结构设计、安全读写封装、完整增删改查示例、多标签页同步以及常见误区排查的顺序给出可直接运行的方案。
一、先确定购物车数据结构与存储边界
在写读写函数之前,需要先确定购物车里到底存哪些字段。一般用数组表示购物车,数组中每个对象对应一件商品(或一个规格 SKU),推荐只保留界面展示和后续合并所需的最小字段:
const sampleCart = [
{
id: 'sku-1001',
name: '纯棉基础款T恤(M码)',
price: 79,
quantity: 2,
checked: true
}
];
这样设计有三个直接好处:每个商品都有唯一标识 id,重复加入时可以准确累加 quantity;携带 checked 状态后,用户勾选了哪些商品在刷新后也不会丢失;字段精简,单条记录只有一百多字节,不容易触及浏览器的存储容量上限。
这种做法只在纯静态演示页面(商品无后端更新、无真实支付)下成立,能够少写一次详情查询。但在真实业务中需要修正两点:第一,把商品详情描述、多张图片 Base64 等大字段全部塞进
localStorage,会很快逼近单个源通常几 MB 的容量上限;第二,本地存储的内容在浏览器开发者工具中可以随意修改,而且商品在服务端可能已调价或下架。因此,localStorage 里的 price 和 name 仅适合做快速渲染兜底,提交订单前必须由服务端按 id 重新核对最新价格与库存。
同时需要明确一个基础事实:localStorage 的 setItem(key, value) 只支持字符串。如果直接把数组传进去,JavaScript 会隐式调用数组的 toString(),最终写进去的是一串无效的 "[object Object]",商品字段会全部丢失。必须经过 JSON.stringify() 和 JSON.parse() 做转换。
二、封装带异常处理的 localStorage 读写方法
直接写 JSON.parse(localStorage.getItem('cart')) 在实际页面里很容易出故障,主要有两个原因:读取到的 JSON 字符串可能被外部插件或人工调试改坏,导致 JSON.parse() 抛出 SyntaxError;在无痕/隐私限制环境、浏览器禁用站点数据或存储空间已满时,localStorage 访问或 setItem() 会抛出 SecurityError 或 QuotaExceededError。
把读写逻辑封装成两个独立函数,在内部统一做容错与格式校验,后续业务代码只需要调用这两个函数即可:
const CART_STORAGE_KEY = 'shop_cart_v1';
/**
* 从 localStorage 安全读取购物车数组
* @returns {Array}
*/
function readCartFromStorage() {
try {
const raw = window.localStorage.getItem(CART_STORAGE_KEY);
if (!raw) {
return [];
}
const parsed = JSON.parse(raw);
// 防止存储内容被意外写成对象、数字或 null 导致后续 .map / .find 报错
if (!Array.isArray(parsed)) {
return [];
}
return parsed.filter(
(item) =>
item &&
typeof item.id === 'string' &&
typeof item.price === 'number' &&
Number.isInteger(item.quantity) &&
item.quantity > 0
);
} catch (err) {
console.warn('读取购物车本地数据失败,已回退为空列表:', err);
return [];
}
}
/**
* 将购物车数组安全写入 localStorage
* @param {Array} cartList
* @returns {boolean} 是否写入成功
*/
function saveCartToStorage(cartList) {
try {
const serialized = JSON.stringify(cartList);
window.localStorage.setItem(CART_STORAGE_KEY, serialized);
return true;
} catch (err) {
if (err && err.name === 'QuotaExceededError') {
console.error('浏览器本地存储空间已满,无法保存更多购物车数据');
} else {
console.warn('写入 localStorage 失败(可能被浏览器隐私策略禁用):', err);
}
return false;
}
}
这里顺带加入了字段合法性过滤(filter):即使旧版本数据或手工调试留下了缺字段的脏条目,也不会把渲染和金额汇总弄崩溃。键名加上版本号 _v1,后续需要调整字段结构时可以按版本号升级并清理旧键。
三、实现完整的购物车持久化示例(增删改查与刷新恢复)
下面给出一个完整可运行的单页 HTML 示例。请在本地静态服务器环境(如在文件所在目录执行 python3 -m http.server 5500 后访问 http://localhost:5500/cart.html,或使用编辑器的 Live Server 插件)下运行。尽量不要直接双击以 file:// 协议打开测试,因为部分浏览器对本地文件路径的 localStorage 共享和持久化策略与 HTTP 站点不同。
把下方代码保存为 cart.html,里面包含商品列表、购物车操作方法以及持久化读写调用。所有变更操作统一通过 commitCartChange() 先写入 localStorage 再刷新视图,避免两处不同步:
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8" />
<title>localStorage 购物车示例</title>
</head>
<body>
<h2>商品列表</h2>
<div id="product-list"></div>
<h2>购物车</h2>
<div id="cart-list"></div>
<p id="cart-summary"></p>
<button id="clear-cart-btn" type="button">清空购物车</button>
<script>
const CART_STORAGE_KEY = 'shop_cart_v1';
const products = [
{ id: 'sku-1001', name: '纯棉基础款T恤', price: 79 },
{ id: 'sku-1002', name: '帆布通勤托特包', price: 128 },
{ id: 'sku-1003', name: '陶瓷马克杯', price: 45 }
];
function readCartFromStorage() {
try {
const raw = window.localStorage.getItem(CART_STORAGE_KEY);
if (!raw) return [];
const parsed = JSON.parse(raw);
if (!Array.isArray(parsed)) return [];
return parsed.filter(
(item) =>
item &&
typeof item.id === 'string' &&
typeof item.price === 'number' &&
Number.isInteger(item.quantity) &&
item.quantity > 0
);
} catch (err) {
console.warn('读取购物车失败,已重置为空:', err);
return [];
}
}
function saveCartToStorage(cartList) {
try {
window.localStorage.setItem(CART_STORAGE_KEY, JSON.stringify(cartList));
return true;
} catch (err) {
console.warn('写入购物车失败:', err);
return false;
}
}
// 内存中的购物车状态,页面启动时从 localStorage 恢复
let cart = [];
function commitCartChange() {
saveCartToStorage(cart);
renderCart();
}
function addToCart(product) {
const existing = cart.find((item) => item.id === product.id);
if (existing) {
existing.quantity += 1;
} else {
cart.push({
id: product.id,
name: product.name,
price: product.price,
quantity: 1,
checked: true
});
}
commitCartChange();
}
function updateQuantity(id, delta) {
const target = cart.find((item) => item.id === id);
if (!target) return;
const nextQty = target.quantity + delta;
if (nextQty <= 0) {
cart = cart.filter((item) => item.id !== id);
} else {
target.quantity = nextQty;
}
commitCartChange();
}
function toggleChecked(id) {
const target = cart.find((item) => item.id === id);
if (!target) return;
target.checked = !target.checked;
commitCartChange();
}
function removeFromCart(id) {
cart = cart.filter((item) => item.id !== id);
commitCartChange();
}
function clearCart() {
cart = [];
try {
window.localStorage.removeItem(CART_STORAGE_KEY);
} catch (err) {
console.warn('清理购物车失败:', err);
}
renderCart();
}
function renderProducts() {
const container = document.getElementById('product-list');
container.innerHTML = '';
products.forEach((p) => {
const row = document.createElement('div');
const btn = document.createElement('button');
btn.type = 'button';
btn.textContent = '加入购物车';
btn.addEventListener('click', () => addToCart(p));
row.textContent = p.name + ' - ¥' + p.price + ' ';
row.appendChild(btn);
container.appendChild(row);
});
}
function renderCart() {
const listEl = document.getElementById('cart-list');
const summaryEl = document.getElementById('cart-summary');
listEl.innerHTML = '';
if (cart.length === 0) {
listEl.textContent = '购物车为空';
summaryEl.textContent = '已选 0 件,合计 ¥0.00';
return;
}
let selectedCount = 0;
let totalCents = 0;
cart.forEach((item) => {
const row = document.createElement('div');
const checkbox = document.createElement('input');
checkbox.type = 'checkbox';
checkbox.checked = Boolean(item.checked);
checkbox.addEventListener('change', () => toggleChecked(item.id));
const minusBtn = document.createElement('button');
minusBtn.type = 'button';
minusBtn.textContent = '-';
minusBtn.addEventListener('click', () => updateQuantity(item.id, -1));
const plusBtn = document.createElement('button');
plusBtn.type = 'button';
plusBtn.textContent = '+';
plusBtn.addEventListener('click', () => updateQuantity(item.id, 1));
const delBtn = document.createElement('button');
delBtn.type = 'button';
delBtn.textContent = '删除';
delBtn.addEventListener('click', () => removeFromCart(item.id));
const label = document.createElement('span');
label.textContent = ' ' + item.name + ' (¥' + item.price + ') × ' + item.quantity + ' ';
row.append(checkbox, label, minusBtn, plusBtn, delBtn);
listEl.appendChild(row);
if (item.checked) {
selectedCount += item.quantity;
// 转为分再累加,减少浮点数精度误差(例如 0.1 + 0.2)
totalCents += Math.round(item.price * 100) * item.quantity;
}
});
summaryEl.textContent =
'已选 ' + selectedCount + ' 件,合计 ¥' + (totalCents / 100).toFixed(2);
}
document.getElementById('clear-cart-btn').addEventListener('click', clearCart);
window.addEventListener('DOMContentLoaded', () => {
cart = readCartFromStorage();
renderProducts();
renderCart();
});
</script>
</body>
</html>
如何验证持久化已经生效
打开 cart.html 后,点击商品加入购物车并调整数量,然后打开浏览器开发者工具(F12)切到 Application → Storage → Local Storage(中文界面为“应用 → 存储 → 本地存储”),选中当前域名即可看到对应的键和值。如果此时按下 F5 刷新页面,甚至关闭标签页重新打开,页面仍能还原出之前勾选的商品与数量。
shop_cart_v1[{"id":"sku-1001","name":"纯棉基础款T恤","price":79,"quantity":2,"checked":true},{"id":"sku-1003","name":"陶瓷马克杯","price":45,"quantity":1,"checked":false}]已选 2 件,合计 ¥158.00(按 F5 刷新后显示保持不变)注意上面计算总价时把单价乘以 100 换算成分(整数)再累加,最后除以 100 格式化为两位小数。如果商品单价包含小数(如 19.9),直接用浮点数相乘相加容易出现 39.800000000000004 的展示误差。
四、多标签页数据同步与常见误区排查
用户购物时经常会同时开多个标签页:在列表页点“加入购物车”,切回已经打开的购物车标签页却发现数量没变,因为另一个标签页内存里的 cart 变量还是旧值。只要在 window 上监听 storage 事件,就可以让同源的其他标签页自动跟进更新:
window.addEventListener('storage', (event) => {
// 1. 只处理当前购物车对应的 key;event.key === null 表示调用了 localStorage.clear()
if (event.key !== CART_STORAGE_KEY && event.key !== null) {
return;
}
// 2. 重新从 localStorage 读取并渲染最新状态
cart = readCartFromStorage();
renderCart();
});
使用 storage 事件时有两个细节容易被误解:第一,当前执行 setItem 的那个标签页本身不会触发 storage 事件,浏览器只会通知“同一源下其他处于打开状态的标签页或窗口”;第二,两个页面的协议、域名、端口必须完全一致才会共享同一份 localStorage 并触发同步,例如 http://localhost:5500 与 http://127.0.0.1:5500 在浏览器看来属于不同源,数据互不互通。
调试时常见的三个问题
| 常见现象 | 可能原因 | 排查与处理方式 |
|---|---|---|
| 刷新后商品消失,Storage 面板里没有键值 | 修改了 cart 数组但漏调保存函数,或本地文件以 file:// 方式打开受限 |
检查增删改操作是否都经过 commitCartChange(),并改用本地 HTTP 服务打开测试 |
读取时控制台报错 SyntaxError |
存储值被写成 "[object Object]" 或调试时手动改坏了 JSON 格式 |
清空该 key,确认写入前经过 JSON.stringify(),读取放在 try...catch 中 |
storage 事件监听函数始终不执行 |
只在当前操作的同一标签页测试,或两个标签页协议/端口/域名不一致 | 打开两个同源标签页,在 A 页修改后观察 B 页的界面和控制台 |
五、上线前的清理策略与方案边界
在实际项目中,localStorage 往往承担的是“未登录游客购物车”或“弱网下的本地暂存”角色。如果用户完成了登录,标准流程是把本地读取到的 cart 数组提交到服务端,与账号原有的云端购物车按商品 id 合并,合并成功后再调用 localStorage.removeItem(CART_STORAGE_KEY) 清空本地副本,避免下次切换其他账号登录时把上一位用户的商品带进去。
如果未来需要更换购物车数据结构(例如从单字段 id 拆成 productId 和 skuId),可以把新版本的 key 命名为 shop_cart_v2,并在初始化读取时顺手删除旧键 localStorage.removeItem('shop_cart_v1'),这样既不会导致老用户页面解析崩溃,也不会在用户浏览器里留下无用垃圾数据。
实用工具推荐
绿化、压缩、噪点和虚拟水印,自由调节做旧程度。
选择画质和输出格式,预览压缩前后的大小。