Document: visibilitychange イベント

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

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

構文

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

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

onvisibilitychange = (event) => {};

イベント型

一般的な Event です。

使用上の注意

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

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

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

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

この例では、文書が表示状態になった時に音楽を再生し、文書が非表示になった時に音楽を停止します。

js
document.addEventListener("visibilitychange", () => {
  if (document.visibilityState === "visible") {
    backgroundMusic.play();
  } else {
    backgroundMusic.pause();
  }
});

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

この例では、 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

関連情報