JavaScript ResizeObserver 怎样读取 contentBoxSize 尺寸

在做一个会随容器宽度切换布局的卡片组件时，我第一次看到 entry.contentBoxSize，下意识把它当成了“一个可以直接读取 width 的对象”。结果回调确实触发了，尺寸却没有按预期进入布局判断。正确的读取路径是：先从 ResizeObserver 回调的 ResizeObserverEntry 取出 contentBoxSize，再读取它的第一项中的 inlineSize 和 blockSize。

官方资料：https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver

现代实现通常把 contentBoxSize 暴露为数组，常规水平书写模式下用 contentBoxSize[0].inlineSize 读取内容宽度、用 contentBoxSize[0].blockSize 读取内容高度。为了照顾旧实现，还应保留“单对象”和 contentRect 的回退分支。

先分清 contentBoxSize 代表哪一层尺寸

ResizeObserver 观察的是元素尺寸变化。回调中的每一项是一个 ResizeObserverEntry，它同时提供 target、contentBoxSize、borderBoxSize 和旧式的 contentRect 等信息。题目中的 contentBoxSize 只描述内容盒，不包含 padding 和 border。

这一区别很重要：如果卡片的 CSS 是 box-sizing: content-box，内容宽度加上左右内边距和边框后，才是外层边框盒的宽度；如果布局判断需要的是“文本或子元素可用空间”，内容盒才是更合适的输入。不要拿 contentBoxSize 的结果去和 offsetWidth 无条件比较，它们属于不同的盒层。

还有一个容易被忽略的点：inlineSize 和 blockSize 是逻辑轴名称，不是固定的横向宽度和纵向高度。在常见的水平书写模式下，inline 方向通常对应宽度，block 方向通常对应高度；如果页面使用了垂直书写模式，二者的物理方向会随 writing-mode 改变。

在回调中读取 inlineSize 和 blockSize

最小写法可以先假定当前浏览器按标准返回数组，然后读取第一项。下面的示例只把尺寸显示到旁边的状态元素，不改变被观察元素本身，因此不会因为回调内反复改尺寸而形成观察循环。

const card = document.querySelector(".card");
const sizeText = document.querySelector(".size-text");

const observer = new ResizeObserver((entries) => {
  for (const entry of entries) {
    // 标准实现返回数组；当前普通元素通常读取第一项。
    const size = entry.contentBoxSize[0];
    if (!size) {
      continue;
    }

    // inlineSize/blockSize 是逻辑轴尺寸，不要硬编码成 width/height。
    sizeText.textContent = `内容盒：${size.inlineSize}px × ${size.blockSize}px`;
  }
});

// 只观察目标元素，页面销毁或组件卸载时要停止观察。
observer.observe(card);

// 组件卸载时执行：observer.disconnect();

这里的 entries 是数组，所以实际代码应遍历它，而不是假设回调永远只有一个目标。contentBoxSize 的第一项是一个 ResizeObserverSize，它提供 inlineSize 与 blockSize 两个只读尺寸字段。对于普通单列元素，第一项就是最常用的读取位置；多列等碎片化布局则要意识到返回值有“多个片段”的语义，不能把数组长度当作浏览器版本标志。

如果只面向当前主流浏览器，下面这一句通常就够用：

const size = entry.contentBoxSize[0];
// 逻辑宽度和逻辑高度分别从两个字段读取。
const inline = size.inlineSize;
const block = size.blockSize;

给 contentBoxSize 做兼容分支

真正容易出错的是直接写 entry.contentBoxSize[0].inlineSize，却没有考虑历史实现。有些旧版本把 contentBoxSize 当成单个对象，有些环境只有兼容用的 contentRect。可以把兼容逻辑集中在一个小函数里，业务代码只消费统一的 inlineSize 和 blockSize。

function readContentBox(entry) {
  const raw = entry.contentBoxSize;

  // 标准形状是数组；旧实现可能直接给一个尺寸对象。
  const size = Array.isArray(raw) ? raw[0] : raw;
  if (size) {
    return {
      inlineSize: size.inlineSize,
      blockSize: size.blockSize,
      source: "contentBoxSize",
    };
  }

  // 没有 contentBoxSize 时使用兼容属性，避免直接访问 undefined。
  if (entry.contentRect) {
    return {
      inlineSize: entry.contentRect.width,
      blockSize: entry.contentRect.height,
      source: "contentRect",
    };
  }

  // 没有任何可读尺寸时交给调用方决定是否跳过本次回调。
  return null;
}

const observer = new ResizeObserver((entries) => {
  for (const entry of entries) {
    const size = readContentBox(entry);
    if (!size) {
      continue;
    }

    // 统一出口后，布局逻辑不必知道兼容分支的细节。
    console.log(size.source, size.inlineSize, size.blockSize);
  }
});

这个分支有三个关键点。第一，先判断 raw 是否为数组，再取 raw[0]，可以避免把单对象当成数组下标访问。第二，回退到 contentRect 时，使用的是物理的 width 和 height，它适合兼容普通水平布局，但不能假装它已经保留了逻辑轴语义。第三，函数可以返回 null，让调用方跳过无法读取的条目，而不是在异常路径上继续写入错误样式。

把尺寸变化接到真实布局逻辑

读取尺寸的最终目的通常不是打印数字，而是根据容器自身的可用空间切换布局。下面用 data-density 表示卡片密度：内容盒足够宽时使用舒展布局，否则切换到紧凑布局。示例把“读取”和“应用”分开，便于后续替换样式策略。

const panel = document.querySelector(".panel");

function getContentSize(entry) {
  const raw = entry.contentBoxSize;
  // 兼容标准数组和旧实现单对象两种形状。
  const size = Array.isArray(raw) ? raw[0] : raw;
  if (size) {
    return size;
  }

  // 兼容没有 contentBoxSize 的环境；这里仅用于普通水平布局。
  return entry.contentRect ?? null;
}

const observer = new ResizeObserver(([entry]) => {
  const size = getContentSize(entry);
  if (!size) {
    return;
  }

  // 逻辑尺寸优先，旧回退对象才读取物理 width。
  const inlineSize = size.inlineSize ?? size.width;
  if (inlineSize 

如果在回调里直接修改 panel 的宽度或高度，就要小心触发下一轮尺寸观察。仅切换不会反过来改变容器尺寸的 class 或 data 属性通常更容易控制；如果业务确实要在回调里改尺寸，应设计稳定的目标值或把写操作延后到下一帧，避免让观察器和布局互相推动。

常见疑问

contentBoxSize 为什么不是直接的 width？

因为它表达的是内容盒尺寸，并且使用逻辑轴字段。标准形态还要通过数组项承载尺寸对象，以便表达碎片化布局下的多个片段。

inlineSize 在普通页面里等于什么？

在常见水平书写模式下，它通常对应内容宽度；但它是逻辑轴字段，遇到垂直书写模式时不要把它永远等同于物理横向宽度。

可以一直用 contentRect.width 吗？

它可以作为兼容回退，尤其适合普通水平布局，但它是保留用于向后兼容的旧属性，不如 contentBoxSize 直接表达内容盒的逻辑尺寸。

什么时候调用 unobserve 和 disconnect？

只移除一个目标时调用 unobserve(target)；观察器整体不再使用时调用 disconnect()。在组件卸载阶段清理，可以避免保留无用的观察关系。

小结

记住“先取 entry，再处理 contentBoxSize 的形状，最后读取逻辑轴字段”这条顺序，就能把 ResizeObserver 的尺寸变化稳定接入组件布局。