UI 视觉设计 / 系统课时
运行时切换主题并避免闪屏
运行时切换主题并避免闪屏
让 Web 页面在第一次绘制时就应用正确的浅色或深色令牌,同时提供“跟随系统、浅色、深色”三种选择。完成后,用户刷新页面、修改系统外观或在另一个标签页切换主题,都不会先看到错误配色再突然跳变。
学习目标
- 区分用户保存的主题模式与浏览器实际应用的颜色主题。
- 在首次绘制前写入
data-theme,用 CSS 语义令牌驱动页面。 - 验证刷新、系统偏好变化、跨标签页同步和存储受限的行为。
确定优先级和执行时机
保存的是用户选择的 system、light 或 dark,不是上次算出的深浅结果。首次访问或读取到非法值时,按 system 处理;明确选择的浅色、深色始终优先于系统偏好。
| 已保存模式 | 系统偏好 | 最终 data-theme |
|---|---|---|
light |
任意 | light |
dark |
任意 | dark |
system |
深色 | dark |
system |
浅色 | light |
主题决策必须发生在浏览器首次绘制之前:把一段同步脚本放进 HTML 的 <head>,尽量置于主题 CSS 之前。它先读取 localStorage,再用 matchMedia('(prefers-color-scheme: dark)') 解析实际主题,并立即设置根元素属性。不要等 React 的 useEffect 执行后才首次切换。

写出可直接运行的主题切换页
以下示例面向支持 matchMedia 和 MediaQueryList.addEventListener 的现代浏览器。将代码保存为 index.html,通过本地 HTTP 预览服务打开。首屏脚本既不加 async,也不加 defer;底部脚本只负责给已经出现的选择框绑定交互。
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="color-scheme" content="light dark">
<script>
(() => {
const KEY = "theme-mode";
const valid = new Set(["system", "light", "dark"]);
const media = matchMedia("(prefers-color-scheme: dark)");
let mode = "system";
try {
const saved = localStorage.getItem(KEY);
if (valid.has(saved)) mode = saved;
} catch {
// 存储被限制时退回系统偏好,避免阻断页面加载。
}
function applyTheme() {
const resolved = mode === "system"
? (media.matches ? "dark" : "light")
: mode;
document.documentElement.dataset.theme = resolved;
}
applyTheme(); // 必须早于页面首次绘制。
media.addEventListener("change", () => {
if (mode === "system") applyTheme();
});
window.themeApp = {
getMode: () => mode,
setMode(next) {
if (!valid.has(next)) return;
mode = next;
applyTheme();
try {
localStorage.setItem(KEY, next);
} catch {
// 当前页面仍可切换,只是不保证刷新后保留。
}
}
};
window.addEventListener("storage", (event) => {
if (event.key !== KEY) return;
mode = valid.has(event.newValue) ? event.newValue : "system";
applyTheme();
const select = document.getElementById("theme-mode");
if (select) select.value = mode;
});
})();
</script>
<style>
:root {
--surface: #ffffff;
--text: #18243b;
--action: #2563eb;
color-scheme: light;
}
:root[data-theme="dark"] {
--surface: #0f172a;
--text: #f1f5f9;
--action: #93c5fd;
color-scheme: dark;
}
body {
margin: 0;
padding: 2rem;
min-height: 100vh;
box-sizing: border-box;
font: 16px/1.6 system-ui, sans-serif;
background: var(--surface);
color: var(--text);
}
select { background: var(--surface); color: var(--text); }
a { color: var(--action); }
</style>
</head>
<body>
<label for="theme-mode">主题:</label>
<select id="theme-mode">
<option value="system">跟随系统</option>
<option value="light">浅色</option>
<option value="dark">深色</option>
</select>
<p id="verify">刷新页面、切换系统外观,观察背景与文字。</p>
<a href="#verify">查看验证提示</a>
<script>
const select = document.getElementById("theme-mode");
select.value = window.themeApp.getMode();
select.addEventListener("change", () => {
window.themeApp.setMode(select.value);
});
</script>
</body>
</html>预期结果:首次无保存记录时页面跟随系统;选择“深色”后背景变为 #0f172a、文字变为 #f1f5f9,刷新仍为深色;切回“跟随系统”后,再修改系统外观,页面会自动响应。color-scheme 使原生表单控件采用相应外观,自定义页面颜色仍由 CSS 变量决定。
用真实操作检查首屏与响应
- 在浏览器开发者工具的 Application → Local storage 中删除当前站点的
theme-mode,系统设为深色后刷新;页面和选择框应分别显示深色与“跟随系统”。 - 保持系统深色,手动选“浅色”并刷新;根元素应是
<html data-theme="light">,页面保持浅色,不被系统偏好覆盖。 - 选择“跟随系统”,在页面打开期间切换系统深浅色;背景应随之变化。再手动选“深色”并修改系统外观,页面不应跟随。
- 同源打开两个标签页,在其中一个切换主题,另一个应同步;
storage事件只通知其他文档,当前页要靠setMode立即更新。 - 使用开发者工具 Performance 面板录制刷新过程,检查首次绘制对应的屏幕截图;不应出现一帧浅色之后才切到深色。若存储被浏览器禁用,页面应正常打开并默认跟随系统,但选择可能无法跨刷新保存。
避免上线后才出现的闪屏
不要仅在组件挂载后调用 localStorage 并修改类名:首次渲染可能已使用默认主题。也不要在深色媒体查询中无条件覆盖根元素的浅色令牌,否则用户显式选“浅色”仍会被系统深色抢占。本例让 data-theme 成为配色的唯一入口,媒体查询只参与 system 的决策。
有严格内容安全策略(CSP)的站点,内联脚本若未获得允许将不能执行;应为早期脚本配置有效的 nonce 或哈希,或让服务器依据一致的偏好 Cookie 直接输出主题属性。服务端渲染应用也要保证早期主题设置先于首绘,不要在 hydration 时再无条件覆盖它。