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;底部脚本只负责给已经出现的选择框绑定交互。

html
<!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 变量决定。

用真实操作检查首屏与响应

  1. 在浏览器开发者工具的 Application → Local storage 中删除当前站点的 theme-mode,系统设为深色后刷新;页面和选择框应分别显示深色与“跟随系统”。
  2. 保持系统深色,手动选“浅色”并刷新;根元素应是 <html data-theme="light">,页面保持浅色,不被系统偏好覆盖。
  3. 选择“跟随系统”,在页面打开期间切换系统深浅色;背景应随之变化。再手动选“深色”并修改系统外观,页面不应跟随。
  4. 同源打开两个标签页,在其中一个切换主题,另一个应同步;storage 事件只通知其他文档,当前页要靠 setMode 立即更新。
  5. 使用开发者工具 Performance 面板录制刷新过程,检查首次绘制对应的屏幕截图;不应出现一帧浅色之后才切到深色。若存储被浏览器禁用,页面应正常打开并默认跟随系统,但选择可能无法跨刷新保存。

避免上线后才出现的闪屏

不要仅在组件挂载后调用 localStorage 并修改类名:首次渲染可能已使用默认主题。也不要在深色媒体查询中无条件覆盖根元素的浅色令牌,否则用户显式选“浅色”仍会被系统深色抢占。本例让 data-theme 成为配色的唯一入口,媒体查询只参与 system 的决策。

有严格内容安全策略(CSP)的站点,内联脚本若未获得允许将不能执行;应为早期脚本配置有效的 nonce 或哈希,或让服务器依据一致的偏好 Cookie 直接输出主题属性。服务端渲染应用也要保证早期主题设置先于首绘,不要在 hydration 时再无条件覆盖它。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

运行时切换主题并避免闪屏

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通