前端怎样读取布局偏移条目

页面“突然跳一下”时，先不要只盯着最终的 CLS 数字。浏览器已经把每次可见位移记录成 layout-shift 条目，前端可以用 PerformanceObserver 读取它们，再根据 value、hadRecentInput 和 sources 判断是哪一个元素移动了。下面这套写法适合开发调试和采集问题线索。

读取布局偏移条目的核心是观察 layout-shift 类型：用户刚操作后产生的位移通常不计入 CLS，真正需要排查的条目则从 sources 追到发生移动的节点。

先分清 LayoutShift 条目记录了什么

LayoutShift 是 Performance API 中描述布局稳定性的条目类型。它的 entryType 和 name 都是 layout-shift，duration 固定为 0；调试时更有用的是下面四个字段：

• value：本次位移分数，等于影响比例与移动距离比例的乘积。
• hadRecentInput：最近一次排除性用户输入是否发生在 500 毫秒内。
• lastInputTime：最近一次排除性输入的时间戳，没有则为 0。
• sources：被移动元素的归因信息，通常可以读取 node、previousRect 和 currentRect。

因此，条目出现不等于页面一定有“异常 CLS”。例如点击展开内容后，按钮附近的布局变化可能带有最近用户输入；它仍然值得观察，但不能和自动加载广告、图片尺寸变化造成的位移混为一谈。

用 PerformanceObserver 读取 layout-shift

观察器回调拿到的是条目列表。把 buffered: true 放进观察配置，可以让观察器读取创建前已经记录在性能时间线里的条目，适合在业务代码稍晚初始化时补齐线索。

const layoutEntries = [];

// 先确认当前浏览器是否声明支持 layout-shift，避免直接观察后没有反馈。
const supported = PerformanceObserver.supportedEntryTypes || [];
if (supported.includes("layout-shift")) {
  const observer = new PerformanceObserver((list) => {
    for (const entry of list.getEntries()) {
      // 只保存调试需要的字段，避免把整个 DOM 节点直接发送到服务端。
      layoutEntries.push({
        value: entry.value,
        hadRecentInput: entry.hadRecentInput,
        lastInputTime: entry.lastInputTime,
        sources: (entry.sources || []).map(({ node, previousRect, currentRect }) => ({
          // node 可能为空，先取稳定的元素标签作为本地线索。
          element: node ? node.nodeName : "unknown",
          previousRect,
          currentRect,
        })),
      });
    }
  });

  // buffered 让晚初始化的观察器也能拿到已有的 layout-shift 条目。
  observer.observe({ type: "layout-shift", buffered: true });

  // 单页调试结束后可以调用 observer.disconnect() 停止继续接收条目。
}

这里的 supportedEntryTypes 只是能力声明检查，不代表每个浏览器都会完整提供所有归因字段。回调里保留必要字段即可，尤其不要把 node 对象直接序列化上传；如果要上报，应该转换成组件名、元素标签或自定义标识。

用 hadRecentInput 区分 CLS 相关条目

排查自动位移时，第一道筛选通常是 !entry.hadRecentInput。可以同时记录总条目数、被排除的条目数和一个调试累计值：

let debugScore = 0;
let excludedByInput = 0;

// 过滤用户刚刚主动触发的布局变化，保留自动位移的调试分数。
for (const entry of layoutEntries) {
  if (entry.hadRecentInput) {
    excludedByInput += 1;
    continue;
  }
  debugScore += entry.value;
}

// 这个累计值只用于定位问题，不要把它直接当成最终页面 CLS。
console.log({ debugScore, excludedByInput });

需要特别注意：把所有 value 简单相加只是一个排查指标。正式 CLS 还涉及布局偏移会话窗口等统计规则，真实体验数据应交给采用完整指标算法的采集方案计算。本文只解决“怎样拿到条目并找到来源”，不把调试累计值冒充最终评分。

从 sources 找到发生移动的元素

sources 让“页面跳了一下”变成可定位线索。对每个归因对象，比较 previousRect 与 currentRect，可以看出元素移动前后的矩形；再结合元素标签或业务标识，就能回到图片、广告容器、异步列表等具体组件。

实战中建议在本地开发或采样环境保留 previousRect、currentRect 的关键坐标，不要只上报一个分数。若多个节点同时出现，优先看受影响区域最大的节点，再检查它是否在加载前预留了尺寸。

兼容性与清理清单

• 先检查 PerformanceObserver.supportedEntryTypes，不支持时保留静态性能降级，不要让监控脚本阻塞页面。
• 观察器创建较晚时使用 buffered: true；只关心创建后的实时条目时再按需要调整。
• 用户输入导致的位移要单独标记，不能和自动布局变化共用一个告警阈值。
• 上报前把 sources 转成可控字段，避免直接传递 DOM 节点和过大的对象。
• 页面卸载前或单次诊断完成后调用 disconnect()，避免长期监听造成重复采集。

常见问题

为什么观察不到 layout-shift？

可能是浏览器没有提供该条目类型，也可能当前页面没有产生可见布局位移。先检查支持列表，再确认观察器配置和初始化时机。

sources 一定能拿到具体元素吗？

不一定。归因信息受浏览器实现和兼容性影响，代码应允许 sources 为空，并为 node 缺失准备降级标识。

debugScore 能直接当 CLS 吗？

不能。它适合作为本地定位线索；正式 CLS 需要按完整的指标聚合规则计算。