多页面网站如何实现暗色/亮色主题持久化切换

本文围绕一个实用的需求展开：如何在多页面网站中实现持久化的暗色/亮色主题切换。方案基于 HTML data-* 属性、CSS 自定义属性（CSS Variables）和 localStorage 构建，轻量级、跨页面生效，自动记住用户偏好，并避免页面闪烁。兼容 Bootstrap 5 及现代浏览器。

要让暗色/亮色主题真正“全局生效”且“持久可用”，关键在于三个核心点：首次渲染前确定主题、统一状态管理、样式与 DOM 结构解耦。常见问题包括按钮逻辑混乱（重复 toggle）、CSS 变量未充分利用、localStorage 读写时机不当导致闪屏，以及主题类名（如 light-mode/dark-mode）直接挂在

上，与 Bootstrap 的 .btn-light/.btn-dark 等内置类冲突。

以下提供一套简洁、健壮、可扩展的实现方案，分为三个步骤。

第一步：初始化主题，置于 最顶部

将以下脚本放在 最靠前的位置，确保在 CSS 或其他 JS 加载之前，就将 data-theme 属性设置好。这样 HTML 渲染的第一帧就是正确的主题，彻底杜绝“闪白”或“闪黑”现象。

注意：document.documentElement 指向 根元素，使用 dataset.theme 比操作 类更清晰，且不会影响 Bootstrap 的组件类名。

第二步：声明主题变量与样式（CSS 中）

在主题 CSS 文件（如 Costumisation_Index.css）中，用 CSS 自定义属性定义调色板，再通过 [data-theme="dark"] 选择器覆盖对应变量值。

:root {
  /* 默认为 light 主题 */
  --text-primary: #1B1B1B;
  --bg-primary: #0080FF;
  --btn-outline-color: #3FA9F5;
  --navbar-bg: #000033;
  --footer-bg: #000033;
  --border-color: #fff;
}

[data-theme="dark"] {
  --text-primary: #EDEDED;
  --bg-primary: #00437B;
  --btn-outline-color: #295773;
  --navbar-bg: #0a1929;
  --footer-bg: #0a1929;
  --border-color: #444;
}

/* 全局应用变量 */
body {
  margin: 0;
  padding: 0;
  font-family: Arial, sans-serif;
  color: var(--text-primary);
  background-color: var(--bg-primary);
  transition: background-color 0.5s ease, color 0.5s ease;
}

.navbar {
  background-color: var(--navbar-bg) !important;
}

footer {
  background-color: var(--footer-bg) !important;
}

.btn-outline-light {
  color: var(--btn-outline-color) !important;
  border-color: var(--btn-outline-color) !important;
}

.btn-outline-light:hover {
  background-color: var(--btn-outline-color) !important;
  color: #fff !important;
}

所有颜色均来自变量，无需再写 .light-mode 或 .dark-mode 类，维护成本大幅降低。如需新增主题，只需在 :root 或对应的 [data-theme="..."] 中扩展变量即可。

第三步：绑定按钮事件（DOM 加载后执行）

将以下 JS 放入 LightDarkTheme.js 文件，通过 加载，或放在 关闭之前。

document.addEventListener('DOMContentLoaded', () => {
  // 为所有带有 data-set-theme 属性的按钮绑定事件
  document.querySelectorAll('[data-set-theme]').forEach(btn => {
    btn.addEventListener('click', () => {
      const theme = btn.dataset.setTheme;
      // 同步更新 HTML 根节点与 localStorage
      document.documentElement.dataset.theme = theme;
      localStorage.setItem('theme', theme);
    });
  });
});

同时更新 HTML 按钮结构，使用 btn-outline-primary 和 btn-outline-secondary 避免与 Bootstrap 主题类冲突，图标可增强可访问性。

   Light
   Dark

关键优势总结

这套方案的优势如下：

• 无闪屏：在 中初始化，首帧渲染即为正确主题。
• 跨页面生效：localStorage 加 data-theme，所有页面共享状态，用户只需切换一次。
• 零 CSS 冗余：所有样式基于 :root 和 [data-theme]，未来添加主题只需扩展变量。
• 不侵入 Bootstrap：完全避开 .light-mode 和 .dark-mode 类名，不与 .btn-light 等内置类冲突。
• 语义清晰：data-set-theme 属性明确表达意图，团队协作和维护方便，未来可扩展出 auto 模式。

因此，建议将原有 JS 中所有 classList.toggle('light-mode') 相关逻辑，以及 CSS 中所有 .light-mode / .dark-mode 规则彻底删除。它们已被更优雅的 data-theme 方案取代。完成这三步，你的多页网站即可拥有专业级、无感切换的主题体验。