Vue3+vite 项目中使用 VueUse 的 useResizeObserver 监听元素尺寸变化

1. 为什么要监听元素尺寸变化

在2023年的Web应用开发中，超过78%的前端项目需要处理响应式布局需求。当我们开发仪表盘、数据可视化系统或自适应表单时，常常会遇到一个核心问题：如何准确感知DOM元素的尺寸变化。传统解决方案中，开发者往往需要手动监听window.resize事件并结合MutationObserver实现，这种组合拳不仅代码量庞大，还会遇到性能卡顿和回调触发不精确的问题。

这正是VueUse库中useResizeObserver的用武之地。它基于ResizeObserver API封装，提供声明式的尺寸监听方案，与Vue3的响应式系统完美融合。接下来我们将通过具体场景，深入探讨这个"小而美"的工具函数。

2. 基础环境搭建

在开始示例前，我们先初始化一个标准的Vue3项目 （技术栈：Vue3.3 + Vite5.0）：

npm create vite@latest vue-resize-demo --template vue-ts
cd vue-resize-demo
npm install @vueuse/core

3. 基础用法演示

3.1 基本监听实现

<script setup lang="ts">
import { ref } from 'vue'
import { useResizeObserver } from '@vueuse/core'

// 创建目标元素的引用
const target = ref<HTMLElement>()
const boxRef = ref<HTMLElement>()

// 响应式记录尺寸状态
const dimensions = ref({ width: 0, height: 0 })

// 启动尺寸监听
useResizeObserver(target, (entries) => {
  const entry = entries[0]
  dimensions.value = {
    width: entry.contentRect.width,
    height: entry.contentRect.height
  }
})
</script>

<template>
  <!-- 可拖拽调整大小的容器 -->
  <div ref="target" class="resizable-box">
    当前尺寸：{{ dimensions.width }}x{{ dimensions.height }}
  </div>

  <!-- 联动变化的子元素 -->
  <div 
    ref="boxRef" 
    :style="{ 
      width: `${dimensions.width / 2}px`,
      height: `${dimensions.height}px`
    }"
  >
    自适应子元素
  </div>
</template>

<style>
.resizable-box {
  resize: both;
  overflow: auto;
  border: 2px dashed #ccc;
  padding: 20px;
  max-width: 800px;
  min-width: 300px;
}
</style>

代码解析：

1. 通过ref获取目标DOM引用
2. 使用解构赋值获取useResizeObserver的返回方法
3. 在回调函数中获取精确的contentRect尺寸数据
4. 将尺寸变化同步到响应式状态
5. 子元素根据主容器尺寸进行动态调整

3.2 高级联动示例

<script setup lang="ts">
import { useResizeObserver } from '@vueuse/core'

const dashboardRef = ref<HTMLElement>()
const chartSizes = reactive({
  main: { width: 0, height: 0 },
  aside: { width: 0, height: 0 }
})

// 主看板尺寸监听
useResizeObserver(dashboardRef, (entries) => {
  const { width, height } = entries[0].contentRect
  chartSizes.main = {
    width: width * 0.7,
    height: height - 60
  }
  chartSizes.aside = {
    width: width * 0.28,
    height: height - 40
  }
})
</script>

<template>
  <div ref="dashboardRef" class="dashboard-container">
    <ECharts 
      :width="chartSizes.main.width"
      :height="chartSizes.main.height"
    />
    
    <div class="aside-panel">
      <StatisticsPanel 
        :size="chartSizes.aside"
      />
    </div>
  </div>
</template>

场景特点：

• 实现主内容区与侧边栏的尺寸联动
• 动态计算图表容器的预留空间（考虑边距和标题栏）
• 支持多组件间的尺寸依赖关系

4. 核心特性解析

4.1 智能节流控制

useResizeObserver内部实现了requestAnimationFrame优化，可以有效避免高频触发导致的性能问题。当我们需要自定义触发频率时，可以结合useDebounceFn：

import { useDebounceFn } from '@vueuse/core'

const debouncedHandler = useDebounceFn((entry) => {
  // 处理逻辑
}, 200)

useResizeObserver(target, (entries) => {
  debouncedHandler(entries[0])
})

4.2 多元素监听策略

通过Map结构管理多个元素的监听状态：

const observables = new Map()
const elements = [ref1, ref2, ref3]

elements.forEach((el, index) => {
  useResizeObserver(el, (entries) => {
    observables.set(index, entries[0].contentRect)
  })
})

5. 应用场景剖析

5.1 响应式布局系统

在管理系统侧边栏折叠场景中，实现内容区的平滑过渡：

const contentRef = ref()

useResizeObserver(contentRef, ({ contentRect }) => {
  contextMenuStore.setPositionConstraint({
    maxX: contentRect.width - 20,
    maxY: contentRect.height - 40
  })
})

5.2 数据可视化领域

ECharts图表容器的自适应处理：

const chartRef = ref()
let chartInstance: echarts.ECharts | null = null

useResizeObserver(chartRef, ({ contentRect }) => {
  chartInstance?.resize({
    width: contentRect.width,
    height: contentRect.height
  })
})

5.3 表单动态编排

动态调整表单元素的排列方式：

const formContainer = ref()
const isVertical = ref(false)

useResizeObserver(formContainer, ({ contentRect }) => {
  isVertical.value = contentRect.width < 768
})

6. 技术方案对比

7. 注意事项

1. 内存管理：在onUnmounted时自动清除监听器，避免内存泄漏
2. SSR兼容：在服务端渲染时使用条件引入

   import { useResizeObserver } from '@vueuse/core'
   
   if (process.client) {
     useResizeObserver(...)
   }
   

3. 布局抖动优化：在频繁变化的场景下，建议搭配CSS的transform属性使用
4. 版本兼容性：
   • VueUse >= 8.0
   • Vue3 >= 3.2
   • Chrome >= 64

8. 工程实践建议

1. 将尺寸逻辑封装为自定义Hook：

   export function useElementDimensions(ref: Ref<HTMLElement>) {
     const dims = reactive({ width: 0, height: 0 })
   
     useResizeObserver(ref, ([entry]) => {
       dims.width = entry.contentRect.width
       dims.height = entry.contentRect.height
     })
   
     return dims
   }
   

2. TypeScript类型增强：

   declare module '@vueuse/core' {
     interface UseResizeObserverOptions {
       precision?: number
     }
   }
   

9. 总结与展望

useResizeObserver作为现代响应式开发的重要工具，极大简化了元素尺寸监听的实现难度。它与Vue3的组合式API完美契合，支持从简单到复杂的多层级场景。随着ResizeObserver API的浏览器支持率已达95%以上，这项技术已经成为响应式开发的必备技能。

未来我们可以期待：

• 与CSS容器查询更深度整合
• 机器学习驱动的自适应布局预测
• WebAssembly加持的性能优化方案