Document: visibilitychange イベント

visibilitychange イベントは、タブのコンテンツが表示状態または非表示状態になったときに document に発生します。

このイベントはキャンセル不可です。

構文

このイベント名を addEventListener() などのメソッドで使用するか、イベントハンドラープロパティを設定するかしてください。

js
addEventListener("visibilitychange", (event) => {});

onvisibilitychange = (event) => {};

イベント型

一般的な Event です。

使用上の注意

このイベントには、更新された文書の表示・非表示状態が含まれていませんが、この情報は document の visibilityState プロパティから取得することができます。

このイベントは、ユーザーが新しいページに移動したり、タブを切り替えたり、タブを閉じたり、ブラウザーを最小化したり閉じたりしたとき、あるいはモバイルではブラウザーから異なる形のアプリに切り替えたときに visibilityState が hidden になった状態で発行されます。 hidden への遷移はページが確実に監視できる最後のイベントなので、開発者はそれをユーザーのセッションの終わりとして扱うべきです（例えば解析データの送信の場合）。

また、 hidden への遷移は、ページが UI の更新を停止し、ユーザーがバックグラウンドで実行させたくないタスクを停止するための良いタイミングでもあります。

例

非表示に遷移した際に音楽を一時停止

この例は、ページが非表示になると音声再生を一時停止し、ページが再び表示されると再生を再開します。 完全な例については、Page Visibility API: Pausing audio on page hide ドキュメントを参照してください。

js
document.addEventListener("visibilitychange", () => {
  if (document.hidden) {
    playingOnHide = !audio.paused;
    audio.pause();
  } else {
    // 音声が "playing on hide" であった場合は復旧する
    if (playingOnHide) {
      audio.play();
    }
  }
});

非表示に遷移した際に解析のセッション終了を送信

この例では、 hidden への遷移をユーザーセッションの終わりとして扱い、 Navigator.sendBeacon() API を使って適切な解析を送信しています。

js
document.onvisibilitychange = () => {
  if (document.visibilityState === "hidden") {
    navigator.sendBeacon("/log", analyticsData);
  }
};

仕様書

Specification
HTML Standard
# event-visibilitychange
HTML Standard
# handler-onvisibilitychange

ブラウザーの互換性

BCD tables only load in the browser

関連情報