实现静态网站暗黑模式的跨会话持久化记忆-html教程-PHP中文网

实现静态网站暗黑模式的跨会话持久化记忆

本文详解如何利用 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（闪屏）。