文档教程知识库【免费下载链接】til:memo: Today I Learned项目地址https://gitcode.com/gh_mirrors/ti/til点击查看免费下载本篇指南围绕 TIL 仓库中的 javascript/check-media-queries-from-javascript.md 展开讲解如何把原本用于 CSS 的媒体查询搬进 JavaScript 上下文通过浏览器原生window.matchMediaAPI 读取prefers-color-scheme、prefers-reduced-motion等媒体特性的当前匹配状态。读完本文你将掌握matchMedia的返回值结构与matches属性的用法并能基于它实现响应式、跟随系统主题的 Light/Dark 模式切换等实战方案。从 CSS 媒体查询说起在 Web 开发中媒体查询Media Queries通常被放在 CSS 上下文里使用用它们控制不同屏幕宽度下的布局样式、在用户偏好减少动画时收敛动效或者在用户偏好深色配色时切换整套颜色方案。仓库中的 css/apply-styles-based-on-dark-mode-preferences.md 就演示了如何在 CSS 侧通过prefers-color-scheme同时提供深色与浅色两套样式media (prefers-color-scheme: dark) { /* dark-mode styles */ /* perhaps changing some custom properties */ } media (prefers-color-scheme: light) { /* light-mode styles */ /* perhaps changing some custom properties */ }该文档同时指出prefers-color-scheme一度仍处于规范草稿draft状态但当时已拥有不错的浏览器支持——这也是为什么「既要在 CSS 里写媒体查询又希望在 JavaScript 里读到同一份匹配结果」的需求会越来越常见很多交互逻辑按钮状态、图标切换、内联样式、Canvas 绘制并不适合塞进 CSS 文件里。window.matchMedia在 JavaScript 中查询媒体查询媒体查询的当前值同样可以从 JavaScript 上下文检查。浏览器在window对象上暴露了matchMedia方法它接受一个媒体查询字符串并返回一个MediaQueryList对象用来描述「这条媒体查询在当下环境中是否成立」。比如想判断用户是否偏好深色配色可以针对(prefers-color-scheme: dark)这条查询寻找一次匹配 window.matchMedia((prefers-color-scheme: dark)) MediaQueryList {media: (prefers-color-scheme: dark), matches: true, onchange: null}上面这段输出直接取自原文档在浏览器控制台中的真实运行结果。可以看到matchMedia返回的MediaQueryList对象携带三个关键字段字段含义media传入的媒体查询字符串例如(prefers-color-scheme: dark)matches布尔值表示当前环境是否匹配这条媒体查询onchange可挂载的变更回调null表示尚未监听media字段会被浏览器规范化例如补全空格、合并括号因此在控制台打印时可能与传入字符串略有差异但语义一致。读取匹配结果matches 属性MediaQueryList上的matches属性是最常被直接读取的字段。它在条件判断中可以直接当作布尔值使用例如判断用户是否处于深色模式 window.matchMedia((prefers-color-scheme: dark))[matches] true原文档使用方括号形式[matches]读取属性等价于点号写法.matches后者在工程代码中更常见const prefersDark window.matchMedia((prefers-color-scheme: dark)).matches; if (prefersDark) { // 用户系统当前处于深色模式 }注意matches是快照式的即时值它反映调用那一刻的匹配结果。若要跟随系统设置实时变化例如用户临时切换系统主题还需要监听后续章节所述的变更事件。常用可检测的媒体特性matchMedia的查询串语法与 CSSmedia完全一致凡是 CSS 能写的媒体特性JavaScript 侧都可以按相同写法检测。结合原文档提到的场景常见示例包括// 视口宽度类是否处于窄屏 window.matchMedia((max-width: 600px)).matches // 减少动效偏好用户是否要求减少非必要动画 window.matchMedia((prefers-reduced-motion: reduce)).matches // 配色偏好是否偏好深色/浅色配色 window.matchMedia((prefers-color-scheme: dark)).matches window.matchMedia((prefers-color-scheme: light)).matches原文档点名的prefers-color-scheme是本文的核心媒体特性其取值通常为light、dark与no-preference。值得一提的是不少站点会在 CSS 中基于它定义颜色变量如仓库 css/apply-styles-based-on-dark-mode-preferences.md 建议的「更换自定义属性」做法而 JavaScript 侧同样通过它来决定逻辑分支两者各司其职。监听变化跟随系统主题实时响应MediaQueryList返回对象中的onchange字段暗示了它具备事件能力。当媒体查询的匹配状态随环境变化时可以注册监听来获得通知——例如用户把操作系统从浅色切到深色页面无需刷新即可感知const darkModeQuery window.matchMedia((prefers-color-scheme: dark)); function handleChange(event) { // event.matches 即变化后的最新匹配结果 console.log(当前是否深色模式, event.matches); } // 现代写法addEventListener 绑定 change 事件 darkModeQuery.addEventListener(change, handleChange); // 不再需要时移除监听 darkModeQuery.removeEventListener(change, handleChange);change事件回调收到的参数带有matches属性与MediaQueryList.matches含义一致可以直接用于更新页面状态例如切换根元素上的data-theme属性、改写 CSS 变量、重绘 Canvas 等。把「初始读取」与「变更监听」组合起来就能覆盖「打开页面时」和「运行过程中系统偏好变化」两种时机。实战实现跟随系统的 Light/Dark 切换把上面的能力组合起来即可复刻原文档结尾所提到的经典用法——在客户端给站点接一个 Light/Dark 切换。该模式正是 Astro.build Blog 教程的「添加客户端交互」章节 所展示的例子原文档直接引用了该教程作为实现参考其骨架如下// 读取初始偏好 const darkModeQuery window.matchMedia((prefers-color-scheme: dark)); let isDark darkModeQuery.matches; // 同步 DOM例如在根元素上加/去 dark 类配合 CSS 中的配色变量 function applyTheme(mode) { document.documentElement.classList.toggle(dark, mode dark); } applyTheme(isDark ? dark : light); // 系统偏好变化时自动跟随 darkModeQuery.addEventListener(change, (event) { isDark event.matches; applyTheme(isDark ? dark : light); }); // 用户手动切换按钮 toggleButton.addEventListener(click, () { isDark !isDark; applyTheme(isDark ? dark : light); });对应地CSS 侧基于prefers-color-scheme或根元素上的.dark类提供两套配色。仓库中的 tailwind/use-tailwind-typography-prose-in-dark-mode.md 记录了另一种相关实践在 Tailwind CSS 中为prose排版内容追加dark:prose-dark类以在暗色模式下获得合理的正文默认样式——这类「类名切换」机制与上述applyTheme思路完全同源。在 TIL 仓库中的上下文本仓库README.md是一个以「Today I Learned」形式沉淀的日常技术笔记集合主题涵盖 JavaScript、CSS、Tailwind 等多个领域。本文对应的原始笔记 javascript/check-media-queries-from-javascript.md 属于 JavaScript 分类它与 css/apply-styles-based-on-dark-mode-preferences.md 形成互补前者解决「在 JS 里怎么读媒体查询」后者解决「在 CSS 里怎么写媒体查询」配合 tailwind/use-tailwind-typography-prose-in-dark-mode.md 中的暗色模式类名实践即可拼出完整的深浅色主题能力。小结window.matchMedia(queryString)是浏览器原生 API返回MediaQueryList对象其中media保存查询串、matches保存当前匹配结果、onchange可挂载回调查询串语法与 CSSmedia一致prefers-color-scheme、prefers-reduced-motion、max-width等特性均可检测通过addEventListener(change, ...)可以在系统偏好变化时实时更新应用状态将「初始读取 变更监听 类名切换」组合即可实现跟随系统偏好的 Light/Dark 模式切换这也是 Astro 官方教程采用的交互模式。赞分享文档教程知识库【免费下载链接】til:memo: Today I Learned项目地址https://gitcode.com/gh_mirrors/ti/til点击查看免费下载相关推荐基于 prefers-color-scheme 媒体查询实现深色模式适配 —— til 仓库 CSS 实战指南基于 prefers color scheme 媒体查询实现深色模式适配 —— til 仓库 CSS 实战指南 现代操作系统与浏览器普遍允许用户声明自己更偏好深文档教程知识库自动切换网站主题妙用prefers-color-scheme实现暗色模式检测自动切换网站主题妙用prefers color scheme实现暗色模式检测 你是否遇到过这样的情况晚上浏览网站时突然弹出的白色背景让眼睛刺痛不已或者白前端文档Enzyme测试组件黑暗模式prefers-color-scheme测试Enzyme测试组件黑暗模式prefers color scheme测试 在现代Web应用开发中黑暗模式已成为用户体验的重要组成部分。通过CSS的 pref测试前端上一篇RxJS 4.x fromEventPattern 实战指南用 addHandler/removeHandler 桥接任意自定义事件源下一篇Apollo Client 内部测试工具包 apollo/client/testing/internal API 全面解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考