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

本文围绕一个非常实用的前端需求展开——在多页面网站中实现持久化暗色/亮色主题切换。方案基于 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;
  --na vbar-bg: #000033;
  --footer-bg: #000033;
  --border-color: #fff;
}

[data-theme="dark"] {
  --text-primary: #EDEDED;
  --bg-primary: #00437B;
  --btn-outline-color: #295773;
  --na vbar-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;
}

na vbar {
  background-color: var(--na vbar-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 文件，通过