浏览器与 Web API / 系统课时
使用 ResizeObserver 监听尺寸
使用 ResizeObserver 监听尺寸
本课实现一个可拖拽改变宽度的响应式面板:你将读取内容盒或边框盒尺寸,在组件自身变窄时切换布局,并用“回调只读、下一帧写入”的方式降低重复通知和观察循环风险。
学习目标
- 区分
content-box、border-box与对应的尺寸数据。 - 使用
ResizeObserver响应元素自身尺寸变化。 - 通过批量读取、延后写入和清理避免常见循环问题。
ResizeObserver 观察的是什么
窗口大小不变时,元素仍可能因侧栏展开、父容器布局、字体加载或内容变化而改变尺寸。ResizeObserver 在布局结果可用后批量提供尺寸记录,比只监听 window.resize 更适合封装独立组件。
观察记录由 ResizeObserverEntry 提供。常用数据包括 contentBoxSize、borderBoxSize 和兼容性回退字段 contentRect;前两者还使用 inlineSize、blockSize 描述当前书写模式下的行内轴与块轴尺寸。

选择内容盒或边框盒
observer.observe(element) 默认观察内容盒;显式传入 { box: "border-box" } 时,尺寸包含内容区、内边距和边框。组件断点若以页面实际占位宽度为准,通常选择边框盒;若只关心可排版内容区域,则选择内容盒。
读取 borderBoxSize 时应考虑其在现代浏览器中通常是数组,因为分栏等场景可能产生多个片段。简单元素可读取第一项,并为旧实现保留 getBoundingClientRect() 或 contentRect 回退。
完整示例:根据面板宽度切换布局
以下页面提供可横向拖拽的面板。观察器只读取面板尺寸,实际样式修改安排到下一帧,并作用于内部内容区域,避免直接反复改变被观察面板的宽度。
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>ResizeObserver 示例</title>
<style>
body {
font-family: sans-serif;
padding: 32px;
background: #f5f7fa;
}
#panel {
width: 520px;
min-width: 280px;
max-width: 90vw;
height: 220px;
padding: 20px;
border: 3px solid #1e3a8a;
border-radius: 14px;
box-sizing: border-box;
resize: horizontal;
overflow: auto;
background: white;
}
#content {
display: grid;
grid-template-columns: 1fr 1fr;
gap: 12px;
}
#content.compact {
grid-template-columns: 1fr;
}
.item {
padding: 16px;
border-radius: 10px;
background: #e2e8f0;
}
#status {
margin-top: 14px;
font-family: monospace;
}
</style>
</head>
<body>
<p>拖动面板右下角,观察 420px 断点。</p>
<section id="panel">
<div id="content">
<div class="item">主内容</div>
<div class="item">辅助内容</div>
</div>
<div id="status">等待首次尺寸通知</div>
</section>
<script>
const panel = document.querySelector("#panel");
const content = document.querySelector("#content");
const status = document.querySelector("#status");
let latestWidth = 0;
let frameId = 0;
function render() {
frameId = 0;
const compact = latestWidth < 420;
content.classList.toggle("compact", compact);
status.textContent =
`border-box: ${Math.round(latestWidth)}px; ` +
`mode: ${compact ? "compact" : "wide"}`;
}
const observer = new ResizeObserver(([entry]) => {
const borderSize = Array.isArray(entry.borderBoxSize)
? entry.borderBoxSize[0]
: entry.borderBoxSize;
// 回调阶段只读取尺寸,多次通知合并到下一帧写入。
latestWidth = borderSize?.inlineSize ??
entry.target.getBoundingClientRect().width;
if (frameId === 0) {
frameId = requestAnimationFrame(render);
}
});
observer.observe(panel, { box: "border-box" });
window.addEventListener("pagehide", () => {
cancelAnimationFrame(frameId);
observer.disconnect();
}, { once: true });
</script>
</body>
</html>预期结果
拖动面板宽度时,状态文本持续显示当前边框盒宽度。小于 420 像素时两个内容块改为单列,否则恢复双列;实际宽度会随拖动位置变化。
border-box: <WIDTH>px; mode: compact
或
border-box: <WIDTH>px; mode: wide避免观察回调循环
若回调读取宽度后立即修改同一被观察元素的宽度、内边距或边框,修改会触发新布局,新布局又产生新的尺寸记录。条件在两个尺寸之间来回切换时,浏览器可能报告 ResizeObserver 循环通知未完全交付。
安全做法是先读取并保存尺寸,再通过 requestAnimationFrame() 合并写入;优先修改子元素布局、CSS 自定义属性或不影响被观察盒子尺寸的状态。即使延后写入,也应保证规则能够收敛,不能每一帧继续扩大或缩小目标。
清理与边界
停止观察单个元素使用 observer.unobserve(element),销毁组件时使用 observer.disconnect()。一个观察器可以同时监听多个元素,回调应遍历全部 entries,并按 entry.target 区分目标。
元素被设为 display: none 时,其尺寸可能变为零;重新显示后会再次产生记录。ResizeObserver 只报告尺寸,不判断目标是否位于视口内,可见性检测仍应交给 IntersectionObserver。