MDN wants to learn about developers like you: https://qsurvey.mozilla.com/s3/MDN-dev-survey

Page Visibility API は、ウェブページが見えている状態あるいはフォーカスがある状態であるかを知らせてくれます。タブブラウジングではどのウェブページも、バックグラウンドにあってユーザーから見えていない可能性があります。ユーザーがウェブページを最小化したり別のタブに移動したりすると、API はページの可視性に関して visibilitychange イベントを送信します。イベントを検出して何らかのアクションを起こしたり、さまざまな動作を行うことができます。例えばウェブアプリで動画を再生している場合に、ユーザーが別のブラウザを見たときに再生を一時停止して、その後ユーザーが元のタブに戻ったときに再生を再開できます。ユーザーは動画の出演者を見失うことなく、視聴を続けることができます。

<iframe> の可視性状態は、親ドキュメントと同じになります。CSS プロパティにより iframe を隠しても Page Visibility のイベントは発生せず、また内容物のドキュメントの状態も変わりません。

利点

この API は、ウェブページが見えていないときに不要なタスクを実行しないようにする機会を開発者に与えますので、リソースの節約に特に役立ちます。

使用例

以下に例を示します:

  • 画像を順次表示しているサイトで、ユーザーがページを見ているのでなければ次のスライドへ進むべきではないもの。
  • 情報をダッシュボードに表示するアプリケーションで、ページが見えていないときは更新情報をサーバーへ問い合わせてほしくないもの。
  • 正確なページビューをカウントできるよう、ページがプリレンダリングされている状態を検出したい。
  • デバイスがスタンバイモードである (ユーザーが電源ボタンを押して、画面を消灯している) ときに、音声を止めたいサイト。

以前、開発者はこれを検出するために不完全な代替手段を使用していました。例えば window で onblur/onfocus ハンドラーを登録することでページがアクティブではないときを知る助けになりますが、ページがユーザーから隠された状態であることは知らせてくれません。Page Visibility API はこれを解決します。(window での onblur/onfocus ハンドラー登録と比較したときの重要な相違点は、別のウィンドウがアクティブになってブラウザーウィンドウからフォーカスが外れたときに、ページが隠された状態にはなりません。ユーザーが別のタブに切り替えたりブラウザーウィンドウを最小化したりしたときにのみ、ページは隠されます。)

Live example をご覧ください (音声つき動画あり)。

この例では別のタブに切り替えたときに動画再生を一時停止、また元のタブに戻った時に再生を再開しており、以下のコードで作られました:

// hidden プロパティおよび可視性の変更イベントの名前を設定
var hidden, visibilityChange; 
if (typeof document.hidden !== "undefined") { // Opera 12.10 や Firefox 18 以降でサポート 
  hidden = "hidden";
  visibilityChange = "visibilitychange";
} else if (typeof document.msHidden !== "undefined") {
  hidden = "msHidden";
  visibilityChange = "msvisibilitychange";
} else if (typeof document.webkitHidden !== "undefined") {
  hidden = "webkitHidden";
  visibilityChange = "webkitvisibilitychange";
}
 
var videoElement = document.getElementById("videoElement");

// ページが隠れたとき、動画再生を一時停止する。
// ページが表示されたとき、動画を再生する。
function handleVisibilityChange() {
  if (document[hidden]) {
    videoElement.pause();
  } else {
    videoElement.play();
  }
}

// ブラウザーが addEventListener または Page Visibility API をサポートしない場合に警告
if (typeof document.addEventListener === "undefined" || typeof document[hidden] === "undefined") {
  console.log("This demo requires a browser, such as Google Chrome or Firefox, that supports the Page Visibility API.");
} else {
  // Page Visibility の変更を扱う   
  document.addEventListener(visibilityChange, handleVisibilityChange, false);
    
  // 動画が一時停止されたときに、タイトルを設定する。
  // 一時停止したことを示す。
  videoElement.addEventListener("pause", function(){
    document.title = 'Paused';
  }, false);
    
  // 動画を再生するときに、タイトルを設定する。
  videoElement.addEventListener("play", function(){
    document.title = 'Playing'; 
  }, false);

}

プロパティの概要

document.hidden 読み取り専用

ページがユーザーから隠された状態であると思われる場合に true を、そうでない場合に false を返します。

document.visibilityState 読み取り専用

ドキュメントの可視性を表す string です。以下の値になります:

  • visible : ページのコンテンツは少なくとも部分的に可視状態です。実際は、最小化されていないウィンドウのフォアグラウンドのタブにページがあることを意味します。
  • hidden : ページのコンテンツはユーザーから見えていません。実際は、ドキュメントがバックグラウンドのタブか最小化されているウィンドウにある、あるいは OS のスクリーンがロックされていることを意味します。
  • prerender : ページのコンテンツはプリレンダリングされており、ユーザーから見えていません (document.hidden では隠されているとみなされます)。ドキュメントはこの状態から始まるかもしれませんが、ほかの状態からこの状態に移ることはありません。注記: この値のサポートは必須ではありません。
  • unloaded : ページはメモリからアンロードされています。注記: この値のサポートは必須ではありません。
//startSimulation および pauseSimulation は別途定義される
function handleVisibilityChange() {
  if (document.hidden) {
    pauseSimulation();
  } else  {
    startSimulation();
  }
}

document.addEventListener("visibilitychange", handleVisibilityChange, false);

仕様

仕様書 策定状況 コメント
Page Visibility (Second Edition) 勧告 最初期の定義

ブラウザー実装状況

機能 Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
基本サポート 13 webkit
33
18 (18) [2] 10 12.10[1] 7
機能 Android Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile
基本サポート 4.4 webkit 18.0 (18) [2] 10 12.10[1] 7

[1] ブラウザーウィンドウを最小化しても visibilitychange イベントは発生せず、また hiddentrue に変わりません。

[2] Firefox 10 から Firefox 51 まで、このプロパティは -moz- 接頭辞を使用することができました。

関連情報

ドキュメントのタグと貢献者

 このページの貢献者: yyss, ethertank
 最終更新者: yyss,