本文介绍一种基于 HTML data-* 属性、CSS 自定义属性（CSS Variables）与 localStorage 的轻量级、跨页面主题切换方案，支持自动记忆用户偏好，并避免页面闪烁，兼容 Bootstrap 5 及现代浏览器。
本文介绍一种基于 html `data-*` 属性、css 自定义属性（css variables）与 localstorage 的轻量级、跨页面主题切换方案，支持自动记忆用户偏好，并避免页面闪烁，兼容 bootstrap 5 及现代浏览器。
要让暗色/亮色主题真正“全局生效”且“持久可用”，关键在于三点：首次渲染前即确定主题、统一状态管理、样式解耦于 DOM 结构。你当前的实现存在几个核心问题：按钮逻辑混乱（重复 toggle）、未利用 CSS 变量实现样式复用、localStorage 读写时机不当导致闪屏、且主题类（如 light-mode/dark-mode）直接作用于 <body> 会与 Bootstrap 的 .btn-light/.btn-dark 等内置类冲突。
下面提供一套简洁、健壮、可扩展的实现方案：
✅ 正确做法：三步构建可持久化主题系统
1. 初始化主题（置于 <head> 最顶部）
将以下脚本严格放在 <head> 内首个位置（在任何 CSS 或其他 JS 加载前），确保 HTML 渲染前就设置好 data-theme 属性，彻底杜绝“闪白”或“闪黑”：
<head>
<script>
const setTheme = (theme) => {
theme ??= localStorage.getItem('theme') || 'light';
document.documentElement.dataset.theme = theme;
localStorage.setItem('theme', theme);
};
setTheme(); // 立即执行，锁定初始主题
</script>
<!-- 其他 meta、link、script 均在此之后 -->
</head>⚠️ 注意：document.documentElement 指向 <html> 根元素，使用 dataset.theme 比操作 <body> 类更语义清晰，且不影响 Bootstrap 组件类名。
2. 声明主题变量与样式（CSS 中）
在你的 Costumisation_Index.css（或统一主题 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 类，维护成本大幅降低。
3. 绑定按钮事件（DOM 加载后执行）
将以下 JS 放入 LightDarkTheme.js，并确保其通过 <script defer> 加载（或置于 </body> 前）：
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-light/.btn-dark）：
<div class="theme-buttons position-absolute end-0 me-3 mt-3"> <button type="button" class="btn btn-sm btn-outline-primary" data-set-theme="light">☀️ Light</button> <button type="button" class="btn btn-sm btn-outline-secondary ms-2" data-set-theme="dark">? Dark</button> </div>
✅ 使用 btn-outline-primary/btn-outline-secondary 避免与 Bootstrap 主题类冲突；图标增强可访问性；ms-2 提供间距更符合 Bootstrap 5 推荐写法。
? 关键优势总结
- 无闪屏：<head> 中初始化确保首帧即渲染正确主题；
- 跨页面生效：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 方案取代。完成以上三步，你的多页网站即可拥有专业级、无感切换的主题体验。
