企业官网建设流程全解析

• 前端

设备像素比（devicePixelRatio）是前端做高清屏适配、Canvas 绘制缩放、图片清晰度判断时的核心指标。本文深入解读 VueUse 中 useDevicePixelRatio 的实现原理与用法：它如何在没有任何devicePixelRatio事件监听的前提下，借助matchMedia与媒体查询resolution实现像素比的响应式追踪，并覆盖函数式调用、组件式调用、SSR 行为与自定义window场景。读完本文，你将能够直接复用这一 API，并理解其底层机制。

为什么需要 useDevicePixelRatio

window.devicePixelRatio返回当前显示设备在物理像素与 CSS 像素之间的比率（例如 Retina 屏通常为 2）。但它有一个关键限制：浏览器没有提供任何监听devicePixelRatio变化的事件。用户缩放页面（zoom）或把窗口拖到不同缩放系数的屏幕时，像素比会变化，却无法用传统的事件监听方式感知。

这正是useDevicePixelRatio存在的意义。在 VueUse 的官方文档 packages/core/useDevicePixelRatio/index.md 中明确指出：该函数利用window.matchMedia与resolution媒体查询，应用了与 MDN 监测屏幕分辨率/缩放级别示例完全相同的机制。

快速上手：函数式调用

与 VueUse 其他 composable 一样，useDevicePixelRatio从@vueuse/core导出（见 packages/core/index.ts），最基本的用法只需一行：

import { useDevicePixelRatio } from '@vueuse/core' const { pixelRatio } = useDevicePixelRatio()

pixelRatio是一个只读的ShallowRef<number>，随设备像素比变化自动更新。在组件模板中可以直接解包使用：

<script setup lang="ts"> import { useDevicePixelRatio } from '@vueuse/core' const { pixelRatio } = useDevicePixelRatio() </script> <template> <p>当前设备像素比：{{ pixelRatio }}</p> </template>

官方演示 demo.vue 还展示了如何在页面上实时渲染该值，并提示读者“缩放页面或把窗口移到不同缩放系数的屏幕，即可看到数值变化”——这正是验证响应式追踪是否生效的简单方法。

组件式调用：UseDevicePixelRatio

useDevicePixelRatio同时提供了对应的渲染组件 component.ts，组件名为UseDevicePixelRatio。它通过作用域插槽（scoped slot）向模板暴露返回值：

<template> <UseDevicePixelRatio v-slot="{ pixelRatio }"> Pixel Ratio: {{ pixelRatio }} </UseDevicePixelRatio> </template>

从源码看，该组件基于defineComponent实现（packages/core/useDevicePixelRatio/component.ts）：

• 组件内部将useDevicePixelRatio(props)的返回值包裹成reactive对象；
• 渲染函数中若存在默认插槽，则将data作为插槽数据传出；
• 组件声明了唯一的 propwindow，用于传入自定义window实例。

因此组件用法与函数用法能力完全等价，适合在无法使用<script setup>的模板场景（如纯模板驱动的配置）下使用。

核心原理：用 matchMedia 追踪不可监听的变化

关键技巧：将像素比转化为媒体查询

window.devicePixelRatio没有change事件，但matchMedia监听的媒体查询变化却是有事件的。于是源码（packages/core/useDevicePixelRatio/index.ts）做了这样的转化：

const pixelRatio = shallowRef(1) const query = useMediaQuery(() => `(resolution: ${pixelRatio.value}dppx)`, options) let stop: WatchStopHandle = noop if (window) { stop = watchImmediate(query, () => pixelRatio.value = window!.devicePixelRatio) }

这里有两个巧妙之处：

1. 构建分辨率查询：(resolution: 1dppx)表示“当 1 CSS 像素内包含 1 个物理像素时匹配”。当devicePixelRatio变为 2 时，该查询不再匹配，matchMedia的change事件随即触发——像素比的变化就这样被“翻译”成了可以监听的媒体查询变化。
2. 自引用循环刷新：查询字符串内部引用了pixelRatio.value本身。当像素比变化导致查询不匹配时，useMediaQuery更新matches值；watchImmediate监听到这个变化后，立即把window.devicePixelRatio的新值写回pixelRatio。新值又改变查询字符串（例如从1dppx变成2dppx），新一轮媒体查询重新建立，从而持续追踪后续变化。

底层依赖链：useMediaQuery → matchMedia + change 事件

useDevicePixelRatio复用了 VueUse 的通用媒体查询 composable useMediaQuery。useMediaQuery内部完成三件事：

1. 通过useSupported(() => window && 'matchMedia' in window && typeof window.matchMedia === 'function')做能力检测（packages/core/useMediaQuery/index.ts），不支持的运行环境（如旧浏览器）返回false匹配结果；
2. 用window.matchMedia(toValue(query))建立MediaQueryList并读取初始匹配状态；
3. 通过useEventListener(mediaQuery, 'change', handler, { passive: true })注册change监听（packages/core/useMediaQuery/index.ts），事件触发时更新matches。

由于useMediaQuery返回的是computed(() => matches.value)（packages/core/useMediaQuery/index.ts），watchImmediate(query, ...)实际上就是在观察这个计算值的翻转，从而驱动pixelRatio的同步更新。

watchImmediate：确保初始值立即同步

源码使用watchImmediate而非普通watch。查看其实现（packages/shared/watchImmediate/index.ts）：

export function watchImmediate<T = any>(source: T, cb: any, options?: Omit<WatchOptions, 'immediate'>) { return watch(source, cb, { ...options, immediate: true }) }

它只是{ immediate: true }的语法糖。之所以必须立即执行一次回调，是因为pixelRatio初始值为1，而真实设备像素比可能不是 1——首次挂载时就需要立刻用window.devicePixelRatio覆盖初始值，否则首帧渲染会读到错误的占位值。

API 签名与返回结构

综合类型声明与源码（packages/core/useDevicePixelRatio/index.ts），完整的 API 签名如下：

export interface UseDevicePixelRatioOptions extends ConfigurableWindow {} export interface UseDevicePixelRatioReturn { pixelRatio: Readonly<ShallowRef<number>> stop: WatchStopHandle } export declare function useDevicePixelRatio( options?: UseDevicePixelRatioOptions, ): UseDevicePixelRatioReturn

返回对象包含两个成员：

其中pixelRatio通过shallowReadonly包装（packages/core/useDevicePixelRatio/index.ts），外部无法直接改写，保证追踪结果的一致性。

options：ConfigurableWindow

UseDevicePixelRatioOptions继承自ConfigurableWindow（定义见 packages/core/_configurable.ts），唯一的可选配置项是：

interface ConfigurableWindow { window?: Window }

window用于指定自定义的 window 实例，典型场景包括：

• iframe 场景：需要追踪 iframe 内部文档的像素比；
• 测试环境：在单元测试中注入 mock 的window对象。

源码中的解构默认值体现了 VueUse 的 SSR 友好设计：

const { window = defaultWindow } = options

其中defaultWindow = isClient ? window : undefined（packages/core/_configurable.ts）。因此在服务端渲染环境下window为undefined，if (window)分支不会执行，追踪逻辑被跳过，pixelRatio保持初始值1，stop则为noop，不会在 SSR 期间访问浏览器 API 或产生副作用。

返回值的使用与清理

在实际组件中，stop提供了手动停止追踪的能力：

const { pixelRatio, stop } = useDevicePixelRatio() // 某些条件满足时停止追踪 stop()

若不需要手动控制，无需关心清理问题——内部watch会在组件卸载时由 Vue 自动 dispose；useMediaQuery内部通过useEventListener注册的change监听也会随组件作用域一起清理，不会造成内存泄漏。

边界情况与适用前提

• 浏览器兼容性：该方案依赖matchMedia及resolution媒体查询支持（useSupported会做能力检测），在极老的浏览器中可能无法追踪像素比变化；
• SSR 环境：服务端渲染时返回初始值1且不启动监听，客户端注水（hydration）后才会反映真实像素比；
• 初始值：pixelRatio初始为1，挂载后由watchImmediate立即纠正为真实值，因此在首个异步副作用读取前应避免直接信任初始值；
• 多屏拖拽：将窗口拖到不同缩放系数的显示器，resolution媒体查询同样会触发变化，因此该方案天然覆盖“跨屏改变缩放”的场景。

小结

useDevicePixelRatio是 VueUse 中一个典型的“借道监听”范例：在目标 API 没有事件机制时，通过matchMedia+resolution媒体查询把变化转化为可监听事件，再以watchImmediate自引用循环完成响应式闭环。掌握这一思路，你也能推广到其他“不可监听”的浏览器 API 场景。相关源码与演示均可直接在仓库中查看：实现、组件封装、文档、演示。

• 前端