prefers-color-scheme 在 iOS/Android WebView 中常失效，主因是 WebView 容器未透传系统偏好，需优先通过 JSBridge 获取主题，并用 localStorage fallback；:root 必须初始化所有变量，.dark-mode 仅覆盖，避免闪白或结构失效。
移动端深色模式布局适配，核心不是“加一套暗色样式”，而是让布局结构本身不依赖颜色语义——flex/grid 容器、卡片间距、阴影层级、字体渲染这些底层行为，在深色下必须依然成立。
为什么 prefers-color-scheme 在 iOS/Android WebView 里常失效
不是媒体查询写错了，是容器没暴露系统偏好。Safari（iOS 15+）、Chrome（Android 10+）原生支持 @media (prefers-color-scheme: dark)，但很多 App 内嵌 WebView（如微信、钉钉、企业自研壳）默认禁用该特性，或未透传系统设置。
常见现象：window.matchMedia('(prefers-color-scheme: dark)').matches 始终返回 false，即使手机已开启深色模式。
实操建议：
- 优先走客户端 JSBridge 获取主题：调用
utils.checkThemeMode()或类似接口，而非只信浏览器 API - 降级 fallback 必须存在：比如 localStorage 缓存上次用户手动选择的
local_theme，值为0（浅色）或1（深色） - 不要在 CSS 中只写
@media (prefers-color-scheme: dark)就完事；搭配.dark-modeclass 覆盖更可靠 - 测试时别只用 Chrome DevTools 的「Emulate CSS prefers-color-scheme」——它模拟的是浏览器层，不是 WebView 容器层
:root 和 .dark-mode 的变量声明顺序不能颠倒
CSS 变量生效靠继承和作用域，:root 是起点，.dark-mode 是覆盖层。如果只在 .dark-mode 里定义 --bg-color，但 :root 没声明默认值，那页面首次加载时 background: var(--bg-color) 会回退成 transparent 或浏览器默认色，导致闪白或内容不可读。
正确写法：
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur
:root {
--bg-color: #fff;
--text-color: #333;
--border-color: #e0e0e0;
}
.dark-mode {
--bg-color: #1e1e1e;
--text-color: #f0f0f0;
--border-color: #444;
}
注意：
- 所有变量必须在
:root中初始化，哪怕只是占位值 -
.dark-mode仅用于重写，不能删掉:root原始声明 - 避免在组件级 CSS 里重复声明同名变量（如
.card { --bg-color: #f8f9fa; }），会污染全局语义
Flex/Grid 卡片布局在深色模式下的视觉断裂点
深色模式下最常被忽略的不是颜色，而是对比度缺失引发的结构感知失效。例如：
- 浅色模式下靠
box-shadow: 0 2px 8px rgba(0,0,0,0.1)区分卡片层级，深色模式下这个阴影几乎看不见——改用color-mix(in srgb, currentColor 15%, transparent)或固定低透明度黑（rgba(0,0,0,0.2)）更稳 - 卡片内图片没设
background-color，深色背景上透明 PNG 边缘发灰；应统一加background: var(--bg-color)容器兜底 - 使用
flex-direction: column的响应式断点（如@media (max-width: 768px)）在深色下仍要生效，但别忘了同时重置gap值——深色下过大的间隙会加剧“空洞感” - 文字行高、字重不变，但深色背景 + 浅色文字易产生光晕，可微调
font-smooth: antialiased或-webkit-font-smoothing: subpixel-antialiased
移动端表单控件与深色模式的兼容陷阱
input、select、textarea 在 iOS Safari 和 Android Chrome 中，深色模式下会自动套用系统控件样式，但这个“自动”不可控且不一致。
典型问题：
- input 边框在深色下变成极细灰线，几乎不可见；需显式设
border: 1px solid var(--border-color) - placeholder 文字在深色下默认是
#999，对比度不足；应通过::placeholder { color: var(--text-color-secondary); }统一管理 - checkbox/radio 的原生样式无法用 CSS 变量直接改，得用
appearance: none+ 自绘，否则深色下圆点/勾选图标可能消失 - focus 状态若只靠
outline，在深色下容易被忽略；建议加box-shadow: 0 0 0 2px var(--primary-color)强化焦点环
真正麻烦的不是写多少 CSS，而是每次改一个变量，都得验证它是否在 flex 容器、表格单元格、fixed 定位弹层、iframe 预览区里全都生效——这些上下文对 CSS 变量的继承规则并不总是一致。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
