PerformanceEventTiming

解説

この API により、特定のイベント型（下記参照）のイベントのタイムスタンプと処理時間が提供されるので、遅いイベントを可視化することができるようになります。例えば、ユーザー操作からそのイベントハンドラーが始まるまでの時間や、イベントハンドラーが実行するまでにかかる時間を監視することができます。

この API は、Interaction to Next Paint (INP) （ユーザーがアプリを操作した時点から、ブラウザーが応答できるようになるまでの最長時間で、外れ値を除く）を測定するのに特に有益です。

通常、 PerformanceEventTiming オブジェクトを扱うには、 PerformanceObserver インスタンスを作成し、 observe() メソッドを呼び出して、 type オプションに "event" または "first-input" を渡します。 PerformanceObserver オブジェクトのコールバックは、 PerformanceEventTiming オブジェクトのリストとともに呼び出されます。例えば下記の例をご覧ください。

既定では、PerformanceEventTiming 項目は duration が 104ms 以上の場合に公開されます。調査によると、 100ms 以内に処理されないユーザー入力は遅いと考えられており、 104ms は 100ms より大きい最初の 8 の倍数です（セキュリティ上の理由から、この API は最も近い 8 の倍数に丸められます）。 しかし、observe() メソッドの durationThreshold オプションを使用して、PerformanceObserver を別の閾値に設定することができます。

このインターフェイスは、親である PerformanceEntry のメソッドとプロパティを継承しています。

公開されるイベント

イベントタイミング 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() メソッドを呼び出して、 type オプションの値として "event" または "first-input" を渡してください。また、ユーザーエージェントが文書の構築中にバッファリングしたイベントにアクセスするには、 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(`Total duration: ${duration}`);
    console.log(`Event delay: ${delay}`);
    console.log(`Event handler duration: ${eventHandlerTime}`);
  });
});

// イベントのオブザーバーを登録
observer.observe({ type: "event", buffered: true });

異なる durationThreshold を設定することもできます。既定では 104ms で、最小可能な閾値は 16ms です。

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

仕様書

ブラウザーの互換性

関連情報

• Intersection_Observer_API
• Page_Visibility_API