LayoutShift

描述

当任何在视口中可见的元素在两个帧之间改变其位置时，就会发生布局偏移。这些元素被称为不稳定，表明缺乏视觉稳定性。

布局不稳定 API 提供了一种衡量和报告这些布局偏移的方法。所有用于调试布局偏移的工具，包括浏览器开发者工具中的那些，都使用此 API。该 API 还可用于通过将信息记录到控制台、将数据发送到服务器端点或发送到网页分析来观察和调试布局偏移。

性能工具可以使用此 API 来计算 CLS 分数。

实例属性

此接口通过以下方式扩展了以下 PerformanceEntry 属性：

PerformanceEntry.duration 只读 实验性

始终返回 0（持续时间的概念不适用于布局偏移）。

PerformanceEntry.entryType 只读 实验性

始终返回 "layout-shift"。

PerformanceEntry.name 只读 实验性

始终返回 "layout-shift"。

PerformanceEntry.startTime 只读 实验性

返回一个 DOMHighResTimeStamp，表示布局偏移开始的时间。

此接口还支持以下属性：

LayoutShift.value 实验性

返回布局偏移分数，计算方法是将影响分数（视口移动部分的比例）乘以距离分数（视口移动的距离比例）。

LayoutShift.hadRecentInput 实验性

如果 lastInputTime 距离现在小于 500 毫秒，则返回 true。

LayoutShift.lastInputTime 实验性

返回最近一次排除性输入（将排除此条目作为 CLS 分数贡献的用户输入）的时间，如果没有发生排除性输入，则返回 0。

LayoutShift.sources 实验性

返回一个 LayoutShiftAttribution 对象数组，其中包含有关已移动元素的详细信息。

实例方法

LayoutShift.toJSON() 实验性

将属性转换为 JSON。

示例

记录布局偏移值

以下示例展示了如何捕获布局偏移并将其记录到控制台。

const observer = new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    // Count layout shifts without recent user input only
    if (!entry.hadRecentInput) {
      console.log("LayoutShift value:", entry.value);
      if (entry.sources) {
        for (const { node, currentRect, previousRect } of entry.sources)
          console.log("LayoutShift source:", node, {
            currentRect,
            previousRect,
          });
      }
    }
  }
});

observer.observe({ type: "layout-shift", buffered: true });

规范

浏览器兼容性

另见

• LayoutShiftAttribution
• CLS