当前位置：首页 > 文章列表 > 文章 > 前端 > 前端怎样读取布局偏移条目

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

来源：17golang原创 2026-10-18 15:22:50 0浏览收藏

页面“突然跳一下”时，先不要只盯着最终的 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”。例如点击展开内容后，按钮附近的布局变化可能带有最近用户输入；它仍然值得观察，但不能和自动加载广告、图片尺寸变化造成的位移混为一谈。

LayoutShift 条目字段与布局偏移归因关系说明图 — 图1：条目字段说明图，查看 value、hadRecentInput、sources 与发生位移元素之间的静态关系。

用 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 还涉及布局偏移会话窗口等统计规则，真实体验数据应交给采用完整指标算法的采集方案计算。本文只解决“怎样拿到条目并找到来源”，不把调试累计值冒充最终评分。