ResizeObserver 监听卡片宽度时如何避免循环触发：borderBoxSize 与帧内合并

响应式卡片一旦从单列切到双列，宽度会在短时间内连续变化。直接在 ResizeObserver 回调里改尺寸相关样式，轻则重复计算，重则在控制台看到 “ResizeObserver loop completed with undelivered notifications”。比较稳妥的做法是：用 borderBoxSize 读取当前边框盒宽度，把最新值放进 pendingWidth，再交给 requestAnimationFrame 在一帧内合并更新。

ResizeObserver 负责报告尺寸，requestAnimationFrame 负责安排渲染；不要在观察回调里同步制造下一次布局变化。

卡片宽度变化时，真正要交给组件的是什么

这个场景常见于仪表盘、商品卡片和可拖拽面板：卡片宽度改变后，需要切换紧凑版标题、调整操作按钮间距，或者设置一个与卡片宽度有关的圆角。这里的输入不是浏览器窗口宽度，而是组件自身的边框盒宽度。

MDN 对 borderBoxSize 的说明是一个尺寸序列，每个尺寸对象包含 inlineSize 和 blockSize。在常见的横向书写模式中，inlineSize 就是水平尺寸。代码节点 ResizeObserver、borderBoxSize 和 pendingWidth 会贯穿下面的读取链路。

先读 borderBoxSize，再把写操作移出观察回调

下面的 observeCard 只负责读取和排队。为了兼容某些旧实现，示例保留 contentRect.width 作为回退值；现代浏览器优先使用 borderBoxSize[0].inlineSize。

let pendingWidth = null;
let frameId = 0;

const renderCard = (width) => {
  card.style.setProperty('--card-width', `${width}px`);
  card.classList.toggle('is-compact', width  {
  const entry = entries[0];
  const box = entry.borderBoxSize?.[0];
  pendingWidth = box ? box.inlineSize : entry.contentRect.width;

  if (frameId === 0) {
    frameId = requestAnimationFrame(() => {
      const width = pendingWidth;
      pendingWidth = null;
      frameId = 0;
      if (width !== null) renderCard(width);
    });
  }
});

observeCard.observe(card, { box: 'border-box' });

关键点只有两个：回调内先把最新尺寸写入 pendingWidth，再用 frameId 确保同一帧只登记一次更新。真正写 CSS 变量和切换 is-compact 的动作发生在 requestAnimationFrame 回调里。

为什么帧内合并能减少循环触发

如果回调每进来一次就同步执行 renderCard，而 renderCard 又改变了会影响盒尺寸的样式，浏览器可能在同一个渲染周期里再次产生尺寸通知。W3C 规范明确描述了未能在当前周期交付的通知会触发循环错误事件；这不是“ResizeObserver 不能用”，而是读写布局的边界没有拉开。

帧内合并并不等于忽略变化。假设一帧内先收到 420，再收到 380，pendingWidth 最后只留下 380，渲染阶段直接使用最新值。下一帧若还有真实尺寸变化，观察器仍会继续通知。

可访问性和边界状态不能靠默认值带过

宽度切换通常会影响按钮排列和标题换行。切换 is-compact 时，不要通过脚本修改焦点顺序，也不要把操作按钮从 DOM 中删除；让 CSS 负责布局，键盘用户和屏幕阅读器仍沿用稳定的 DOM 顺序。

初始化时 pendingWidth 可能还是 null，因此渲染分支必须先判断。元素被移除后也应调用 observeCard.unobserve(card)，组件销毁时再取消尚未执行的 frameId，避免回调触碰已失效节点。

性能检查：看合并是否真的发生

在 DevTools 的 Performance 面板录制一次拖动容器宽度的过程，重点看 ResizeObserver 回调和 requestAnimationFrame 的数量关系。正常情况下，一帧可能收到多次观察通知，但只应该有一次 renderCard 写入；如果两者数量几乎相同，说明合并条件没有生效。

• 观察回调只读 borderBoxSize，不在其中读取会触发布局的复杂计算。
• frameId === 0 是去重开关，执行帧回调后要恢复为 0。
• 用 360 这类组件真实断点做检查，不要拿没有业务意义的随机阈值压测。

常见问题

borderBoxSize 为什么是数组

规范把它定义为尺寸序列，用于支持多片段布局；普通卡片通常读取第一个尺寸对象即可。

可以直接用 contentRect.width 吗

可以作为兼容回退，但它描述的是内容矩形；如果组件的判断包含 padding 或 border，优先使用 borderBoxSize。

requestAnimationFrame 会不会丢掉最后一次变化

示例只覆盖同一帧内的重复通知，保留最后一个 pendingWidth。下一帧发生的新尺寸变化仍会触发 ResizeObserver。

把读写边界固定下来

ResizeObserver 适合告诉组件“尺寸变了”，不适合承担一整套同步布局写操作。把 borderBoxSize 的读取、pendingWidth 的合并和 renderCard 的写入拆开，组件更容易测，也更容易在控制台和 Performance 面板里解释每一次更新。