CSS变量实现主题切换需在:root定义默认变量，.dark类中覆盖变量，通过classList.toggle('dark')触发重绘；状态同步应优先原生桥接存储，fallback localStorage；禁用prefers-color-scheme自动响应，避免样式冲突。
HTML5页面如何用CSS变量实现主题切换
夜间模式本质是样式批量替换，CSS自定义属性（--bg-color、--text-color等）是最轻量、最可控的方案。不用重写整套class，也不依赖JS动态改class名，所有颜色/间距/阴影都通过变量控制。
关键操作：在:root里定义默认主题变量，在.dark类里覆盖同一组变量；然后用document.documentElement.classList.toggle('dark')切换根节点class即可触发全局重绘。
- 变量命名要带语义，比如
--primary-text比--color1更易维护 - 避免在
.dark里只改背景色却漏掉border-color或placeholder色，导致局部“亮斑” - 慎用
!important覆盖变量值——它会破坏CSS变量的层叠逻辑，调试时极难追踪
WebView中保存并同步主题状态到本地
APP重启后必须记住用户上次选的主题，不能每次打开都回退到白天模式。单纯用localStorage不够：Android WebView和iOS WKWebView对localStorage持久化支持不一致，尤其在低内存清理或冷启动时可能丢失。
更稳妥的做法是：JS层读写localStorage做即时反馈，同时通过JSBridge把当前主题值（如"light"或"dark"）传给原生层，由原生代码存入SharedPreferences（Android）或UserDefaults（iOS）。
立即学习“前端免费学习笔记（深入）”；
- 首次加载页面时，优先从原生桥接接口取主题值（
window.WebViewBridge.getTheme()）， fallback才查localStorage - 切换主题后，立即调用
window.WebViewBridge.setTheme('dark')，再更新localStorage，防止桥接失败时样式错乱 - 不要在
DOMContentLoaded之前读取localStorage——部分WebView会延迟初始化存储API
适配系统级深色模式（prefers-color-scheme）的边界情况
用户开了系统深色模式，但APP内手动切回白天模式，此时@media (prefers-color-scheme: dark)仍会生效，造成样式冲突。不能直接靠媒体查询接管全部逻辑。
正确做法是：把系统偏好当默认值，而非强制规则。用JS检测window.matchMedia('(prefers-color-scheme: dark)').matches获取初始状态，但后续一切以用户手动选择为准，并禁用媒体查询的自动响应。
- 在CSS里避免直接写
@media (prefers-color-scheme: dark) { :root { --bg: #121212; } }——它会在用户手动切回白天时仍偷偷生效 - 如果必须用媒体查询做兜底（比如未登录页），加一层
:not(.theme-manual)限定，确保用户手动设置后媒体查询失效 - iOS 16+ 的WKWebView有bug：切换系统模式后，
matchMedia的change事件可能不触发，需定时轮询检查
原生层注入CSS变量或动态替换CSS文件的坑
有些团队尝试让原生代码直接注入整段CSS字符串（如webView.evaluateJavascript("document.documentElement.style.setProperty('--bg', '#000')")），这会导致样式不可预测：变量作用域混乱、重复注入覆盖、无批量更新原子性。
更可靠的方式是预置两套CSS文件（theme-light.css和theme-dark.css），用原生层控制标签的href属性切换，或者干脆只注入一个标签，内容为纯变量声明块（不含选择器）。
- 注入CSS字符串时，务必用
encodeURIComponent处理换行和引号，否则Android WebView会静默截断 - 不要在
onPageFinished里立刻注入——此时DOM可能未就绪，document.documentElement还不存在 - 若使用CSS文件方式，注意HTTP缓存：给
href加时间戳参数（theme-dark.css?t=1712345678）避免旧文件被强缓存
真正麻烦的不是切换动作本身，而是状态同步时机、变量作用域隔离、以及WebView各版本对CSS和Storage的实际行为差异。这些细节不压平，夜间模式就会在某个机型上闪一下白屏，或者切了主题按钮变灰但文字还是黑的。
