本文详解如何利用 localstorage 在纯静态 html 网站中持久保存用户选择的亮色/暗色模式状态，确保页面刷新、跳转或重新打开时自动恢复上次偏好，无需后端支持。
本文详解如何利用 localstorage 在纯静态 html 网站中持久保存用户选择的亮色/暗色模式状态，确保页面刷新、跳转或重新打开时自动恢复上次偏好，无需后端支持。
在静态网站中实现「记住上次主题」看似简单，实则需兼顾初始化、状态同步、存储安全与可访问性。核心思路是：将用户手动切换的行为结果（dark-mode 是否启用）序列化为字符串，存入 localStorage；每次页面加载时优先读取该值并还原 DOM 状态。下面是一个生产就绪的完整实现方案。
✅ 基础实现（修复原始代码缺陷）
原始代码仅在点击时切换 class，但未初始化、未持久化、未做类型防护。以下是优化后的 JavaScript：
<script>
const html = document.documentElement; // 推荐用 documentElement 而非 querySelector('html')
const button = document.querySelector('.contrast-toggle');
// ✅ 步骤1：页面加载时读取并应用存储的主题
const savedTheme = localStorage.getItem('dark-mode');
const isDark = savedTheme === 'true'; // 安全解析：避免 'false' 字符串被误判为 true
if (isDark) html.classList.add('dark-mode');
// ✅ 步骤2：绑定切换逻辑，同步更新 DOM 与存储
button.addEventListener('click', (e) => {
e.preventDefault();
const wasDark = html.classList.contains('dark-mode');
html.classList.toggle('dark-mode');
// ✅ 仅当状态实际改变时才写入，减少 storage 事件冗余
if (wasDark !== html.classList.contains('dark-mode')) {
localStorage.setItem('dark-mode', html.classList.contains('dark-mode'));
}
});
</script>? 关键改进说明：
- 使用
document.documentElement更语义化、性能更优；- 显式比较
'true'字符串而非!!savedTheme，防止null/'false'导致误激活；- 切换前比对状态，避免无意义的
setItem（虽不影响功能，但利于调试与多标签页协同）。
? CSS 建议：增强可维护性与渐进增强
推荐采用 data-theme 属性替代纯 class 控制，提升语义性与样式隔离性（尤其当项目未来引入 Tailwind 或 BEM）：
/* 默认亮色主题 */
:root {
--bg-color: #ffffff;
--text-color: #333333;
--link-color: #007bff;
}
/* 暗色主题覆盖 */
html[data-theme="dark"] {
--bg-color: #1a1a1a;
--text-color: #f0f0f0;
--link-color: #00d4ff;
}
body {
background-color: var(--bg-color);
color: var(--text-color);
transition: background-color 0.3s ease, color 0.3s ease;
}
a {
color: var(--link-color);
}对应 JS 初始化改为：
if (isDark) html.dataset.theme = 'dark';
// 切换时：
html.dataset.theme = html.classList.contains('dark-mode') ? 'dark' : 'light';⚙️ 进阶增强（可选但强烈推荐）
-
系统偏好兜底（首次访问友好）
若localStorage为空，可回退至系统设置：const systemPrefersDark = window.matchMedia?.('(prefers-color-scheme: dark)').matches; const isDark = savedTheme !== null ? savedTheme === 'true' : systemPrefersDark; -
多标签页实时同步
在其他标签页切换主题时，当前页也应响应：window.addEventListener('storage', (e) => { if (e.key === 'dark-mode') { const newIsDark = e.newValue === 'true'; html.classList.toggle('dark-mode', newIsDark); html.dataset.theme = newIsDark ? 'dark' : 'light'; } }); -
可访问性支持
为切换按钮添加aria-pressed状态，提升屏幕阅读器体验：button.setAttribute('aria-pressed', isDark); // 切换时同步更新： button.setAttribute('aria-pressed', html.classList.contains('dark-mode'));
⚠️ 注意事项
-
localStorage是同源存储，同一域名下所有页面共享；清除浏览器数据或隐私模式下将丢失； - 不要依赖
prefers-color-scheme作为唯一开关——它只反映系统设置，无法响应用户手动操作； - 避免在
中直接内联脚本，建议置于底部或使用defer； - 若网站支持服务端渲染（SSR），需在 HTML 模板中预设
data-theme，防止 FOUC（闪屏）。
至此，你的静态网站已具备专业级暗色模式持久化能力：轻量、可靠、可扩展，且完全不依赖任何框架或后端服务。
