rsgltzyd/testing-tool
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
抽取 themeSnapshot 工具模块，异步恢复与跨窗同步时写回 snapshot；HTML 内联脚本与 useLayoutEffect 消除 dark 类首帧闪烁；避免 storage 恢复覆盖用户操作及 setState 嵌套更新。

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
雨霖铃
2026-06-19 00:45:52 +08:00
parent 8f9ff27034
commit f0292acbb7
8 changed files with 302 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/entrypoints/popup/index.html
+13
View File
@@ -5,6 +5,19 @@
<meta name="viewport" content="width=device-width, initial-scale=1.0" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Testing Tools - 标签页</title> <title>Testing Tools - 标签页</title>
<meta name="manifest.type" content="browser_action" /> <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> <style>
/* Force initial popup size before React hydration */ /* Force initial popup size before React hydration */
html, body { html, body {
src/entrypoints/popup/main.tsx
+3
View File
@@ -1,8 +1,11 @@
import ReactDOM from 'react-dom/client'; import ReactDOM from 'react-dom/client';
import { applyThemeFromSnapshot } from '@/utils/themeSnapshot';
import AppRoot from '@/providers/AppRoot'; import AppRoot from '@/providers/AppRoot';
import '@/index.css'; import '@/index.css';
import App from './App.tsx'; import App from './App.tsx';
applyThemeFromSnapshot();
ReactDOM.createRoot(document.getElementById('root')!).render( ReactDOM.createRoot(document.getElementById('root')!).render(
<AppRoot> <AppRoot>
<App /> <App />
src/entrypoints/sidepanel/index.html
+13
View File
@@ -4,6 +4,19 @@
<meta charset="UTF-8" /> <meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Testing Tools - Side Panel</title> <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> </head>
<body> <body>
<div id="root"></div> <div id="root"></div>
src/entrypoints/sidepanel/main.tsx
+3
View File
@@ -1,8 +1,11 @@
import ReactDOM from 'react-dom/client'; import ReactDOM from 'react-dom/client';
import { applyThemeFromSnapshot } from '@/utils/themeSnapshot';
import AppRoot from '@/providers/AppRoot'; import AppRoot from '@/providers/AppRoot';
import '@/index.css'; import '@/index.css';
import App from './App.tsx'; import App from './App.tsx';
applyThemeFromSnapshot();
ReactDOM.createRoot(document.getElementById('root')!).render( ReactDOM.createRoot(document.getElementById('root')!).render(
<AppRoot> <AppRoot>
<App /> <App />
src/providers/ThemeModeProvider.tsx
+60 -68
View File
@@ -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 { browser } from 'wxt/browser';
import { storageUtil } from '@/utils/chromeStorage'; 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, ThemeMode };
export type ResolvedThemeMode = 'light' | 'dark';
interface ThemeModeContextType { interface ThemeModeContextType {
mode: ThemeMode; mode: ThemeMode;
@@ -13,112 +31,88 @@ interface ThemeModeContextType {
const ThemeModeContext = createContext<ThemeModeContextType | null>(null); 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 { interface ThemeModeProviderProps {
children: ReactNode; children: ReactNode;
} }
export function ThemeModeProvider({ children }: ThemeModeProviderProps) { export function ThemeModeProvider({ children }: ThemeModeProviderProps) {
const [mode, setModeState] = useState<ThemeMode>(getSyncSnapshot); const [mode, setModeState] = useState<ThemeMode>(getThemeSyncSnapshot);
const [resolvedMode, setResolvedMode] = useState<ResolvedThemeMode>( const [resolvedMode, setResolvedMode] = useState<ResolvedThemeMode>(() =>
mode === 'system' ? getSystemMode() : mode, resolveThemeMode(getThemeSyncSnapshot()),
); );
const modeRef = useRef(mode);
const hasUserSetMode = useRef(false);
useEffect(() => {
modeRef.current = mode;
}, [mode]);
const updateResolved = useCallback((nextMode: ThemeMode) => { const updateResolved = useCallback((nextMode: ThemeMode) => {
setResolvedMode(nextMode === 'system' ? getSystemMode() : nextMode); setResolvedMode(resolveThemeMode(nextMode));
}, []); }, []);
const setMode = useCallback( const setMode = useCallback(
(next: ThemeMode) => { (next: ThemeMode) => {
hasUserSetMode.current = true;
setModeState(next); setModeState(next);
updateResolved(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); console.error('[Theme Storage Error] Failed to persistent theme state:', err);
}); });
try { persistThemeModeSnapshot(next);
localStorage.setItem(SNAPSHOT_KEY, JSON.stringify(next));
} catch (err) {
console.error('[Theme Snapshot Error] LocalStorage quota exceeded:', err);
}
}, },
[updateResolved], [updateResolved],
); );
// Sync theme from storage on mount
useEffect(() => { useEffect(() => {
let cancelled = false; let cancelled = false;
storageUtil storageUtil
.get(THEME_MODE_KEY, 'system') .get(THEME_MODE_STORAGE_KEY, 'system')
.then((saved) => { .then((saved) => {
if (cancelled) return; if (cancelled || hasUserSetMode.current) return;
if (isValidMode(saved)) { if (!isValidThemeMode(saved)) return;
setModeState(saved);
updateResolved(saved); setModeState(saved);
} updateResolved(saved);
persistThemeModeSnapshot(saved);
applyResolvedThemeClass(resolveThemeMode(saved));
}) })
.catch((err) => { .catch((err) => {
console.error('[Theme Restore Thread Failed]', err); console.error('[Theme Restore Thread Failed]', err);
}); });
return () => { return () => {
cancelled = true; cancelled = true;
}; };
}, [updateResolved]); }, [updateResolved]);
// Listen for system theme changes when in system mode
useEffect(() => { useEffect(() => {
if (mode !== 'system') return; if (mode !== 'system') return;
const mq = window.matchMedia('(prefers-color-scheme: dark)'); const mq = window.matchMedia('(prefers-color-scheme: dark)');
const handler = (e: MediaQueryListEvent) => { const handler = (event: MediaQueryListEvent) => {
setResolvedMode(e.matches ? 'dark' : 'light'); setResolvedMode(event.matches ? 'dark' : 'light');
}; };
mq.addEventListener('change', handler); mq.addEventListener('change', handler);
return () => mq.removeEventListener('change', handler); return () => mq.removeEventListener('change', handler);
}, [mode]); }, [mode]);
// Sync theme across extension contexts (popup <-> sidepanel)
useEffect(() => { useEffect(() => {
const handleStorageChange = (changes: Record<string, { newValue?: unknown }>) => { const handleStorageChange = (changes: Record<string, { newValue?: unknown }>) => {
if (changes[THEME_MODE_KEY]) { if (!changes[THEME_MODE_STORAGE_KEY]) return;
const next = changes[THEME_MODE_KEY].newValue;
if (isValidMode(next)) { const next = changes[THEME_MODE_STORAGE_KEY].newValue;
setModeState((currentMode) => { if (!isValidThemeMode(next) || next === modeRef.current) return;
if (next !== currentMode) {
updateResolved(next); setModeState(next);
return next; updateResolved(next);
} persistThemeModeSnapshot(next);
return currentMode; applyResolvedThemeClass(resolveThemeMode(next));
});
}
}
}; };
browser.storage.onChanged.addListener(handleStorageChange); browser.storage.onChanged.addListener(handleStorageChange);
@@ -127,10 +121,8 @@ export function ThemeModeProvider({ children }: ThemeModeProviderProps) {
}; };
}, [updateResolved]); }, [updateResolved]);
useEffect(() => { useLayoutEffect(() => {
if (typeof document !== 'undefined') { applyResolvedThemeClass(resolvedMode);
document.documentElement.classList.toggle('dark', resolvedMode === 'dark');
}
}, [resolvedMode]); }, [resolvedMode]);
return ( return (
src/providers/__tests__/ThemeModeProvider.test.tsx
+119
View File
@@ -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);
});
});
src/utils/__tests__/themeSnapshot.test.ts
+41
View File
@@ -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);
});
});
src/utils/themeSnapshot.ts
+50
View File
@@ -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()));
};