基于 prefers-color-scheme 的 H5 暗黑模式适配指南
在移动端开发中，用户越来越习惯根据系统设置自动切换网页主题。你是否也曾遇到过这样的场景：明明正在用浅色模式浏览网站，切换到傍晚或开启手机深色模式后，页面竟然自动变成了暗黑配色？这并非异常现象，而是现代浏览器原生支持的 prefers-color-scheme 媒体特性在发挥作用。本文将带你彻底搞懂这一特性，并分享一套生产环境可用的完整适配方案。
什么是 prefers-color-scheme？
prefers-color-scheme 是 CSS 媒体查询（Media Queries Level 5）中的核心特性，专门用于检测用户操作系统的颜色偏好设置。它无需任何第三方库，仅靠浏览器原生能力即可实现主题响应。该特性主要包含三个枚举值：
- light：表示用户系统当前处于浅色（日光）模式。
- dark：表示用户系统当前处于深色（暗黑）模式。
- no-preference：表示系统未明确获取到用户的偏好设置。
通过该特性，开发者可以编写两套或多套样式表，让网页像操作系统一样智能地“感知”环境变化。更多底层规范可查阅 MDN 官方文档。
核心实现方案
1. 纯 CSS 媒体查询实现基础切换
最轻量且零延迟的实现方式是利用 @media 规则覆盖 CSS 自定义属性（CSS Variables）。这种方式完全依赖浏览器渲染引擎，性能极佳。
<style>
:root {
--bg-color: #ffffff;
--text-color: #333333;
}
@media (prefers-color-scheme: dark) {
:root {
--bg-color: #121212;
--text-color: #e0e0e0;
}
}
body {
background-color: var(--bg-color);
color: var(--text-color);
}
</style>在实际开发中，建议同时添加 <meta name="color-scheme" content="light dark"> 到 <head> 中。这能引导浏览器自动调整原生表单控件（如滚动条、输入框焦点环）的配色，避免手动重写大量组件样式。具体效果如下所示，页面样式会随系统模式无缝切换：
2. 进阶：JS 监听与本地持久化存储
虽然纯 CSS 方案足够优雅，但它只能被动响应系统设置。若需支持用户手动点击按钮切换，或保持刷新后的状态，则必须引入 JavaScript 与 localStorage。以下是标准的生产级逻辑：
- 优先级判断：优先读取
localStorage中缓存的用户选择；若无记录，再通过window.matchMedia('(prefers-color-scheme: dark)').matches获取系统初始偏好。 - 实时监听变化：调用
addEventListener('change', handler)监听系统主题变更事件。注意必须使用此 API，而非传统的onchange，以确保 Safari 和 Chrome 等主流浏览器能准确触发回调。 - 防止闪烁（FOUT/FOUC)：将初始化脚本放在
<head>的内联<script>中，早于外部 CSS 加载执行。切勿依赖DOMContentLoaded，否则首屏可能出现短暂的白底或黑底闪烁。
这套组合拳能确保无论用户如何切换设备主题或主动修改网页设置，视觉体验始终如一。如果你需要更完整的 Vue/React 主题切换架构，欢迎访问 CyunZing的程序员修炼手册 获取更多实战教程。当然，前端生态日新月异，关于媒体查询的更多高级用法，也可参考我们往期整理的 H5 主题适配深度解析。
兼容性与最佳实践总结
浏览器支持与降级策略
prefers-color-scheme 已获广泛支持（Chrome 76+、Firefox 67+、Safari 12.1+、Edge 79+）。但在老旧环境或企业内网浏览器中，仍需做好降级处理。核心原则是：所有样式必须提供默认亮色基线，严禁仅在 @media (prefers-color-scheme: dark) 分支内定义全局变量，否则匹配失败时页面将失去背景与文字颜色。
此外，部分旧版 Safari 对 change 事件的兼容性较弱，此时可采用轮询或强制刷新作为 fallback。只要遵循上述结构规范，你的 H5 项目就能在各大平台上稳定运行。
掌握 prefers-color-scheme 只是第一步，实际业务中往往需要结合 CSS 变量管理、路由守卫及无障碍设计（A11y）进行综合考量。希望本文提供的代码模板与优化思路，能帮你快速打通移动端主题适配的全链路。如有技术疑问，欢迎在评论区交流探讨。
文章评论