Page Visibility API の使用

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

利点

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

使用例

以下に例を示します:

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

以前、開発者はこれを検出するために不完全な代替手段を使用していました。例えば 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.mozHidden !== "undefined") {
  hidden = "mozHidden";
  visibilityChange = "mozvisibilitychange";
} 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") {
  alert("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);
    
  // ページが閉じられたときに、サイトの既存の favicon に戻す。
  // そうでなければ favicon を paused.png のままにする。
  window.addEventListener("unload", function(){
    favicon.change("/favicon.ico");
  }, false);
    
  // 動画が一時停止されたときに、favicon を設定する。
  // これは paused.png の画像を表示する。
  videoElement.addEventListener("pause", function(){
    favicon.change("images/paused.png");
  }, false);
    
  // 動画が再生されるときに、favicon を設定する。
  videoElement.addEventListener("play", function(){
    favicon.change("images/playing.png");
  }, false);
    
  // 現在の再生時間をもとにドキュメント (タブ) のタイトルを設定する
  videoElement.addEventListener("timeupdate", function(){
    document.title = Math.floor(videoElement.currentTime) + " second(s)";
  }, 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);

補足

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

仕様書

ブラウザ実装状況

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

関連情報

• IEBlog での Page Visibility API の解説
• Google による Page Visibility API の解説