fix(ThemeModeProvider): 修复主题快照同步与首屏闪烁问题

抽取 themeSnapshot 工具模块，异步恢复与跨窗同步时写回 snapshot；HTML 内联脚本与 useLayoutEffect 消除 dark 类首帧闪烁；避免 storage 恢复覆盖用户操作及 setState 嵌套更新。 Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-19 00:45:52 +08:00
parent 8f9ff27034
commit f0292acbb7
8 changed files with 302 additions and 68 deletions
@@ -5,6 +5,19 @@
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Testing Tools - 标签页</title>
    <meta name="manifest.type" content="browser_action" />
+    <script>
+      (function () {
+        try {
+          var raw = localStorage.getItem('snapshot/app/themeMode');
+          var mode = raw ? JSON.parse(raw) : 'system';
+          if (mode !== 'light' && mode !== 'dark' && mode !== 'system') mode = 'system';
+          var isDark =
+            mode === 'dark' ||
+            (mode === 'system' && window.matchMedia('(prefers-color-scheme: dark)').matches);
+          if (isDark) document.documentElement.classList.add('dark');
+        } catch (_error) {}
+      })();
+    </script>
    <style>
      /* Force initial popup size before React hydration */
      html, body {
@@ -1,8 +1,11 @@
 import ReactDOM from 'react-dom/client';
+import { applyThemeFromSnapshot } from '@/utils/themeSnapshot';
 import AppRoot from '@/providers/AppRoot';
 import '@/index.css';
 import App from './App.tsx';

+applyThemeFromSnapshot();
+
 ReactDOM.createRoot(document.getElementById('root')!).render(
  <AppRoot>
    <App />
@@ -4,6 +4,19 @@
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Testing Tools - Side Panel</title>
+    <script>
+      (function () {
+        try {
+          var raw = localStorage.getItem('snapshot/app/themeMode');
+          var mode = raw ? JSON.parse(raw) : 'system';
+          if (mode !== 'light' && mode !== 'dark' && mode !== 'system') mode = 'system';
+          var isDark =
+            mode === 'dark' ||
+            (mode === 'system' && window.matchMedia('(prefers-color-scheme: dark)').matches);
+          if (isDark) document.documentElement.classList.add('dark');
+        } catch (_error) {}
+      })();
+    </script>
  </head>
  <body>
    <div id="root"></div>
@@ -1,8 +1,11 @@
 import ReactDOM from 'react-dom/client';
+import { applyThemeFromSnapshot } from '@/utils/themeSnapshot';
 import AppRoot from '@/providers/AppRoot';
 import '@/index.css';
 import App from './App.tsx';

+applyThemeFromSnapshot();
+
 ReactDOM.createRoot(document.getElementById('root')!).render(
  <AppRoot>
    <App />
@@ -1,9 +1,27 @@
-import { createContext, ReactNode, useCallback, useContext, useEffect, useState } from 'react';
+import {
+  createContext,
+  ReactNode,
+  useCallback,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from 'react';
 import { browser } from 'wxt/browser';
 import { storageUtil } from '@/utils/chromeStorage';
+import {
+  applyResolvedThemeClass,
+  getThemeSyncSnapshot,
+  isValidThemeMode,
+  persistThemeModeSnapshot,
+  resolveThemeMode,
+  THEME_MODE_STORAGE_KEY,
+  type ResolvedThemeMode,
+  type ThemeMode,
+} from '@/utils/themeSnapshot';

-export type ThemeMode = 'light' | 'dark' | 'system';
-export type ResolvedThemeMode = 'light' | 'dark';
+export type { ResolvedThemeMode, ThemeMode };

 interface ThemeModeContextType {
  mode: ThemeMode;
@@ -13,112 +31,88 @@ interface ThemeModeContextType {

 const ThemeModeContext = createContext<ThemeModeContextType | null>(null);

-const THEME_MODE_KEY = 'app/themeMode' as const;
-const SNAPSHOT_KEY = 'snapshot/app/themeMode';
-
-const VALID_MODES: ThemeMode[] = ['light', 'dark', 'system'];
-const isValidMode = (v: unknown): v is ThemeMode => VALID_MODES.includes(v as ThemeMode);
-
-/**
- * 同步追溯 localStorage 级快照（首屏 0 闪烁核心防线）
- */
-const getSyncSnapshot = (): ThemeMode => {
-  try {
-    const raw = localStorage.getItem(SNAPSHOT_KEY);
-    if (!raw) return 'system';
-    const parsed = JSON.parse(raw) as unknown;
-    return isValidMode(parsed) ? parsed : 'system';
-  } catch {
-    return 'system';
-  }
-};
-
-/**
- * 实时嗅探系统底层操作系统的明暗色轴
- */
-const getSystemMode = (): ResolvedThemeMode => {
-  if (typeof window === 'undefined') return 'light';
-  return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
-};
-
 interface ThemeModeProviderProps {
  children: ReactNode;
 }

 export function ThemeModeProvider({ children }: ThemeModeProviderProps) {
-  const [mode, setModeState] = useState<ThemeMode>(getSyncSnapshot);
-  const [resolvedMode, setResolvedMode] = useState<ResolvedThemeMode>(
-    mode === 'system' ? getSystemMode() : mode,
+  const [mode, setModeState] = useState<ThemeMode>(getThemeSyncSnapshot);
+  const [resolvedMode, setResolvedMode] = useState<ResolvedThemeMode>(() =>
+    resolveThemeMode(getThemeSyncSnapshot()),
  );
+  const modeRef = useRef(mode);
+  const hasUserSetMode = useRef(false);
+
+  useEffect(() => {
+    modeRef.current = mode;
+  }, [mode]);

  const updateResolved = useCallback((nextMode: ThemeMode) => {
-    setResolvedMode(nextMode === 'system' ? getSystemMode() : nextMode);
+    setResolvedMode(resolveThemeMode(nextMode));
  }, []);

  const setMode = useCallback(
    (next: ThemeMode) => {
+      hasUserSetMode.current = true;
      setModeState(next);
      updateResolved(next);
+      applyResolvedThemeClass(resolveThemeMode(next));

-      void storageUtil.set(THEME_MODE_KEY, next).catch((err) => {
+      void storageUtil.set(THEME_MODE_STORAGE_KEY, next).catch((err) => {
        console.error('[Theme Storage Error] Failed to persistent theme state:', err);
      });

-      try {
-        localStorage.setItem(SNAPSHOT_KEY, JSON.stringify(next));
-      } catch (err) {
-        console.error('[Theme Snapshot Error] LocalStorage quota exceeded:', err);
-      }
+      persistThemeModeSnapshot(next);
    },
    [updateResolved],
  );

-  // Sync theme from storage on mount
  useEffect(() => {
    let cancelled = false;
+
    storageUtil
-      .get(THEME_MODE_KEY, 'system')
+      .get(THEME_MODE_STORAGE_KEY, 'system')
      .then((saved) => {
-        if (cancelled) return;
-        if (isValidMode(saved)) {
-          setModeState(saved);
-          updateResolved(saved);
-        }
+        if (cancelled || hasUserSetMode.current) return;
+        if (!isValidThemeMode(saved)) return;
+
+        setModeState(saved);
+        updateResolved(saved);
+        persistThemeModeSnapshot(saved);
+        applyResolvedThemeClass(resolveThemeMode(saved));
      })
      .catch((err) => {
        console.error('[Theme Restore Thread Failed]', err);
      });
+
    return () => {
      cancelled = true;
    };
  }, [updateResolved]);

-  // Listen for system theme changes when in system mode
  useEffect(() => {
    if (mode !== 'system') return;
+
    const mq = window.matchMedia('(prefers-color-scheme: dark)');
-    const handler = (e: MediaQueryListEvent) => {
-      setResolvedMode(e.matches ? 'dark' : 'light');
+    const handler = (event: MediaQueryListEvent) => {
+      setResolvedMode(event.matches ? 'dark' : 'light');
    };
+
    mq.addEventListener('change', handler);
    return () => mq.removeEventListener('change', handler);
  }, [mode]);

-  // Sync theme across extension contexts (popup <-> sidepanel)
  useEffect(() => {
    const handleStorageChange = (changes: Record<string, { newValue?: unknown }>) => {
-      if (changes[THEME_MODE_KEY]) {
-        const next = changes[THEME_MODE_KEY].newValue;
-        if (isValidMode(next)) {
-          setModeState((currentMode) => {
-            if (next !== currentMode) {
-              updateResolved(next);
-              return next;
-            }
-            return currentMode;
-          });
-        }
-      }
+      if (!changes[THEME_MODE_STORAGE_KEY]) return;
+
+      const next = changes[THEME_MODE_STORAGE_KEY].newValue;
+      if (!isValidThemeMode(next) || next === modeRef.current) return;
+
+      setModeState(next);
+      updateResolved(next);
+      persistThemeModeSnapshot(next);
+      applyResolvedThemeClass(resolveThemeMode(next));
    };

    browser.storage.onChanged.addListener(handleStorageChange);
@@ -127,10 +121,8 @@ export function ThemeModeProvider({ children }: ThemeModeProviderProps) {
    };
  }, [updateResolved]);

-  useEffect(() => {
-    if (typeof document !== 'undefined') {
-      document.documentElement.classList.toggle('dark', resolvedMode === 'dark');
-    }
+  useLayoutEffect(() => {
+    applyResolvedThemeClass(resolvedMode);
  }, [resolvedMode]);

  return (
@@ -0,0 +1,119 @@
+import { act, render, screen, waitFor } from '@testing-library/react';
+import { browser } from 'wxt/browser';
+import { ThemeModeProvider, useThemeMode } from '@/providers/ThemeModeProvider';
+import { storageUtil } from '@/utils/chromeStorage';
+import { THEME_MODE_SNAPSHOT_KEY, THEME_MODE_STORAGE_KEY } from '@/utils/themeSnapshot';
+
+vi.mock('@/utils/chromeStorage', () => ({
+  storageUtil: {
+    get: vi.fn(),
+    set: vi.fn(() => Promise.resolve()),
+  },
+}));
+
+const TestComponent = () => {
+  const { mode, resolvedMode, setMode } = useThemeMode();
+  return (
+    <div>
+      <div data-testid="mode">{mode}</div>
+      <div data-testid="resolved-mode">{resolvedMode}</div>
+      <button type="button" data-testid="set-dark" onClick={() => setMode('dark')}>
+        Set Dark
+      </button>
+    </div>
+  );
+};
+
+describe('ThemeModeProvider', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    localStorage.clear();
+    document.documentElement.classList.remove('dark');
+    (storageUtil.get as ReturnType<typeof vi.fn>).mockImplementation(
+      (_key: string, defaultValue: unknown) => Promise.resolve(defaultValue),
+    );
+  });
+
+  it('应从 localStorage 快照初始化主题', () => {
+    localStorage.setItem(THEME_MODE_SNAPSHOT_KEY, JSON.stringify('dark'));
+
+    render(
+      <ThemeModeProvider>
+        <TestComponent />
+      </ThemeModeProvider>,
+    );
+
+    expect(screen.getByTestId('mode')).toHaveTextContent('dark');
+    expect(screen.getByTestId('resolved-mode')).toHaveTextContent('dark');
+    expect(document.documentElement.classList.contains('dark')).toBe(true);
+  });
+
+  it('异步恢复 storage 后应写回 snapshot', async () => {
+    (storageUtil.get as ReturnType<typeof vi.fn>).mockResolvedValue('dark');
+
+    render(
+      <ThemeModeProvider>
+        <TestComponent />
+      </ThemeModeProvider>,
+    );
+
+    await waitFor(() => {
+      expect(localStorage.getItem(THEME_MODE_SNAPSHOT_KEY)).toBe(JSON.stringify('dark'));
+    });
+  });
+
+  it('用户已切换主题时不应被较慢的 storage 恢复覆盖', async () => {
+    let resolveStorage: (value: 'light' | 'dark' | 'system') => void;
+    const storagePromise = new Promise<'light' | 'dark' | 'system'>((resolve) => {
+      resolveStorage = resolve;
+    });
+
+    (storageUtil.get as ReturnType<typeof vi.fn>).mockImplementation(() => storagePromise);
+
+    render(
+      <ThemeModeProvider>
+        <TestComponent />
+      </ThemeModeProvider>,
+    );
+
+    await act(async () => {
+      screen.getByTestId('set-dark').click();
+    });
+
+    expect(screen.getByTestId('mode')).toHaveTextContent('dark');
+
+    await act(async () => {
+      resolveStorage!('light');
+      await storagePromise;
+    });
+
+    expect(screen.getByTestId('mode')).toHaveTextContent('dark');
+  });
+
+  it('storage.onChanged 同步时应更新 mode 与 snapshot', async () => {
+    (storageUtil.get as ReturnType<typeof vi.fn>).mockResolvedValue('system');
+
+    render(
+      <ThemeModeProvider>
+        <TestComponent />
+      </ThemeModeProvider>,
+    );
+
+    await waitFor(() => {
+      expect(browser.storage.onChanged.addListener).toHaveBeenCalled();
+    });
+
+    const storageChangeHandler = vi.mocked(browser.storage.onChanged.addListener).mock
+      .calls[0][0] as (changes: Record<string, { newValue?: unknown }>) => void;
+
+    await act(async () => {
+      storageChangeHandler({
+        [THEME_MODE_STORAGE_KEY]: { newValue: 'dark' },
+      });
+    });
+
+    expect(screen.getByTestId('mode')).toHaveTextContent('dark');
+    expect(localStorage.getItem(THEME_MODE_SNAPSHOT_KEY)).toBe(JSON.stringify('dark'));
+    expect(document.documentElement.classList.contains('dark')).toBe(true);
+  });
+});
@@ -0,0 +1,41 @@
+import {
+  applyResolvedThemeClass,
+  applyThemeFromSnapshot,
+  getThemeSyncSnapshot,
+  persistThemeModeSnapshot,
+  resolveThemeMode,
+  THEME_MODE_SNAPSHOT_KEY,
+} from '@/utils/themeSnapshot';
+
+describe('themeSnapshot', () => {
+  beforeEach(() => {
+    localStorage.clear();
+    document.documentElement.classList.remove('dark');
+  });
+
+  it('应从未知快照值回退到 system', () => {
+    localStorage.setItem(THEME_MODE_SNAPSHOT_KEY, JSON.stringify('invalid'));
+    expect(getThemeSyncSnapshot()).toBe('system');
+  });
+
+  it('resolveThemeMode 应解析 system 为当前系统主题', () => {
+    vi.spyOn(window, 'matchMedia').mockReturnValue({
+      matches: true,
+    } as MediaQueryList);
+
+    expect(resolveThemeMode('dark')).toBe('dark');
+    expect(resolveThemeMode('system')).toBe('dark');
+  });
+
+  it('applyThemeFromSnapshot 应根据快照同步 dark 类', () => {
+    persistThemeModeSnapshot('dark');
+    applyThemeFromSnapshot();
+    expect(document.documentElement.classList.contains('dark')).toBe(true);
+  });
+
+  it('applyResolvedThemeClass 移除 dark 时应清理 class', () => {
+    document.documentElement.classList.add('dark');
+    applyResolvedThemeClass('light');
+    expect(document.documentElement.classList.contains('dark')).toBe(false);
+  });
+});
@@ -0,0 +1,50 @@
+export type ThemeMode = 'light' | 'dark' | 'system';
+export type ResolvedThemeMode = 'light' | 'dark';
+
+export const THEME_MODE_STORAGE_KEY = 'app/themeMode' as const;
+export const THEME_MODE_SNAPSHOT_KEY = 'snapshot/app/themeMode';
+
+const VALID_MODES: ThemeMode[] = ['light', 'dark', 'system'];
+
+export const isValidThemeMode = (value: unknown): value is ThemeMode =>
+  VALID_MODES.includes(value as ThemeMode);
+
+/**
+ * 同步读取 localStorage 快照（首屏防闪烁）
+ */
+export const getThemeSyncSnapshot = (): ThemeMode => {
+  try {
+    const raw = localStorage.getItem(THEME_MODE_SNAPSHOT_KEY);
+    if (!raw) return 'system';
+    const parsed = JSON.parse(raw) as unknown;
+    return isValidThemeMode(parsed) ? parsed : 'system';
+  } catch {
+    return 'system';
+  }
+};
+
+export const getSystemThemeMode = (): ResolvedThemeMode => {
+  if (typeof window === 'undefined') return 'light';
+  return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+};
+
+export const resolveThemeMode = (mode: ThemeMode): ResolvedThemeMode =>
+  mode === 'system' ? getSystemThemeMode() : mode;
+
+export const persistThemeModeSnapshot = (mode: ThemeMode): void => {
+  try {
+    localStorage.setItem(THEME_MODE_SNAPSHOT_KEY, JSON.stringify(mode));
+  } catch (error) {
+    console.error('[Theme Snapshot Error] LocalStorage quota exceeded:', error);
+  }
+};
+
+export const applyResolvedThemeClass = (resolved: ResolvedThemeMode): void => {
+  if (typeof document === 'undefined') return;
+  document.documentElement.classList.toggle('dark', resolved === 'dark');
+};
+
+/** 在 React 挂载前同步应用快照主题，避免首帧闪烁 */
+export const applyThemeFromSnapshot = (): void => {
+  applyResolvedThemeClass(resolveThemeMode(getThemeSyncSnapshot()));
+};