HTML / CSS / 系统课时
实现主题切换
实现主题切换
主题切换的关键不是给每个组件分别改样式,而是把当前主题收敛为根节点上的单一状态,再让 dark: 变体向整棵页面树传播。本课将完成可持久化、支持系统偏好且刷新后不闪回默认主题的明暗切换。
学习目标
- 理解类名切换与属性切换的状态来源。
- 使用
dark:变体完成页面样式联动。 - 保存用户选择,并在首次访问时回退到系统偏好。
选择唯一的主题状态源
最稳妥的做法是把主题状态放在 <html> 根元素上。类名方案使用 .dark,属性方案可以使用 data-theme="dark";两者不要同时作为业务状态源,否则按钮、系统偏好与持久化数据可能互相覆盖。本课采用 .dark,因为组件只需编写 dark:bg-*、dark:text-* 等变体。
主题初始化应遵循固定优先级:先读取用户已保存的选择,没有记录时再读取 prefers-color-scheme。用户点击按钮后,只更新根元素、localStorage 和按钮文案,组件本身不保存主题状态。

配置 dark 变体
下面以 Tailwind CSS 的 CSS 入口文件为例,把 dark: 变体绑定到根节点上的 .dark 类。项目需要先具备正常的 Tailwind 编译流程;若现有版本已经在其他位置声明了相同变体,不要重复定义。
@import "tailwindcss";
/* 根元素或任意祖先存在 .dark 时,启用 dark: 变体 */
@custom-variant dark (&:where(.dark, .dark *));生效后,bg-white dark:bg-slate-950 会编译为两套规则,是否启用暗色规则由祖先节点上的 .dark 决定。验证时可在浏览器开发者工具中手动给 <html> 添加和删除 dark,确认页面样式同步变化。
完成可持久化切换
下面的页面在脚本启动时先应用主题,再绑定按钮事件。初始化脚本放在 <head> 中,可以在主要内容绘制前设置根类名,减少刷新时短暂显示错误主题的现象。
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>主题切换示例</title>
<link rel="stylesheet" href="./dist.css">
<script>
const savedTheme = localStorage.getItem("theme");
const systemDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
const initialTheme = savedTheme ?? (systemDark ? "dark" : "light");
// 在页面绘制前设置根状态,避免刷新时先亮后暗
document.documentElement.classList.toggle("dark", initialTheme === "dark");
document.documentElement.style.colorScheme = initialTheme;
</script>
</head>
<body class="min-h-screen bg-slate-50 text-slate-900 transition-colors dark:bg-slate-950 dark:text-slate-100">
<main class="mx-auto max-w-xl p-6">
<button id="themeButton"
class="rounded-lg bg-sky-600 px-4 py-2 text-white hover:bg-sky-700 dark:bg-sky-500 dark:hover:bg-sky-400">
切换主题
</button>
<section class="mt-6 rounded-xl border border-slate-200 bg-white p-6 shadow-sm dark:border-slate-800 dark:bg-slate-900">
<h1 class="text-2xl font-semibold">主题预览</h1>
<p class="mt-2 text-slate-600 dark:text-slate-300">背景、文字、边框和按钮会一起切换。</p>
</section>
</main>
<script>
const button = document.querySelector("#themeButton");
function syncButtonText() {
const isDark = document.documentElement.classList.contains("dark");
button.textContent = isDark ? "切换到明亮主题" : "切换到暗色主题";
}
button.addEventListener("click", () => {
const nextIsDark = !document.documentElement.classList.contains("dark");
document.documentElement.classList.toggle("dark", nextIsDark);
document.documentElement.style.colorScheme = nextIsDark ? "dark" : "light";
localStorage.setItem("theme", nextIsDark ? "dark" : "light");
syncButtonText();
});
syncButtonText();
</script>
</body>
</html>预期结果
首次访问:没有保存记录时跟随操作系统主题。
点击按钮:页面背景、文字、边框和按钮立即切换。
刷新页面:继续使用用户最后一次选择的主题。处理常见边界
不要只修改 <body> 的类名,因为弹窗、原生表单控件或挂载到根节点外的组件可能无法继承一致状态。设置 colorScheme 可以让滚动条和部分原生控件更贴合当前主题,但它不能替代 dark: 样式。
若产品需要“跟随系统”第三种选项,应删除 localStorage 中的固定主题,并监听 matchMedia 的 change 事件;只有处于跟随系统模式时才响应系统变化,避免覆盖用户主动选择。