如果你写过一个带折叠侧边栏的后台管理系统八成遇到过这种诡异场景浏览器窗口明明没变过但页面中间那块内容区的宽度跟着侧边栏的收起、展开默默变了图表组件却还保持着原来的尺寸图上全是留白。我第一次碰到这个问题时第一反应是给window挂一个resize监听然后在回调里手动去拿内容区的宽度代码写得又丑又脆换个组件就得再复制一份。后来我把这套逻辑换成 ResizeObserver才算真正把“容器尺寸变了”当成一个一等公民事件去处理。这篇文章想把我对 ResizeObserver 的理解从头梳理一遍包括它内部的执行时机、回调参数里容易被忽略的细节、我自己项目里沉淀出来的几种落地模式以及几个非常隐蔽的坑。适合正在写自适应组件、图表适配、虚拟列表的前端开发者尤其是已经被window.resize和轮询尺寸折腾过几轮的人。1. 窗口监听救不了自适应需求ResizeObserver 到底补了哪块空白1.1 为什么 window.resize 让布局代码越写越拧巴window.resize是前端最初拿来做自适应的唯一原生方案但它本质上只告诉你一件事视口大小变了。问题在于现代布局里元素的尺寸经常会在视口完全没动的情况下发生变化。拿最常见的侧边栏折叠来说。侧边栏从 240px 收起来变成 48px主内容区的宽度从calc(100% - 240px)变成calc(100% - 48px)这个宽度变化是真实发生的但window的尺寸一个像素都没变resize事件根本不会触发。这时候你要么在侧边栏组件里广播一个自定义事件要么用状态管理库同步通知所有依赖宽度的组件去重新测量。前者写起来快但维护两三个月后到处都是监听器后者看似规范实际上一处状态更新会牵动十几个组件各自跑一遍测量逻辑性能损耗先不谈组件之间隐式耦合的味儿就已经很冲了。类似的场景还有父容器里内容增多导致换行、字体异步加载完成后文字宽度改变、图片加载完成后把容器撑高、iframe 内部页面高度变化导致外层容器高度变化。这些情况里视口都没有动但目标元素的尺寸确实变了。window.resize对此完全无能为力。很多人尝试过一种变通在resize回调里遍历所有可能变化的容器逐个读取尺寸并做 diff。这种方案确实能覆盖一部分场景但它把“视口事件”硬生生翻译成了“元素事件”属于用一个模糊信号去推导精确信号推导过程里还得自己处理各种边界情况。ResizeObserver 出现的意义就是让你不再去做这种翻译。1.2 轮询尺寸在性能上是慢性自杀在没有 ResizeObserver 的年代另一个通行做法是轮询用setInterval每隔一段时间调用一次getBoundingClientRect()对比前后尺寸来感知变化。这个方法能解决问题但代价很隐蔽。getBoundingClientRect这类布局属性在读取时如果浏览器存在待处理的样式变更或布局计算就会强制同步执行它这在性能术语里叫强制同步布局forced synchronous layout。哪怕浏览器有缓存高频调用本身也是在不断触碰布局系统。假设页面上有二十个卡片组件每个组件各自开一个 100ms 的定时器做尺寸轮询一秒钟就是两百次布局读取。这些调用互相之间没有协调也没有合并很容易把 Performance 面板刷成一片紫色。轮询还有另一个问题你很难选对轮询频率。间隔太长尺寸变化被发现得太晚动画和联动会出现明显延迟间隔太短主机被白白消耗在无意义的查询上。而需求往往是多变的今天 100ms 够用明天组件复杂了可能就会出现闪烁。ResizeObserver 的设计思路完全不同。它对目标元素生效的时机是浏览器渲染管线内部由浏览器自己判断“目标元素的实际渲染尺寸是否变化”。没有变化时它几乎不产生额外消耗有变化时它会把同一帧内多个元素的尺寸变化合并成一次回调批量派发。这种“浏览器替你节流”的能力恰恰是手写轮询最难实现的。1.3 它和 MutationObserver、IntersectionObserver 的分工边界很多初学者会把前端几个 Observer API 混在一起其实它们的分工是很清晰的。Observer监听内容触发时机典型场景ResizeObserver元素尺寸变化layout 之后、paint 之前容器自适应、图表 resize、虚拟列表高度校正MutationObserverDOM 树结构、属性变化DOM 变更发生之后异步回调节点增删、class 切换、属性变更的响应IntersectionObserver元素与视口或指定根元素的交叉比例滚动、布局变化导致的可见性变化懒加载、曝光埋点、吸顶判断它们之间不是替代关系而是配合关系。拿动态渲染的卡片列表举例卡片插入 DOM 这件事可以交给框架或MutationObserver去感知卡片是否进入视口是IntersectionObserver的分工卡片渲染后实际占了多少高度、宽度有没有变化才轮到ResizeObserver出手。指望用任何一个 Observer 去覆盖其他两个的职责基本都会写出拧巴的代码。我见过一个反面案例有人想用MutationObserver监听某个容器通过它的childList变化来判断内容是否被撑开。但实际上节点变化并不等于尺寸变化图片还没加载完的时候节点早就挂上去了尺寸几秒后才变。这本质上是把接口用错了地方。如果真想监听尺寸就该用 ResizeObserver而不是绕道 DOM 树。2. 回调触发的真实时点渲染流水线的缝隙里藏着什么2.1 一次 resize 回调发生在 layout 之后、paint 之前浏览器的渲染主线程通常经历这样一条链路解析 HTML 和 CSS、计算样式style、计算布局layout、绘制paint。ResizeObserver 的回调被设计在 layout 完成之后、paint 开始之前批量派发这个时机是刻意的。为什么这个时机重要因为回调执行时ResizeObserverEntry里拿到的尺寸已经是当前这一帧最终的布局尺寸。如果回调被设计在 layout 之前触发拿到的就是上一帧的过时尺寸如果被设计在 paint 之后触发那修改尺寸又得被迫多等一帧响应就慢了。当前这个位置让“读取尺寸”和“修改样式”可以衔接得足够顺又不至于扰乱绘制流程。对比一下全局resize事件它的派发时点在不同浏览器里实现有差异事件触发之后不保证布局已经稳定。所以老代码里经常能看到setTimeout(() { /* 再量一次 */ }, 0)这种脏操作就是为了等布局收敛。ResizeObserver 把“什么时候量”这个问题交给了浏览器内部开发者不需要再猜。这里还有一个特别容易忽略的点首次调用observe()时回调会被立刻触发一次哪怕元素尺寸根本没变过。这是规范刻意设计的目的是让你拿到初始尺寸建立起点状态。很多人第一次写 RO 时会惊讶“我还没改尺寸它怎么就调用了”其实这不是 bug是特性。如果业务上不希望初始触发的逻辑执行需要自己在回调里加一个标志位或者初始化判断。2.2 entry 对象的三件套别再把 contentRect 当唯一信息源回调参数里收到的是一个ResizeObserverEntry数组数组里常用到三类信息target、contentRect、以及几个尺寸数组。target明确告诉你这次是哪个元素变了contentRect返回的是内容盒content box的矩形信息而尺寸数组则包含更精细的盒子尺寸。用一个具体的元素来说明。假设有一个div宽度 300px、高度 150px内边距padding: 20px边框border: 5px。默认观察content-box时contentRect.width 300 - 20*2 - 5*2 250contentRect.height 150 - 20*2 - 5*2 100contentRect.x 5 20 25contentRect.y 25contentBoxSize[0].inlineSize 250blockSize 100borderBoxSize[0].inlineSize 300blockSize 150这里inlineSize和blockSize是逻辑尺寸概念。横排书写模式下inlineSize对应宽度blockSize对应高度一旦碰到竖排书写模式语义就互换。理解这一点遇到国际化页面或特殊排版时才不会糊涂。另外contentBoxSize、borderBoxSize在规范里是数组不是单值。大部分场景下只有一个元素取[0]是对的但遇到多列布局columns时数组长度会超过 1这一点放在后面“坑”的部分展开。早期浏览器对borderBoxSize的支持不一致有的实现干脆不返回它所以稳妥的写法是先判断是否存在const entry entries[0]; const width entry.borderBoxSize?.[0]?.inlineSize ?? entry.contentRect.width; const height entry.borderBoxSize?.[0]?.blockSize ?? entry.contentRect.height;这个可空链写法兼容性很好我后来所有封装里都用了它。2.3 box 观察模式content-box、border-box、物理像素怎么选observe()的第二个参数可以指定观察哪种盒子target.observe(el, { box: content-box }); // 默认 target.observe(el, { box: border-box }); target.observe(el, { box: device-pixel-content-box });默认的content-box适合关注内容区域的场景。比如图表要绘制在内容区里padding 和 border 的变化不应该触发重绘那就观察 content-box。border-box适合关注元素整体占位的场景比如一个组件的整体视觉尺寸变了要通知外部布局联动用 border-box 更贴合 CSS 盒模型的感知。device-pixel-content-box返回的是物理像素尺寸移动端高分屏上做 canvas 绘制时特别有用可以直接拿到设备的真实像素数避免devicePixelRatio换算这一层心智负担但这个能力在部分浏览器上支持得比较晚生产环境里我会先做特性检测再决定用不用。还有一个容易迷惑的点不管observe时选的哪种 boxentry.contentRect永远返回 content-box 的尺寸。这是规范写死的不是浏览器实现差异。所以你想拿 border-box 的宽高别指望从contentRect里读必须老老实实去读borderBoxSize数组。3. 项目里频繁用到的高频模式从 textarea 到图表再到虚拟列表3.1 textarea 自动增高与其监听输入不如观察结果textarea 自动增高这个需求几乎所有做表单的人都写过。传统思路是监听input事件然后把height设为auto再读取scrollHeight把高度撑起来。问题在于值一变就觉得要重算实际上一个字符的变化可能根本不会影响换行结果白白跑了一整套测量。换一个视角高度自适应的本质是“元素的尺寸随着内容变化而变化”所以可以用 ResizeObserver 来承接“尺寸最终变了”这一信号。const ta document.querySelector(textarea); const ro new ResizeObserver((entries) { const height entries[0].borderBoxSize?.[0]?.blockSize; // 这里不做修改自身尺寸的操作只负责通知外部联动比如调整父容器间距 notifyExternal(height); }); ta.addEventListener(input, () { ta.style.height auto; ta.style.height ta.scrollHeight px; }); ro.observe(ta);这套组合的思路是input事件负责主动修改高度ResizeObserver 负责被动感知最终尺寸两者各司其职。如果你在 RO 回调里又去改ta.style.height那就是自己观察自己、自己改自己早晚触发循环告警。是我用下来的一个红线RO 回调里尽量少写“修改被测元素自身几何属性”的代码。3.2 图表自适应与 ECharts 的 resize 协作方式图表库是 ResizeObserver 最常见的受益者。大多数图表库只监听window.resize页面里侧边栏一折叠图表就变成了被拉伸过的“哈哈镜”。用 RO 接管图表的 resize 调用时不建议在回调里直接执行chart.resize()因为高频触发时它内部要重新计算布局、可能还要强读容器尺寸开销不小。const container document.getElementById(chart); const chart echarts.init(container); let rafId 0; const ro new ResizeObserver(() { cancelAnimationFrame(rafId); rafId requestAnimationFrame(() { chart.resize(); }); }); ro.observe(container);这样修改后侧边栏折叠时图表会跟随容器宽度变化而且 resize 动作被对齐到帧上不会在一帧里重复执行。再进一步还可以从 entry 里直接拿到精确尺寸减少图表库内部再做一次 DOM 测量const ro new ResizeObserver((entries) { const entry entries[0]; const width entry.borderBoxSize?.[0]?.inlineSize ?? entry.contentRect.width; const height entry.borderBoxSize?.[0]?.blockSize ?? entry.contentRect.height; chart.resize({ width, height }); });这个做法有三层价值省掉了多余的布局读取、让回调逻辑保持纯函数式、也让测试更容易 mock。3.3 虚拟列表高度校正RO 与 IntersectionObserver 组合拳虚拟列表最怕什么最怕列表项的真实高度和预设占位高度不一致。图片加载、字体渲染、异步内容插入都会让实际高度偏差一旦偏差滚动位置就会抖动。我常用的组合是 IO 负责“什么时候渲染”RO 负责“渲染后真实高度是多少”。const io new IntersectionObserver((entries) { entries.forEach((e) { if (e.isIntersecting) renderItem(e.target); }); }); const ro new ResizeObserver((entries) { entries.forEach((entry) { const height entry.contentRect.height; updateVirtualListCache(entry.target, height); }); });这里有一个细节不要对未进入视口的元素去做 RO 监听。一个超长列表可能有几百上千个待渲染的占位项如果全部挂 RO即使它们尺寸不会变化观察器本身也是一笔不小的开销。先用 IO 过滤可见性等到真正要渲染内容了再挂 RO性能会好很多。还有一种拖拽调宽的场景列表项宽度变化后高度跟着变化这个变化也会被 RO 捕捉到并反馈给虚拟缓存从而让滚动计算始终基于最新数据。3.4 一个小而美的 React HookuseElementSizeReact 项目里最常用的形式是把这个能力封装成一个 Hook组件里直接拿引用和尺寸。下面这个版本我一直在用逻辑很简单但几个关键点都处理到了import { useEffect, useRef, useState } from react; function useElementSize() { const ref useRef(null); const [size, setSize] useState({ width: 0, height: 0 }); useEffect(() { const el ref.current; if (!el) return; let rafId 0; const ro new ResizeObserver((entries) { const entry entries[0]; const { width, height } entry.contentRect; cancelAnimationFrame(rafId); rafId requestAnimationFrame(() { setSize({ width, height }); }); }); ro.observe(el); return () { cancelAnimationFrame(rafId); ro.disconnect(); }; }, []); return { ref, size }; }两点经验。第一尺寸读取用entry.contentRect而不是el.offsetWidth前者直接从 entry 里来不需要额外读取 DOM后者则可能触发强制同步布局。第二setSize放在 rAF 里执行防止 RO 在同一帧内多次触发导致 React 渲染次数过多。React 18 下并发渲染也没什么问题因为尺寸更新被对齐到了帧边界不会在同一帧里反复调度。4. 最容易在这几个地方翻车反复出现的坑与排查思路4.1 ResizeObserver loop limit exceeded循环触发到底怎么来的我第一次遇到这个警告是在一个图表页面上控制台刷出ResizeObserver loop limit exceeded的时候整个人是懵的。查了一圈才弄明白浏览器的 RO 回调是在渲染流程内部派发的如果回调里又改了元素的尺寸就会产生新的尺寸变化浏览器在同一帧里继续派发回调然后再次修改、再次派发。为了防止这个循环拖垮主线程浏览器会做限制超出限制就打印这条警告。最常见的触发原因有三种回调里直接改了被测元素的style.width/height回调触发了 React 的setState渲染结果又改变了被测元素的样式多个元素的尺寸互相影响形成“A 变 B 变 A 变”的连锁反应。规避手段其实不复杂回调里不要修改被测元素的几何属性如果确实要改用requestAnimationFrame推迟到下一帧并且加条件判断只有尺寸真的变化超过阈值才动手如果 A、B 两个元素互相影响给回调加一个防抖让改动集中生效。我后来几乎所有的 RO 封装里都会遵循“回调只读数、业务推迟到 rAF”的模式这个习惯帮我避开了绝大多数循环告警。4.2 回调里读布局属性强制同步布局的隐藏开销RO 回调执行的时点在 layout 之后理论上此时读布局属性是有缓存的。但如果你在回调里先改了某个元素的高度转手又去读另一个元素的clientWidth浏览器就不得不立刻重新跑一遍布局这就是强制同步布局。更麻烦的是强制同步布局引起的布局变化还会产生新的 RO 回调两个机制叠加在一起很容易出现“读了又改、改了又读”的恶性循环。我排查过一次线上卡顿Performance 录制里能看到大量layout紫色块源头就是一个 RO 回调里既改了容器宽度又读了内部某个文本节点的offsetWidth。正确做法是回调里需要的信息尽量从entry里拿实在拿不到需要手动读取的先记下来在下一帧 rAF 里再读。RO 的好处是它已经把“尺寸变了”的信号告诉你并不要求你在同一帧里把后续动作全做完慢半拍完全没关系而且更稳。4.3 borderBoxSize 数组不等于单值多列布局的特殊语义CSS 多列布局columns: 3会把一个元素的内容拆成多列渲染视觉上是一排并列的块。这时候这个元素在浏览器内部对应的是多个片段fragmentborderBoxSize数组的长度就会大于 1每一项对应一个片段的尺寸。很多人在封装组件时直接在回调里写entry.borderBoxSize[0].inlineSize在普通布局下没问题一旦元素被放进多列容器里拿到的只是其中一个片段的宽度不是元素整体占用的宽度结果就是布局联动完全失真。那到底什么时候该用contentRect什么时候该用borderBoxSize我的判断标准是如果我只想知道“这个元素整体多宽多高”用contentRect.width/height它在多列布局下返回的是整体内容盒不会带你进沟里如果我明确需要 border-box 级别的尺寸且确定不会遇到多列再取数组第一项。处理跨列场景时要么遍历数组求和但这在语义上不一定对要么就换用整体属性的 API。写 polyfill 的人尤其要注意这个数组语义我自己写轻量实现时就在这翻过车。4.4 display:none、字体切换与 transform哪些情况不触发或触发得很意外RO 的触发规则有几个容易想当然的盲区逐个说。display: none会让元素尺寸变成 0RO 会触发一次回调而且首次observe时如果元素本身是隐藏的回调第一次就会给你一个 0 尺寸。从display: none恢复显示时又会触发一次从 0 到有效尺寸的回调。所以做动画或者做初始化判断时一定要考虑“尺寸为 0”这个状态不然会莫名闪现或触发不必要的重绘。字体加载是 RO 的一个隐藏收益点。font-face字体加载完成后文字宽度变化容器尺寸跟着变RO 会自然触发。这其实是好事很多项目还在用历史悠久的document.fonts.ready去手动校正布局RO 相当于帮你自动捕获了字体渲染完成后的一切变化。transform: scale()不触发 RO。它是视觉变换不改变布局尺寸所以scale(0.5)在布局系统里宽度不变RO 感知不到。这一点如果你试图用 RO 去做缩放联动一定会踩坑。还有一点浏览器窗口缩放导致元素尺寸变化时 RO 会触发但它和window.resize的派发时机在不同浏览器里可能不同别硬编码“先 resize 后 RO”这种顺序依赖。代码只要写成“只处理最终尺寸不依赖谁先谁后”就不会出问题。5. 兼容性策略与压榨性能的封装技巧5.1 原生优先polyfill 能不用就不用ResizeObserver 现在的兼容性已经相当能看了。Chrome 64 起支持、Firefox 69 起支持、Safari 13.1 起支持Edge 基于 Chromium 后也全量支持。对现代项目来说原生 API 完全可以放心用。那 polyfill 还有没有存在的价值有但仅限于需要兼容特别老的 WebKit 内核比如某些内嵌浏览器内核的应用的场景。而且必须清楚它的本质polyfill 通常是通过定时器轮询加尺寸对比来实现的API 形状可以做得一样但“在渲染管线内部高效批量派发”这个特性是补不出来的。也就是说polyfill 只是让你写代码不报错性能上跟原生 API 完全是两码事。如果确实要引入 polyfill记得确保只引入一次并且不要和原生实现冲突。用打包器时最好先判断一下typeof ResizeObserver ! undefined不要一问就塞 polyfill 进 bundle。我见过一些项目所有现代浏览器都支持原生了bundle 里还带着 3KB 的 polyfill 在跑纯属多余。5.2 RO 已做了帧级批量为什么业务层还得配合 rAF有人会问RO 不是已经自动合并同一帧的多次变化了吗为什么回调里还要再包一层requestAnimationFrame先说结论RO 合并的是“通知”本身它保证同一帧里多个元素尺寸变化你只回调一次。但你的回调内部如果做了重逻辑比如重绘图表、更新 React 状态、调用一个重型布局方法那么这一帧里的开销依然不小。而 RO 回调是浏览器主线程流程的一部分在这里执行越久留给 paint 的时间就越少用户能感知到掉帧。再包一层 rAF 的意思是RO 只负责告诉你“有变化发生”真正处理变化的工作放到下一帧的渲染任务里去做。这样即使同一帧里有两次 RO 回调第二段业务逻辑也会被cancelAnimationFrame取消并重新安排保证一帧里最多执行一次。function observeResize(el, callback) { let width 0; let height 0; let rafId 0; const ro new ResizeObserver((entries) { const entry entries[0]; const nextWidth entry.borderBoxSize?.[0]?.inlineSize ?? entry.contentRect.width; const nextHeight entry.borderBoxSize?.[0]?.blockSize ?? entry.contentRect.height; if (nextWidth width nextHeight height) return; width nextWidth; height nextHeight; cancelAnimationFrame(rafId); rafId requestAnimationFrame(() { callback(width, height); }); }); ro.observe(el); return () { cancelAnimationFrame(rafId); ro.disconnect(); }; }这段代码里我做了三件小事先用borderBoxSize优先、contentRect兜底加了一个尺寸相等判断避免没有变化也触发 rAF用cancelAnimationFrame保证一帧内最多一次业务回调。看起来不起眼但组合起来在高频变化场景下非常稳。5.3 一个可复用的 observeResize 封装最后给一个更泛化的版本适合一个页面里多个元素都要监听尺寸的情况。核心是用WeakMap管理每个元素的观察器同一个元素复用一套监听逻辑多个业务回调用Set存起来互不干扰。const registry new WeakMap(); export function watchResize(el, handler) { if (registry.has(el)) { registry.get(el).handlers.add(handler); return () { const record registry.get(el); record.handlers.delete(handler); if (!record.handlers.size) { record.ro.disconnect(); registry.delete(el); } }; } const handlers new Set([handler]); const ro new ResizeObserver((entries) { for (const entry of entries) { const size { width: entry.borderBoxSize?.[0]?.inlineSize ?? entry.contentRect.width, height: entry.borderBoxSize?.[0]?.blockSize ?? entry.contentRect.height, }; handlers.forEach((fn) fn(size, entry)); } }); ro.observe(el); registry.set(el, { ro, handlers }); return () { handlers.delete(handler); if (!handlers.size) { ro.disconnect(); registry.delete(el); } }; }这里有几个设计细节值得解释。用WeakMap而不是普通对象是为了避免元素被垃圾回收后 key 还留在内存里造成泄漏。同一个元素挂多个 handler 时复用同一个 RO避免重复观察。最后一个 handler 移除时自动调用disconnect减少无谓开销。这套思路同样适用于自定义事件、状态管理订阅等场景算是一个比较通用的注册中心模式。这套工具我用到现在快两年了说句实话真正帮我省时间的不是 API 本身多难掌握而是它让我把代码的视角从“全局视口”切换到了“单个元素本身”。下次再遇到需要监听某个区块尺寸的场景建议你先想清楚它到底在等哪个信号、尺寸变了之后要去联动谁、会不会自己改自己触发循环想通了再动手方案基本不会跑偏。
