移动端主题切换必须用 data-theme 属性而非 class，因其不参与 CSS 优先级竞争、兼容 Shadow DOM、避免 iOS Safari 渲染缓存失效；需结合 localStorage 与 prefers-color-scheme 实现用户选择优先，并通过 :root[data-theme] 预定义变量、限定 transition 属性保障性能与一致性。
移动端主题切换必须用 data-theme 而不是 class 切换
直接给 html 或 body 加 .dark 类在移动端容易失效，尤其遇到 iOS Safari 的渲染缓存或第三方 UI 框架（如 Nebular、Ionic）对 class 的样式覆盖逻辑。用 data-theme 属性是更稳定的选择，它不参与 CSS 优先级竞争，且能被所有现代浏览器正确识别为状态标识。
常见错误现象：点击按钮后主题没变，或只变了一半（比如背景变了但文字没变），大概率是 class 被其他样式规则覆盖，或者伪类选择器（如 :root.dark）未生效。
-
:root[data-theme="dark"]比:root.dark更可靠，尤其在 Shadow DOM 或 Web Component 场景下 - 不要用
body[data-theme]，而要用:root[data-theme]—— 否则变量作用域受限，子元素无法继承 - 移动端 Safari 对
:root中变量的重计算有时延迟，需配合transition强制触发重绘
prefers-color-scheme 和用户手动切换必须共存
仅靠媒体查询自动适配系统偏好，会忽略用户主动选择。移动端用户常因环境光临时切深色，但系统设置仍为浅色——这时必须允许覆盖。
关键逻辑是「系统偏好兜底 + 用户选择优先」：页面加载时先读 localStorage，有值就用；无值再查 matchMedia('(prefers-color-scheme: dark)')，最后写回 localStorage 保证下次一致。
立即学习“前端免费学习笔记（深入）”；
- JavaScript 初始化时必须同步设置
document.documentElement.setAttribute('data-theme', ...)，不能只改 class - 监听
matchMedia变化时，仅当用户未手动切换过才响应（可用 flag 标记） - 避免在
DOMContentLoaded前读取localStorage，iOS Safari 可能报SecurityError
移动端性能敏感点：别用 style.setProperty 批量设变量
逐个调用 document.documentElement.style.setProperty('--color-bg', '#121212') 在低端 Android 机上会卡顿，因为每次调用都触发一次样式重计算。应统一用 data-theme 触发整套变量替换，由 CSS 引擎批量处理。
正确做法是在 :root 下预定义所有主题变量块，例如：
:root {
--color-bg: #fff;
--color-text: #333;
}
:root[data-theme="dark"] {
--color-bg: #121212;
--color-text: #e0e0e0;
}
:root[data-theme="sepia"] {
--color-bg: #f4f0ec;
--color-text: #5a4a42;
}
- 变量名保持语义化（如
--color-bg），避免用--bg这类缩写，否则多主题维护时易冲突 - 所有主题变量必须在初始 CSS 中一次性声明，运行时只切换属性，不动态注入新规则
- 移动端不要用
@media (max-width: 768px)嵌套主题变量——这会导致 CSS 文件体积膨胀且不可缓存
过渡动画必须加在 body 或 html 上，且限定属性
直接写 transition: all 0.3s ease 在 :root 无效，CSS 变量本身不触发过渡。必须把过渡效果绑定到实际使用变量的属性上，且只过渡颜色、背景、阴影等视觉属性，避免 transform 或 width 等触发布局重排。
推荐写法：
body {
background-color: var(--color-bg);
color: var(--color-text);
transition: background-color 0.3s ease, color 0.3s ease;
}
- 不要用
transition: all，iOS Safari 会把未声明的变量（如--spacing）也纳入过渡，导致意外抖动 - 如果用了
box-shadow或border-color，记得把它们也加进transition列表 - 首次加载时若主题切换过快，可加
opacity: 0; transition: opacity 0.1s;防闪屏
最易被忽略的是：移动端 WebView（如微信内置浏览器、QQ 浏览器）对 matchMedia 的支持不完整，prefers-color-scheme 可能始终返回 light。所以用户手动切换的入口必须显眼，且初始化逻辑不能依赖媒体查询结果作为唯一依据。
