真正高效的主题管理必须对齐CSS变量、React Context和DOM属性；仅设data-theme无法触发Context更新和组件重渲染，需用MutationObserver监听并同步状态，避免频繁getComputedStyle阻塞主线程。
直接改 document.documentElement.setAttribute('data-theme', 'dark') 就能切换主题，但只靠这一步，useContext 拿不到当前主题、组件不会重渲染、暗色模式下 getComputedStyle 读变量可能卡顿——真正高效的主题管理，必须把 CSS 变量、React Context 和 DOM 属性三者对齐。
为什么不能只靠 document.documentElement.setAttribute
单纯设置 data-theme 能触发 CSS 变量更新，但 React 组件并不感知这个变化。比如你写了 const theme = useContext(ThemeContext)，却没在 data-theme 改变时同步更新 Context 值，组件里读到的还是旧主题；另外，频繁调用 getComputedStyle(document.documentElement).getPropertyValue('--color-bg') 会阻塞主线程，尤其在滚动或动画中明显掉帧。
- Context 不响应 DOM 属性变更，需手动监听
mutationObserver或用useEffect+matchMedia同步 -
getComputedStyle是同步强制重排，应仅在初始化或明确需要读取时调用，避免在 render 中反复读 - CSS 变量本身不触发 React 更新，必须让状态变更驱动 re-render，否则样式变了、JS 逻辑还按旧值跑
如何让 ThemeContext 与 data-theme 实时同步
核心是用 useEffect 监听根元素属性变化，并把当前 data-theme 值作为 Context 的 source of truth。不要在 Context Provider 里存冗余状态，而是每次从 DOM 读取，确保 JS 和 CSS 一致。
- Provider 内部用
useState(() => document.documentElement.getAttribute('data-theme') || 'light')初始化 - 用
useEffect订阅document.documentElement的attribute变更：observer.observe(root, { attributes: true, attributeFilter: ['data-theme'] }) - 回调里调用
setState(root.getAttribute('data-theme'))，触发所有useContext组件更新 - 暴露的
toggleTheme函数只需做两件事：改data-theme、触发系统级偏好同步（如localStorage和prefers-color-scheme）
组件内安全读取和使用 CSS 变量的三种方式
别在 JSX 里写 style={{ backgroundColor: getComputedStyle(...).getPropertyValue(...) }}。优先级从高到低：CSS 变量直用 > useTheme Hook 封装读取 > 极少数需 JS 运算时缓存读取结果。
Orderly React SDK 钩子使用参考指南，包括 useOrderEntry、usePositionStream、useOrderbookStream、useCollateral 等。
立即学习“前端免费学习笔记（深入）”；
- 纯样式场景：直接在 CSS 中用
var(--color-bg)，零 JS 开销，支持 SSR 和 DevTools 调试 - 需要条件逻辑时（如根据主题决定是否加 box-shadow），封装
useTheme()Hook，内部用useContext读值，避免重复getComputedStyle - 若必须运行时计算（如动态生成渐变色），在
useMemo里读一次getComputedStyle，并依赖theme值变化，而不是每次 render 都读 - 注意：CSS 变量名大小写敏感，
--Color-Primary和--color-primary是两个变量，命名统一用 kebab-case
暗色模式下容易被忽略的兼容点
用户系统偏好（prefers-color-scheme）和页面 data-theme 不一致时，matchMedia 监听器不会自动触发更新，且部分老浏览器不支持 data-theme 切换后立即生效的 CSS 变量继承链。
- 首次加载时，先读
localStorage，再 fallback 到matchMedia('(prefers-color-scheme: dark)').matches，最后才是硬编码默认值 - 给
html元素加class备份（如class="theme-dark"），防止某些 CSS 引擎对[data-theme="dark"]解析延迟 - SSR 场景下，服务端渲染时无法访问
document，必须通过getServerSideProps或请求头判断客户端偏好，并注入初始data-theme - 测试时别只看 Chrome，Safari 对
css custom property的 cascade 行为略有差异，特别是嵌套 shadow DOM 内
最常出问题的地方不是“怎么切”，而是“切完之后 JS 和 CSS 是否真的一致”。每次修改主题变量，都要验证三处：DOM 上的 data-theme 值、Context 提供的 theme 值、DevTools 里 computed style 中 var(--xxx) 的实际解析结果——三个必须完全对得上。
