如何实现HTML页面主题切换及换肤功能？

本文共计883个文字，预计阅读时间需要4分钟。

主题切换不是加个+class+就完事，核心在于CSS+变量+localStorage三者协同，缺一不可。仅改+class+易被其他样式覆盖，仅靠+prefers-color-scheme+会无视用户选择，不存在+localStorage+则刷新即丢失。

用 document.documentElement.dataset.theme 控制主题状态

别碰 body.className 或随意加 class="dark"——它可能和 Tailwind、BEM 或第三方库冲突。统一用 data-theme 属性更语义化、隔离性好：

• document.documentElement.dataset.theme = "dark" 设为深色
• document.documentElement.dataset.theme = "" 清空（等价于浅色）
• CSS 中必须写 html[data-theme="dark"] { ... }，不能漏掉 html 前缀，否则层级可能被子元素样式压住
• 切完立刻触发重绘，无需手动 force reflow，浏览器自动响应变量变化

CSS 变量定义要分层，:root + [data-theme="dark"] 配合写

所有可变颜色、间距、阴影都得从变量取值，否则切换无效。结构必须是：

:root { --bg-color: #ffffff; --text-color: #333333; --border-color: #e0e0e0; } [data-theme="dark"] { --bg-color: #121212; --text-color: #e0e0e0; --border-color: #444444; } body { background-color: var(--bg-color); color: var(--text-color); border-color: var(--border-color); }

注意：[data-theme="dark"] 是选择器，不是媒体查询；它不依赖系统设置，纯由 JS 触发，所以能响应按钮点击。

立即学习“前端免费学习笔记（深入）”；

初始化时必须按优先级读取：localStorage > prefers-color-scheme > 默认值

用户点过按钮，就得记住；没点过，才看系统偏好。常见错误是监听 matchMedia 后自动切，结果用户刚选完“深色”，系统夜间一开又给顶回去。

• 先读 localStorage.getItem("theme")，返回 null 时不能直接赋值给 dataset.theme
• 正确写法：const saved = localStorage.getItem("theme"); document.documentElement.dataset.theme = saved || (window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light");
• 只要写了新值，立刻同步写入：localStorage.setItem("theme", "dark")，字符串即可，别 JSON 化
• 每次设主题后，顺手更新 <meta name="color-scheme">，否则 Safari/Chrome 地址栏、表单控件颜色不一致

按钮必须是 <button> + aria-pressed + 点击事件监听

别用 <input type="checkbox"> + :checked 纯 CSS 实现——它无法持久化、无法响应系统变更、无障碍支持差。

• HTML 中写：<button id="theme-toggle" aria-pressed="false">?</button>
• JS 中切换时同步更新 aria-pressed：btn.setAttribute("aria-pressed", theme === "dark")
• 监听 click，不是 change 或 input
• 额外加一层 window.matchMedia("(prefers-color-scheme: dark)").addEventListener 仅用于「检测系统变更后提示用户」，不要自动切主题

最易忽略的点：所有用到颜色的地方——包括 SVG 的 fill、stroke，按钮的 box-shadow，甚至 hr 的 border-top——都得走 var(--xxx)。漏一个，主题就“破功”。