最大内容绘制

LargestContentfulPaint 接口提供有关网页上用户输入之前最大的图像或文本绘制的计时信息。

描述

此 API 提供的关键时刻是 最大内容绘制 (LCP) 指标。它提供了在视窗内可见的最大图像或文本块的渲染时间,记录自页面首次开始加载时。在确定 LCP 时,会考虑以下元素

要测量其他元素的渲染时间,请使用 PerformanceElementTiming API。

其他关键绘制时刻由 PerformancePaintTiming API 提供

  • 首次绘制 (FP):渲染任何内容的时间。请注意,首次绘制的标记是可选的,并非所有用户代理都会报告它。
  • 首次内容绘制 (FCP):首次渲染 DOM 文本或图像内容的时间。

LargestContentfulPaint 继承自 PerformanceEntry

PerformanceEntry LargestContentfulPaint

实例属性

此接口通过如下限定和约束属性,扩展了以下 PerformanceEntry 属性

PerformanceEntry.entryType 只读 实验性

返回 "largest-contentful-paint"。

PerformanceEntry.name 只读 实验性

始终返回空字符串。

PerformanceEntry.startTime 只读 实验性

如果此条目的 renderTime 不为 0,则返回此条目的 renderTime 的值,否则返回此条目的 loadTime 的值。

PerformanceEntry.duration 只读 实验性

返回 0,因为 duration 不适用于此接口。

它还支持以下属性

LargestContentfulPaint.element 只读

当前最大内容绘制的元素。

LargestContentfulPaint.renderTime 只读

元素渲染到屏幕上的时间。如果元素是跨域图像,并且没有 Timing-Allow-Origin 标头,则可能无法使用。

LargestContentfulPaint.loadTime 只读

元素加载的时间。

LargestContentfulPaint.size 只读

元素的固有大小,以面积(宽度 * 高度)返回。

LargestContentfulPaint.id 只读

元素的 id。当没有 id 时,此属性返回空字符串。

LargestContentfulPaint.url 只读

如果元素是图像,则为图像的请求网址。

实例方法

此接口还继承了 PerformanceEntry 的方法。

LargestContentfulPaint.toJSON()

返回 LargestContentfulPaint 对象的 JSON 表示形式。

示例

观察最大内容绘制

在以下示例中,注册了一个观察者,以便在页面加载时获取最大内容绘制。buffered 标志用于访问观察者创建之前的的数据。

LCP API 会分析它找到的所有内容(包括从 DOM 中删除的内容)。当找到新的最大内容时,它会创建一个新的条目。当滚动或输入事件发生时,它会停止搜索更大的内容,因为这些事件可能会在网站上引入新的内容。因此,LCP 是观察者报告的最后一个性能条目。

js
const observer = new PerformanceObserver((list) => {
  const entries = list.getEntries();
  const lastEntry = entries[entries.length - 1]; // Use the latest LCP candidate
  console.log("LCP:", lastEntry.startTime);
  console.log(lastEntry);
});
observer.observe({ type: "largest-contentful-paint", buffered: true });

跨域图像渲染时间

出于安全原因,如果资源是跨域请求,则 renderTime 属性的值为 0。相反,会公开 loadTime。要公开跨域渲染时间信息,需要设置 Timing-Allow-Origin HTTP 响应标头。

例如,要允许 https://mdn.org.cn 查看 renderTime,跨域资源应该发送

http
Timing-Allow-Origin: https://mdn.org.cn

与代码示例中一样,您可以使用 startTime,它在 renderTime 不为 0 时返回条目的 renderTime 的值,否则返回此条目的 loadTime 的值。但是,建议设置 Timing-Allow-Origin 标头,这样指标会更准确。

如果您使用 startTime,可以通过检查是否使用了 renderTime 来标记任何不准确之处

js
const isAccurateLCP = entry.renderTime ? true : false;

规范

规范
最大内容绘制
# sec-largest-contentful-paint-interface

浏览器兼容性

BCD 表格仅在浏览器中加载

另请参见