PerformanceEventTiming

描述

此 API 通过提供特定事件类型的事件时间戳和持续时间（见下文），从而实现了对慢速事件的可视性。例如，您可以监控用户操作与其事件处理程序开始之间的时间，或者事件处理程序运行所需的时间。

此 API 对于测量用户交互到下次绘制（INP）特别有用：这是从用户与您的应用交互的那一刻到浏览器实际能够响应该交互的那一刻之间（排除某些异常值）的最长时间。

您通常通过创建 PerformanceObserver 实例，然后调用其 observe() 方法，并将 "event" 或 "first-input" 作为 type 选项的值来处理 PerformanceEventTiming 对象。然后，PerformanceObserver 对象的回调将以 PerformanceEventTiming 对象列表的形式被调用，您可以进行分析。有关更多信息，请参阅下面的示例。

默认情况下，当 PerformanceEventTiming 条目的 duration 为 104ms 或更高时，它们会被公开。研究表明，未在 100ms 内处理的用户输入被认为是慢速的，而 104ms 是大于 100ms 的第一个 8 的倍数（出于安全原因，此 API 会四舍五入到最接近的 8ms 倍数）。但是，您可以使用 observe() 方法中的 durationThreshold 选项将 PerformanceObserver 设置为不同的阈值。

此接口继承了其父级 PerformanceEntry 的方法和属性。

公开的事件

Event Timing API 公开以下事件类型：

请注意，以下事件未包含在此列表中，因为它们是连续事件，在此阶段无法获得有意义的事件计数或性能指标：mousemove、pointermove、pointerrawupdate、touchmove、wheel、drag。

要获取所有公开事件的列表，您还可以查找 performance.eventCounts 映射中的键。

const exposedEventsList = [...performance.eventCounts.keys()];

构造函数

此接口本身没有构造函数。有关通常如何获取 PerformanceEventTiming 接口所包含的信息，请参阅下面的示例。

实例属性

此接口通过以下方式扩展了其父级 PerformanceEntry 的属性，以用于事件计时性能条目类型：

PerformanceEntry.duration 只读

返回一个 DOMHighResTimeStamp，表示从 startTime 到下一次渲染绘制的时间（四舍五入到最接近的 8ms）。

PerformanceEntry.entryType 只读

返回 "event"（对于长事件）或 "first-input"（对于首次用户交互）。

PerformanceEntry.name 只读

返回与事件关联的事件类型。

PerformanceEntry.startTime 只读

返回一个 DOMHighResTimeStamp，表示与事件关联的 timestamp 属性。这是事件创建的时间，可以被视为用户交互发生时间的代理。

此接口还支持以下属性：

PerformanceEventTiming.cancelable 只读

返回与事件关联的 cancelable 属性。

PerformanceEventTiming.interactionId 只读

返回唯一标识触发关联事件的用户交互的 ID。

PerformanceEventTiming.processingStart 只读

返回一个 DOMHighResTimeStamp，表示事件分派开始的时间。要测量用户操作到事件处理程序开始运行之间的时间，请计算 processingStart - startTime。

PerformanceEventTiming.processingEnd 只读

返回一个 DOMHighResTimeStamp，表示事件分派结束的时间。要测量事件处理程序运行所需的时间，请计算 processingEnd - processingStart。

PerformanceEventTiming.target 只读

返回与事件关联的最后一个目标，如果它未被移除。

实例方法

PerformanceEventTiming.toJSON()

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

示例

获取事件计时信息

要获取事件计时信息，请创建一个 PerformanceObserver 实例，然后调用其 observe() 方法，并将 "event" 或 "first-input" 作为 type 选项的值。您还需要将 buffered 设置为 true，以访问用户代理在构建文档时缓冲的事件。然后，PerformanceObserver 对象的回调将以 PerformanceEventTiming 对象列表的形式被调用，您可以进行分析。

const observer = new PerformanceObserver((list) => {
  list.getEntries().forEach((entry) => {
    // Full duration
    const duration = entry.duration;

    // Input delay (before processing event)
    const delay = entry.processingStart - entry.startTime;

    // Synchronous event processing time
    // (between start and end dispatch)
    const eventHandlerTime = entry.processingEnd - entry.processingStart;
    console.log(`Total duration: ${duration}`);
    console.log(`Event delay: ${delay}`);
    console.log(`Event handler duration: ${eventHandlerTime}`);
  });
});

// Register the observer for events
observer.observe({ type: "event", buffered: true });

您还可以设置不同的 durationThreshold。默认值为 104ms，可能的最小持续时间阈值为 16ms。

observer.observe({ type: "event", durationThreshold: 16, buffered: true });

规范

浏览器兼容性

另见

• Intersection Observer API
• Page Visibility API