airi 项目中的 VueUse usePreferredDark 实战响应式深色主题偏好检测与暗色模式适配指南【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airiusePreferredDark是 VueUse 在Browser浏览器分类下提供的组合式函数用于以响应式Reactive方式实时追踪用户对深色主题的系统级偏好。在 airi 这类同时包含 Webapps/stage-web、Electron 桌面端apps/stage-tamagotchi、Capacitor 移动端apps/stage-pocket以及大量 Vue 组件库如 packages/stage-ui的多端 Vue 项目中它是实现跟随系统深色模式能力的基础设施。阅读本文后你将掌握usePreferredDark的声明式用法、组件式用法、类型签名理解它与useDark、usePreferredColorScheme的协作关系并能直接照搬到自己的 Vue 组件中实现暗色主题适配。背景usePreferredDark解决什么问题在浏览器中用户可以通过操作系统macOS、Windows、Android、iOS 等的设置项声明自己偏好深色还是浅色界面。浏览器将该偏好暴露为 CSS 媒体查询prefers-color-scheme开发者可以据此调整页面样式。原生写法通常是这样的media (prefers-color-scheme: dark) { /* 深色样式 */ }但 CSS 媒体查询无法直接驱动 Vue 的逻辑状态无法与computed、watch等响应式机制联动。usePreferredDark的定位正是把这条媒体查询翻译成一个ComputedRefboolean当系统偏好为深色时返回true为浅色时返回false并且在系统设置实时变化例如用户在系统设置里切换主题时自动更新无需任何手动监听。在 airi 的.agents技能体系中该函数被归类于 SKILL.md 的 Browser 分类调用规则为AUTO——即只要在 Vue.js / Nuxt 项目中遇到相关需求就应当优先考虑用 VueUse 组合式函数而非自写代码以保证实现简洁、可维护且高性能。快速上手组合式 API 用法最基础的用法只需一行调用import { usePreferredDark } from vueuse/core const isDark usePreferredDark()isDark是一个ComputedRefboolean系统偏好深色时isDark.value true系统偏好浅色时isDark.value false系统主题在运行期间发生变化时isDark.value自动响应式更新。把它与 Vue 的响应式机制组合即可驱动模板、样式类或计算属性。例如在模板中script setup langts import { usePreferredDark } from vueuse/core const isDark usePreferredDark() /script template div :classisDark ? theme-dark : theme-light Current system preference: {{ isDark ? Dark : Light }} /div /template在 packages/stage-ui、apps/stage-web 这类使用 UnoCSS 的页面中isDark还可以直接参与计算属性的派生例如根据系统偏好选择素材深色 Logo 与浅色 Logo 切换。组件式用法UsePreferredDark对于偏好模板语法的场景如选项式 API 组件或简单展示需求VueUse 提供了对应的无渲染组件UsePreferredDark通过默认插槽scoped slot向外暴露prefersDarktemplate UsePreferredDark v-slot{ prefersDark } Prefers Dark: {{ prefersDark }} /UsePreferredDark /templateprefersDark即对应组合式 API 中的isDark.value。这种写法适合在无需额外逻辑、仅需在模板中读取偏好状态的场合例如调试面板、状态展示条等。类型签名与配置项usePreferredDark的完整类型声明如下见 usePreferredDark.md/** * Reactive dark theme preference. * * see https://vueuse.org/usePreferredDark * param [options] * * __NO_SIDE_EFFECTS__ */ export declare function usePreferredDark( options?: ConfigurableWindow, ): ComputedRefboolean需要关注的要点返回类型ComputedRefboolean可直接在模板中自动解包auto-unwrap在script setup中通过.value访问。可选参数options?: ConfigurableWindowVueUse 通用的窗口配置项包含window字段用于指定要监听的目标window对象。这在非浏览器环境或需要模拟窗口对象的测试场景下非常有用——例如 airi 仓库在 Vitest 中为 Electron 主进程、渲染进程与 Web Worker 编写测试时可通过注入自定义window隔离媒体查询环境。__NO_SIDE_EFFECTS__标注表明该函数没有副作用可在任意作用域安全调用便于构建工具的 tree-shaking 与死代码消除。调用规则在 SKILL.md 中其 Invocation 为AUTO即满足场景即可直接使用无需额外安装依赖前提是项目已引入vueuse/core。底层机制它是如何响应式的usePreferredDark的底层实现本质是window.matchMedia((prefers-color-scheme: dark))的封装函数内部创建MediaQueryList通过change事件监听匹配状态变化并将其桥接为 Vue 的ComputedRef。因此它具备以下特性实时性系统级主题切换会通过change事件即时驱动isDark更新零轮询完全基于浏览器原生事件不产生额外的定时器开销SSR 兼容在服务端渲染或无window环境如 Node 测试环境下可通过ConfigurableWindow提供兜底或由上层调用方判断环境。从功能矩阵看VueUse 围绕颜色偏好提供了三个相互关联的组合式函数均位于 references 目录函数返回值语义usePreferredDarkComputedRefboolean是否偏好深色布尔判定usePreferredColorSchemeComputedRefColorSchemeType完整偏好值dark \| light \| no-preferenceuseDarkWritableComputedRefboolean可读写的深色状态带持久化与 DOM 属性同步其中useDark的文档useDark.md明确说明useDark组合了usePreferredDark与useStorage。启动时它优先从 localStorage/sessionStorage键名可配置默认vueuse-color-scheme读取用户主动设置的主题若用户未设置则回退到usePreferredDark读取的系统偏好。当开发者修改isDarkref 时它会更新目标元素的属性默认 Tailwind 风格给html添加或移除dark类并将选择持久化到 storage。也就是说在真实产品中通常的分工是跟随系统的初始值获取 →usePreferredDark用户手动切换 记忆的完整暗色模式方案 →useDark需要区分 no-preference的三态场景 →usePreferredColorScheme。airi 仓库中的实际应用佐证在 airi 的 Electron 桌面端应用 apps/stage-tamagotchi 中渲染进程组件 fade-on-hover.vue 直接使用了同族的useDarkimport { refDebounced, useDark, useMouseInElement } from vueuse/core const isDark useDark({ disableTransition: false })这印证了上述分工在需要用户可主动切换并持久化的界面中项目选择useDark而非裸用usePreferredDark而usePreferredDark作为其内部依赖负责提供系统偏好的响应式来源。仓库各端apps/stage-web、apps/stage-pocket、packages/stage-ui也都随包依赖vueuse/core意味着usePreferredDark可在任意一端直接引入使用。使用建议与注意事项只读偏好不做持久化usePreferredDark是只读的ComputedRef它只反映系统此刻怎么想不负责写入任何存储。需要用户手动覆盖时应切换到useDark可持久化、可写。结合媒体查询设计 CSSusePreferredDark驱动的是 JS 逻辑层。CSS 层面依然建议保留原生media (prefers-color-scheme: dark)兜底避免 JS 未就绪时出现首屏样式闪烁。SSR / 测试环境在服务端渲染或 Node 测试如 airi 仓库在 apps/stage-web、packages/stage-ui 下配置的 Vitest 环境中注意通过ConfigurableWindow注入或守护window是否存在。优先使用而非自研按照 SKILL.md 的决策原则该场景应直接选用 VueUse 组合式函数避免手写matchMedia监听、手动解绑等样板代码降低内存泄漏风险。小结usePreferredDark用一行调用把浏览器底层的prefers-color-scheme媒体查询变成了 Vue 世界里的响应式布尔值是构建默认跟随系统、可选用户覆盖暗色主题体验的第一块基石。它既是独立可用的轻量工具也是useDark的响应式数据源。在 airi 的多端 Vue 技术栈中你可以随时从vueuse/core引入它配合useDark、usePreferredColorScheme与 UnoCSS 的暗色变体以最小成本实现一致、实时、可持久化的深色模式体验。【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考