大网数据广告活动
Web 标准与前端开发

PerformanceEventTiming

· 52CE 我爱测

事件计时 API 的 `PerformanceEventTiming` 接口用来观察用户交互触发的某些事件的延迟情况。

Performance API

事件计时 API 的 PerformanceEventTiming 接口用来观察用户交互触发的某些事件的延迟情况。

描述

此 API 通过提供某些事件类型(见下文)的时间戳和持续时间,实现对慢事件的可见性。例如,你可以监控用户操作与事件处理程序开始执行之间的时间,或事件处理程序自身的执行时间。

此 API 对于测量Interaction to Next Paint特别有用:从用户与应用交互到浏览器实际响应该交互的最长时间(去除一些异常值)。

通常通过创建 PerformanceObserver 实例来使用 PerformanceEventTiming 对象,然后调用其 observe() 方法,传入 "event" 或 "first-input" 作为 type 选项的值。然后,PerformanceObserver 对象的回调将接收到一个 PerformanceEventTiming 对象列表,你可以对其进行分析。请参阅下面的示例以了解更多信息。

默认情况下,当 PerformanceEventTiming 条目的持续时间达到 104 毫秒或以上时,该条目会被暴露。研究表明,如果用户输入在 100 毫秒内未得到处理,则被认为是缓慢的,而 104 毫秒是大于 100 毫秒的第一个 8 的倍数(出于安全原因,此 API 四舍五入为最接近的 8 毫秒的倍数)。但是,你可以使用 observe() 方法中的 durationThreshold 选项将 PerformanceObserver 设置为不同的阈值。

此接口从其父级 PerformanceEntry 继承方法和属性:

暴露的事件

事件计时 API 暴露以下事件类型:

<table> <tbody> <tr> <th scope="row">点击事件</th> <td> Element/auxclick_event、Element/click_event、Element/contextmenu_event、Element/dblclick_event </td> </tr> <tr> <th scope="row">合成事件</th> <td> Element/compositionend_event、Element/compositionstart_event、Element/compositionupdate_event </td> </tr> <tr> <th scope="row">拖放事件</th> <td> HTMLElement/dragend_event、HTMLElement/dragenter_event、HTMLElement/dragleave_event、HTMLElement/dragover_event、HTMLElement/dragstart_event、HTMLElement/drop_event </td> </tr> <tr> <th scope="row">输入事件</th> <td> Element/beforeinput_event、Element/input_event </td> </tr> <tr> <th scope="row">键盘事件</th> <td> Element/keydown_event、Element/keypress_event、Element/keyup_event </td> </tr> <tr> <th scope="row">鼠标事件</th> <td> Element/mousedown_event、Element/mouseenter_event、Element/mouseleave_event、Element/mouseout_event、Element/mouseover_event、Element/mouseup_event </td> </tr> <tr> <th scope="row">指针事件</th> <td> Element/pointerover_event、Element/pointerenter_event、Element/pointerdown_event、Element/pointerup_event、Element/pointercancel_event、Element/pointerout_event、Element/pointerleave_event、Element/gotpointercapture_event、Element/lostpointercapture_event </td> </tr> <tr> <th scope="row">触摸事件</th> <td> Element/touchstart_event、Element/touchend_event、Element/touchcancel_event </td> </tr> </tbody> </table>

请注意,以下事件未包含在列表中,因为这些事件属于连续事件,无法在此阶段获得有意义的事件计数或性能指标:Element/mousemove_event、Element/pointermove_event、Element/pointerrawupdate_event、Element/touchmove_event、Element/wheel_event、HTMLElement/drag_event。

要获取所有暴露的事件的列表,你还可以在 performance.eventCounts 映射中查找键:

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

构造函数

该接口没有自己的构造函数。请参阅下方示例,了解如何获取 PerformanceEventTiming 对象所包含的信息。

实例属性

此接口通过以下限定方式扩展了事件计时性能条目类型的以下 PerformanceEntry 属性:

  • PerformanceEntry.duration
    • : 返回一个 DOMHighResTimeStamp,表示从 startTime 到下一次渲染绘制的时间(四舍五入到最接近的 8 毫秒)。
  • PerformanceEntry.entryType
    • : 返回 "event"(对于长事件)或 "first-input"(对于第一次用户交互)。
  • PerformanceEntry.name
    • : 返回关联事件的类型。
  • PerformanceEntry.startTime
    • : 返回一个 DOMHighResTimeStamp,表示关联事件的 timestamp 属性。这是事件创建的时间,可以被视为用户交互发生时间的代理。

该接口还支持以下属性:

  • PerformanceEventTiming.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) => {
    // 全程
    const duration = entry.duration;

    // 输入延迟(在处理事件之前)
    const delay = entry.processingStart - entry.startTime;

    // 同步事件处理时间
    // (开始和结束调度之间)
    const eventHandlerTime = entry.processingEnd - entry.processingStart;
    console.log(`总时长:${duration}`);
    console.log(`事件延迟:${delay}`);
    console.log(`事件处理程序执行时间:${eventHandlerTime}`);
  });
});

// 注册事件观察器
observer.observe({ type: "event", buffered: true });

你还可以设置不同的 durationThreshold。默认值为 104 毫秒,最小可能的持续时间阈值为 16 毫秒。

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

规范

浏览器兼容性

参见

来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。

资料来源与适用范围

资料来源
MDN Web Docs / Mozilla 贡献者
适用范围
请按文中版本与环境说明核对
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY-SA 2.5

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。