前端【免费下载链接】vueuseCollection of essential Vue Composition Utilities for Vue 3项目地址https://gitcode.com/gh_mirrors/vu/vueuse点击查看免费下载usePreferredDark是 VueUse 核心包中一个轻量却高频使用的 Browser 类组合式函数它通过监听操作系统/浏览器层面的prefers-color-scheme媒体查询返回一个响应式的布尔值 ref实时反映用户是否偏好深色主题。在 VueUse 生态中它是 useDark 与 useColorMode 实现自动跟随系统主题的底层基石也常被单独用于 favicon 切换、图表配色适配等场景。读完本文你将掌握它的用法、底层实现原理、SSR 行为边界以及如何将其集成到自己的主题系统中。一、快速上手从vueuse/core引入后直接调用即可无需任何参数import { usePreferredDark } from vueuse/core const isDark usePreferredDark()isDark是一个ComputedRefboolean当系统处于深色模式或浏览器内设置了prefers-color-scheme: dark时其值为true当系统处于浅色模式时其值为false。最关键的特性是响应式当用户中途切换系统深色/浅色外观时该 ref 会立即自动更新无需手动刷新页面也无需额外绑定监听事件。这与 VueUse 其他usePreferred*系列如 usePreferredColorScheme一样遵循prefer* 系列即响应式偏好的设计惯例。该函数被标记为__NO_SIDE_EFFECTS__见 index.ts即调用本身不产生副作用可安全用于 SSR 场景或惰性初始化。在模板中直接使用script setup langts import { usePreferredDark } from vueuse/core const isDark usePreferredDark() /script template span当前是否偏好深色{{ isDark }}/span /template仓库自带的 demo.vue 展示了最简形态usePreferredDark()的返回值直接绑定到BooleanDisplay组件上展示布尔值。二、底层原理从 matchMedia 到响应式 refusePreferredDark本身只有一行核心实现见 index.tsexport function usePreferredDark(options?: ConfigurableWindow) { return useMediaQuery((prefers-color-scheme: dark), options) }也就是说它是对通用媒体查询组合式函数 useMediaQuery 的固定封装。理解usePreferredDark本质上就是理解useMediaQuery的响应式机制其实现位于 packages/core/useMediaQuery/index.ts。关键调用链能力检测通过useSupported(() window matchMedia in window typeof window.matchMedia function)判断当前环境是否支持matchMedia避免在不支持的旧浏览器或非浏览器环境抛错。建立媒体查询watchEffect内调用window.matchMedia((prefers-color-scheme: dark))并将MediaQueryList.matches的初值写入matchesref。事件监听useEventListener(mediaQuery, change, handler, { passive: true })监听change事件。当系统外观变化时浏览器触发MediaQueryListEventhandler将event.matches同步到 ref。返回计算属性最终返回computed(() matches.value)对外呈现为只读、响应式的布尔 ref。整个链路环环相扣matchMedia 初值 change 事件增量更新 computed 派生这就是系统偏好一变isDark立刻跟着变的原理。与手写监听的区别手写实现通常需要const mql window.matchMedia((prefers-color-scheme: dark)) const onChange (e: MediaQueryListEvent) isDark e.matches mql.addEventListener(change, onChange) // 别忘了卸载时 removeEventListener而usePreferredDark借助useEventListener自动在组件卸载/作用域销毁时清理监听器useEventListener基于tryOnScopeDispose实现自动清理同时天然享受 VueUse 的 SSR 与测试基础设施代码量从十几行压缩到一行。三、选项Options与自定义 windowusePreferredDark接受一个可选的ConfigurableWindow类型参数定义于 packages/core/_configurable.tsexport interface ConfigurableWindow { /* * Specify a custom window instance, e.g. working with iframes or in testing environments. */ window?: Window }选项类型默认值说明windowWindowdefaultWindow客户端为全局window服务端为undefined指定自定义 window 实例用于 iframe 或测试环境典型使用场景iframe 内的主题偏好当你的应用以 iframe 嵌入第三方页面、需要以父页面或特定 iframe 的 window为检测基准时const iframeWindow document.querySelector(iframe)!.contentWindow const isDark usePreferredDark({ window: iframeWindow })典型使用场景单元测试在 vitest 等测试环境中可以注入一个 mock 的 window 对象来稳定模拟系统外观而无需真实切换操作系统设置import { usePreferredDark } from vueuse/core import { describe, expect, it, vi } from vitest it(mock 深色偏好, () { const mockWindow { matchMedia: vi.fn().mockReturnValue({ matches: true, addEventListener: vi.fn(), removeEventListener: vi.fn(), }), } const isDark usePreferredDark({ window: mockWindow as unknown as Window }) expect(isDark.value).toBe(true) })注意defaultWindow由isClient ? window : undefined决定见 _configurable.ts因此在 SSR 环境下未传window时matchMedia不会被执行。四、SSR 与无窗口环境的边界行为从源码看useMediaQuery为 SSR 做了专门处理见 useMediaQuery/index.ts当window不可用服务端渲染时isSupported为false函数不会调用window.matchMedia返回的 ref 保持初始值false它额外支持ssrWidth选项ConfigurableWindow { ssrWidth?: number }允许在 SSR 阶段基于预设的视口宽度模拟min-width/max-width类媒体查询结果。不过对于(prefers-color-scheme: dark)这类非宽度型查询SSR 阶段会直接返回false因为服务端无从得知用户系统的外观偏好。实际含义在 SSR 首屏渲染时isDark一定为false只有客户端水合hydrate后才会得到真实值。如果你的主题系统在首屏就依赖该值做样式注入需要在设计时考虑这一闪烁窗口通常可配合useDark的持久化存储localStorage来抹平差异。五、组件用法UsePreferredDark与大多数 VueUse 组合式函数一样usePreferredDark提供了对应的渲染函数组件UsePreferredDark通过作用域插槽暴露数据见 component.tstemplate UsePreferredDark v-slot{ prefersDark } Prefers Dark: {{ prefersDark }} /UsePreferredDark /template插槽数据prefersDark的类型为ComputedRefboolean。组件的 props 同样继承ConfigurableWindow可传入windowUsePreferredDark :windowiframeWindow v-slot{ prefersDark } 当前 iframe 偏好深色{{ prefersDark }} /UsePreferredDark从源码实现看组件内部用reactive包裹了usePreferredDark(props)的返回值component.ts并在slots.default存在时才渲染插槽内容。该组件由 packages/components/index.ts 统一对外导出属于 VueUse 的组件入口。六、实战集成与 useDark / useColorMode 联动usePreferredDark最核心的应用场景是作为主题系统的自动模式信号源。1. 一键式深色模式useDarkuseDark 的自动跟随系统能力正是建立在usePreferredDark之上的useDarkcombines withusePreferredDarkanduseStorage. On start up, it reads the value from localStorage/sessionStorage (the key is configurable) to see if there is a user configured color scheme, if not, it will use users system preferences.行为流程为启动时先读取存储中的用户显式配置默认 key 为vueuse-color-scheme若无用户配置则回退到usePreferredDark()的系统偏好手动切换isDark时更新 DOM 属性并将选择写回存储。典型用法import { useDark, useToggle } from vueuse/core const isDark useDark() const toggleDark useToggle(isDark)2. 多模式主题useColorModeuseColorMode 默认的auto模式同样依赖usePreferredDark源码见 useColorMode/index.ts 的usePreferredDark({ window })调用读取 ref 时默认返回当前模式dark/light/ 自定义模式开启emitAuto后auto才会出现在返回值中写入 ref 时触发 DOM 更新并持久化到存储传入auto则回到跟随系统状态。3. 轻量场景动态 favicon 与数据可视化不引入完整主题系统单点适配即可import { useFavicon, usePreferredDark } from vueuse/core import { computed } from vue const isDark usePreferredDark() const favicon computed(() isDark.value ? dark.png : light.png) useFavicon(favicon)这是 useFavicon 文档中的官方示例系统切到深色favicon 自动换成深色版图标。同理可将其映射到图表背景色、代码高亮主题、Canvas 配色等任何响应式派生值。七、源码结构速览该功能的全部相关文件都位于packages/core/usePreferredDark/目录文件作用index.ts核心实现封装useMediaQuery((prefers-color-scheme: dark))标记__NO_SIDE_EFFECTS__component.ts渲染函数组件UsePreferredDark暴露prefersDark作用域插槽demo.vue官方演示页面index.md官方文档本文主体导出关系组合式函数由 packages/core/index.ts 导出组件由 packages/components/index.ts 导出二者在vueuse/core与vueuse/components中均可直接引入。值得一提的是usePreferredDark的打包体积仅有1.17 kB见 packages/export-size.md是 VueUse 中体积最小的实用函数之一引入成本几乎可以忽略。在 VueUse 快速上手指南中它也与useLocalStorage、useMouse一起作为入门示例出现足以说明其使用频度与代表性。八、小结usePreferredDark用一行封装换来了整个响应式系统偏好检测能力API 极简零配置调用即得响应式布尔 ref实现可靠基于matchMediachange事件 useEventListener自动清理无内存泄漏生态地位useDark、useColorMode的auto模式都构建于其上边界清晰SSR 阶段返回false客户端水合后生效可通过window选项适配 iframe 与测试环境。如果你正在实现跟随系统深浅色或自动主题功能直接使用它或在其之上组合useDark/useColorMode是最符合 VueUse 设计哲学、也最省力的方案。赞分享前端【免费下载链接】vueuseCollection of essential Vue Composition Utilities for Vue 3项目地址https://gitcode.com/gh_mirrors/vu/vueuse点击查看免费下载相关推荐airi 项目中的 VueUse usePreferredDark 实战响应式深色主题偏好检测与暗色模式适配指南airi 项目中的 VueUse usePreferredDark 实战响应式深色主题偏好检测与暗色模式适配指南 usePreferredDark 是 VueAI 应用人工智能大模型数字人AI Agent语音前端后端桌面应用移动开发即时通讯3D渲染黑苹果安装前硬件体检怎么做OpCore-Simplify 兼容性检测完整指南黑苹果安装前硬件体检怎么做OpCore Simplify 兼容性检测完整指南 装黑苹果最怕的不是过程麻烦而是装到一半发现硬件根本不兼容——显卡没加速、Wi开发工具CLIVueUse usePreferredReducedMotion响应式监听 prefers-reduced-motion 无障碍偏好VueUse usePreferredReducedMotion响应式监听 prefers reduced motion 无障碍偏好 本指南围绕 VueUse前端上一篇猫抓浏览器插件免费解锁网页视频下载的终极解决方案下一篇猫抓浏览器插件三步完成网页视频下载的终极免费方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
VueUse usePreferredDark 指南：响应式深色模式偏好检测
前端【免费下载链接】vueuseCollection of essential Vue Composition Utilities for Vue 3项目地址https://gitcode.com/gh_mirrors/vu/vueuse点击查看免费下载usePreferredDark是 VueUse 核心包中一个轻量却高频使用的 Browser 类组合式函数它通过监听操作系统/浏览器层面的prefers-color-scheme媒体查询返回一个响应式的布尔值 ref实时反映用户是否偏好深色主题。在 VueUse 生态中它是 useDark 与 useColorMode 实现自动跟随系统主题的底层基石也常被单独用于 favicon 切换、图表配色适配等场景。读完本文你将掌握它的用法、底层实现原理、SSR 行为边界以及如何将其集成到自己的主题系统中。一、快速上手从vueuse/core引入后直接调用即可无需任何参数import { usePreferredDark } from vueuse/core const isDark usePreferredDark()isDark是一个ComputedRefboolean当系统处于深色模式或浏览器内设置了prefers-color-scheme: dark时其值为true当系统处于浅色模式时其值为false。最关键的特性是响应式当用户中途切换系统深色/浅色外观时该 ref 会立即自动更新无需手动刷新页面也无需额外绑定监听事件。这与 VueUse 其他usePreferred*系列如 usePreferredColorScheme一样遵循prefer* 系列即响应式偏好的设计惯例。该函数被标记为__NO_SIDE_EFFECTS__见 index.ts即调用本身不产生副作用可安全用于 SSR 场景或惰性初始化。在模板中直接使用script setup langts import { usePreferredDark } from vueuse/core const isDark usePreferredDark() /script template span当前是否偏好深色{{ isDark }}/span /template仓库自带的 demo.vue 展示了最简形态usePreferredDark()的返回值直接绑定到BooleanDisplay组件上展示布尔值。二、底层原理从 matchMedia 到响应式 refusePreferredDark本身只有一行核心实现见 index.tsexport function usePreferredDark(options?: ConfigurableWindow) { return useMediaQuery((prefers-color-scheme: dark), options) }也就是说它是对通用媒体查询组合式函数 useMediaQuery 的固定封装。理解usePreferredDark本质上就是理解useMediaQuery的响应式机制其实现位于 packages/core/useMediaQuery/index.ts。关键调用链能力检测通过useSupported(() window matchMedia in window typeof window.matchMedia function)判断当前环境是否支持matchMedia避免在不支持的旧浏览器或非浏览器环境抛错。建立媒体查询watchEffect内调用window.matchMedia((prefers-color-scheme: dark))并将MediaQueryList.matches的初值写入matchesref。事件监听useEventListener(mediaQuery, change, handler, { passive: true })监听change事件。当系统外观变化时浏览器触发MediaQueryListEventhandler将event.matches同步到 ref。返回计算属性最终返回computed(() matches.value)对外呈现为只读、响应式的布尔 ref。整个链路环环相扣matchMedia 初值 change 事件增量更新 computed 派生这就是系统偏好一变isDark立刻跟着变的原理。与手写监听的区别手写实现通常需要const mql window.matchMedia((prefers-color-scheme: dark)) const onChange (e: MediaQueryListEvent) isDark e.matches mql.addEventListener(change, onChange) // 别忘了卸载时 removeEventListener而usePreferredDark借助useEventListener自动在组件卸载/作用域销毁时清理监听器useEventListener基于tryOnScopeDispose实现自动清理同时天然享受 VueUse 的 SSR 与测试基础设施代码量从十几行压缩到一行。三、选项Options与自定义 windowusePreferredDark接受一个可选的ConfigurableWindow类型参数定义于 packages/core/_configurable.tsexport interface ConfigurableWindow { /* * Specify a custom window instance, e.g. working with iframes or in testing environments. */ window?: Window }选项类型默认值说明windowWindowdefaultWindow客户端为全局window服务端为undefined指定自定义 window 实例用于 iframe 或测试环境典型使用场景iframe 内的主题偏好当你的应用以 iframe 嵌入第三方页面、需要以父页面或特定 iframe 的 window为检测基准时const iframeWindow document.querySelector(iframe)!.contentWindow const isDark usePreferredDark({ window: iframeWindow })典型使用场景单元测试在 vitest 等测试环境中可以注入一个 mock 的 window 对象来稳定模拟系统外观而无需真实切换操作系统设置import { usePreferredDark } from vueuse/core import { describe, expect, it, vi } from vitest it(mock 深色偏好, () { const mockWindow { matchMedia: vi.fn().mockReturnValue({ matches: true, addEventListener: vi.fn(), removeEventListener: vi.fn(), }), } const isDark usePreferredDark({ window: mockWindow as unknown as Window }) expect(isDark.value).toBe(true) })注意defaultWindow由isClient ? window : undefined决定见 _configurable.ts因此在 SSR 环境下未传window时matchMedia不会被执行。四、SSR 与无窗口环境的边界行为从源码看useMediaQuery为 SSR 做了专门处理见 useMediaQuery/index.ts当window不可用服务端渲染时isSupported为false函数不会调用window.matchMedia返回的 ref 保持初始值false它额外支持ssrWidth选项ConfigurableWindow { ssrWidth?: number }允许在 SSR 阶段基于预设的视口宽度模拟min-width/max-width类媒体查询结果。不过对于(prefers-color-scheme: dark)这类非宽度型查询SSR 阶段会直接返回false因为服务端无从得知用户系统的外观偏好。实际含义在 SSR 首屏渲染时isDark一定为false只有客户端水合hydrate后才会得到真实值。如果你的主题系统在首屏就依赖该值做样式注入需要在设计时考虑这一闪烁窗口通常可配合useDark的持久化存储localStorage来抹平差异。五、组件用法UsePreferredDark与大多数 VueUse 组合式函数一样usePreferredDark提供了对应的渲染函数组件UsePreferredDark通过作用域插槽暴露数据见 component.tstemplate UsePreferredDark v-slot{ prefersDark } Prefers Dark: {{ prefersDark }} /UsePreferredDark /template插槽数据prefersDark的类型为ComputedRefboolean。组件的 props 同样继承ConfigurableWindow可传入windowUsePreferredDark :windowiframeWindow v-slot{ prefersDark } 当前 iframe 偏好深色{{ prefersDark }} /UsePreferredDark从源码实现看组件内部用reactive包裹了usePreferredDark(props)的返回值component.ts并在slots.default存在时才渲染插槽内容。该组件由 packages/components/index.ts 统一对外导出属于 VueUse 的组件入口。六、实战集成与 useDark / useColorMode 联动usePreferredDark最核心的应用场景是作为主题系统的自动模式信号源。1. 一键式深色模式useDarkuseDark 的自动跟随系统能力正是建立在usePreferredDark之上的useDarkcombines withusePreferredDarkanduseStorage. On start up, it reads the value from localStorage/sessionStorage (the key is configurable) to see if there is a user configured color scheme, if not, it will use users system preferences.行为流程为启动时先读取存储中的用户显式配置默认 key 为vueuse-color-scheme若无用户配置则回退到usePreferredDark()的系统偏好手动切换isDark时更新 DOM 属性并将选择写回存储。典型用法import { useDark, useToggle } from vueuse/core const isDark useDark() const toggleDark useToggle(isDark)2. 多模式主题useColorModeuseColorMode 默认的auto模式同样依赖usePreferredDark源码见 useColorMode/index.ts 的usePreferredDark({ window })调用读取 ref 时默认返回当前模式dark/light/ 自定义模式开启emitAuto后auto才会出现在返回值中写入 ref 时触发 DOM 更新并持久化到存储传入auto则回到跟随系统状态。3. 轻量场景动态 favicon 与数据可视化不引入完整主题系统单点适配即可import { useFavicon, usePreferredDark } from vueuse/core import { computed } from vue const isDark usePreferredDark() const favicon computed(() isDark.value ? dark.png : light.png) useFavicon(favicon)这是 useFavicon 文档中的官方示例系统切到深色favicon 自动换成深色版图标。同理可将其映射到图表背景色、代码高亮主题、Canvas 配色等任何响应式派生值。七、源码结构速览该功能的全部相关文件都位于packages/core/usePreferredDark/目录文件作用index.ts核心实现封装useMediaQuery((prefers-color-scheme: dark))标记__NO_SIDE_EFFECTS__component.ts渲染函数组件UsePreferredDark暴露prefersDark作用域插槽demo.vue官方演示页面index.md官方文档本文主体导出关系组合式函数由 packages/core/index.ts 导出组件由 packages/components/index.ts 导出二者在vueuse/core与vueuse/components中均可直接引入。值得一提的是usePreferredDark的打包体积仅有1.17 kB见 packages/export-size.md是 VueUse 中体积最小的实用函数之一引入成本几乎可以忽略。在 VueUse 快速上手指南中它也与useLocalStorage、useMouse一起作为入门示例出现足以说明其使用频度与代表性。八、小结usePreferredDark用一行封装换来了整个响应式系统偏好检测能力API 极简零配置调用即得响应式布尔 ref实现可靠基于matchMediachange事件 useEventListener自动清理无内存泄漏生态地位useDark、useColorMode的auto模式都构建于其上边界清晰SSR 阶段返回false客户端水合后生效可通过window选项适配 iframe 与测试环境。如果你正在实现跟随系统深浅色或自动主题功能直接使用它或在其之上组合useDark/useColorMode是最符合 VueUse 设计哲学、也最省力的方案。赞分享前端【免费下载链接】vueuseCollection of essential Vue Composition Utilities for Vue 3项目地址https://gitcode.com/gh_mirrors/vu/vueuse点击查看免费下载相关推荐airi 项目中的 VueUse usePreferredDark 实战响应式深色主题偏好检测与暗色模式适配指南airi 项目中的 VueUse usePreferredDark 实战响应式深色主题偏好检测与暗色模式适配指南 usePreferredDark 是 VueAI 应用人工智能大模型数字人AI Agent语音前端后端桌面应用移动开发即时通讯3D渲染黑苹果安装前硬件体检怎么做OpCore-Simplify 兼容性检测完整指南黑苹果安装前硬件体检怎么做OpCore Simplify 兼容性检测完整指南 装黑苹果最怕的不是过程麻烦而是装到一半发现硬件根本不兼容——显卡没加速、Wi开发工具CLIVueUse usePreferredReducedMotion响应式监听 prefers-reduced-motion 无障碍偏好VueUse usePreferredReducedMotion响应式监听 prefers reduced motion 无障碍偏好 本指南围绕 VueUse前端上一篇猫抓浏览器插件免费解锁网页视频下载的终极解决方案下一篇猫抓浏览器插件三步完成网页视频下载的终极免费方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
