本文详解如何在纯静态 html 网站中，利用浏览器 localstorage 记住用户最后一次选择的明暗主题（如 dark-mode），确保页面刷新、跳转或重新打开时自动恢复原设置，无需后端支持。
本文详解如何在纯静态 html 网站中，利用浏览器 localstorage 记住用户最后一次选择的明暗主题（如 dark-mode），确保页面刷新、跳转或重新打开时自动恢复原设置，无需后端支持。
实现暗黑模式的「记忆能力」，核心在于将用户操作转化为可持久化的状态存储。对于静态网站而言，localStorage 是最轻量、兼容性最佳（IE8+ 及所有现代浏览器均支持）、且无需服务端参与的理想方案。它以键值对形式在同源下长期保存数据，恰好适配主题偏好这类低频变更、高复用性的用户设置。
以下是一个完整、健壮、可直接集成的实现方案：
✅ 1. 初始化：页面加载时读取并应用历史设置
在 DOM 加载完成后，立即检查 localStorage 中是否已存有 'dark-mode' 键，并安全解析其值（注意：localStorage 只能存储字符串）：
document.addEventListener('DOMContentLoaded', () => {
const html = document.documentElement; // 推荐使用 documentElement 而非 body，语义更准确
const button = document.querySelector('.contrast-toggle');
const saved = localStorage.getItem('dark-mode');
// 安全解析布尔值：避免 'true'/'false' 字符串误判，统一用 JSON.parse
const isDark = saved ? JSON.parse(saved) : false;
// 应用主题类（推荐 toggle + boolean 第二参数，更清晰可靠）
html.classList.toggle('dark-mode', isDark);
// 同步更新按钮的可访问性状态（提升无障碍体验）
if (button) {
button.setAttribute('aria-pressed', isDark);
}
});
✅ 2. 切换时：实时保存 + 状态同步
点击按钮时，不仅切换 DOM 类，还需立即将新状态序列化后写入 localStorage：
button?.addEventListener('click', (e) => {
e.preventDefault();
const html = document.documentElement;
const isCurrentlyDark = html.classList.contains('dark-mode');
// 翻转主题
html.classList.toggle('dark-mode');
// 保存新状态（使用 JSON.stringify 确保布尔值正确存储）
localStorage.setItem('dark-mode', JSON.stringify(!isCurrentlyDark));
// 更新按钮 ARIA 状态
button.setAttribute('aria-pressed', !isCurrentlyDark);
});
✅ 3. 进阶增强（强烈推荐）
为提升专业性与用户体验，建议补充以下三点：
-
兜底系统偏好：首次访问且无本地记录时，可优雅降级至系统设置：
const systemPrefersDark = window.matchMedia?.('(prefers-color-scheme: dark)').matches; const isDark = saved !== null ? JSON.parse(saved) : systemPrefersDark; -
多标签页同步：监听
storage事件，使其他同源标签页也能响应主题变更：window.addEventListener('storage', (e) => { if (e.key === 'dark-mode') { const html = document.documentElement; const isDark = e.newValue ? JSON.parse(e.newValue) : false; html.classList.toggle('dark-mode', isDark); // 如有按钮，也同步更新 aria-pressed } }); -
CSS 渐进增强：避免样式闪动（FOUC），建议在
标签上预设data-theme属性，并在 CSS 中使用属性选择器：html[data-theme='dark'] body { background: #000; color: #fff; } html[data-theme='light'] body { background: #fff; color: #000; }对应 JS 更新方式改为：
document.documentElement.dataset.theme = isDark ? 'dark' : 'light';
⚠️ 注意事项
-
localStorage属于客户端存储，用户清除浏览器数据后状态丢失——这是设计使然，非缺陷；若需永久绑定，才需引入服务端用户偏好系统。 - 避免直接比较字符串
=== 'true'，因localStorage存储值可能被意外篡改为'1'或'on'；始终用JSON.parse()安全反序列化。 - 不要依赖
prefers-color-scheme媒体查询作为切换逻辑主体——它仅反映系统设置，无法响应用户主动点击，二者应正交使用（系统设默认值，用户操作覆盖并持久化）。
通过以上实现，你的静态网站即可拥有媲美现代 SPA 的主题记忆能力：零后端、零构建工具、开箱即用，且完全符合 Web 标准与可访问性规范。
