全画面 API のガイド

この記事では、全画面 API を使用して指定された要素を全画面モードにする方法と、ブラウザーの全画面モードへの移行と終了を検出する方法について説明します。

全画面モードの有効化

全画面モードで表示したい要素（例えば <video> など）がある場合、その requestFullscreen() メソッドを呼び出すことによって、全画面モードで表示させることができます。

この <video> 要素について考えてみましょう。

html
<video controls id="myvideo">
  <source src="somevideo.webm"></source>
  <source src="somevideo.mp4"></source>
</video>

この video 要素を以下のように全画面化することができます。

js
const elem = document.getElementById("myvideo");
if (elem.requestFullscreen) {
  elem.requestFullscreen();
}

このコードでは、requestFullscreen() メソッドが存在するかどうかを調べてから、それを呼び出しています。

ここで、現時点での Gecko と WebKit の実装の重要な違いに注目しておきましょう。Gecko は自動的に CSS ルール "width: 100%; height: 100%;" を要素に追加し、画面の内側へ引き伸ばすようにします。 WebKit はこのようなことはせず、代わりに全画面表示の要素を同じ大きさで、それ以外は真っ黒な画面の中央に配置します。 WebKit で同じ全画面表示を取得するには、自分自身で "width: 100%; height: 100%;" を CSS ルールに追加する必要があります。

css
#myvideo:-webkit-full-screen {
  width: 100%;
  height: 100%;
}

一方、 WebKit の動作を Gecko 上で模倣しようとする場合、表示したい要素を別の要素の内部に配置し、その要素を代わりに全画面化し、 CSS ルールを使用して内側の要素を表示したい外観に一致するように調整する必要があります。

通知

全画面モードが正常に実行されると、その要素を含む文書は fullscreenchange イベントを受け取ります。全画面モードが終了すると、その文書は再び fullscreenchange イベントを受け取ります。なお、 fullscreenchange イベントは、文書が全画面モードに入るか抜けるかについての情報そのものは提供しませんが、もし文書に null ではない fullscreenElement があれば、全画面モードであることが分かります。

全画面リクエストに失敗した場合

全画面モードに切り替わることは保証されていません。例えば、<iframe> 要素には全画面モードでコンテンツを表示することを許可するためのallowfullscreen 属性があります。また、ウィンドウ形式のプラグインなど、特定の種類の中身は全画面モードで表示することができません。全画面表示できない要素（またはその親や子孫）を全画面表示にしようとしても、これはうまくいきません。その代わりに、全画面表示をリクエストされた要素は mozfullscreenerror イベントを受け取ります。全画面表示に失敗した場合、 Firefox はウェブコンソールにエラーメッセージをログ出力し、なぜ失敗したのかを説明します。しかし、 Chrome や Opera の新しいバージョンでは、そのような警告は生成されません。

メモ: 全画面リクエストは、イベントハンドラー内で呼び出す必要があり、そうでない場合は拒否されます。

全画面モードからの脱出

ユーザーは常に自分自身で全画面モードを終了することができます。ユーザーが知りたいことを参照してください。また、 Document.exitFullscreen() メソッドを呼び出すことで、プログラム的にそうすることも可能です。

その他の情報

Document は、全画面表示のウェブアプリケーションを開発する際に有益な追加情報を提供します。

Document.fullscreenElement / ShadowRoot.fullscreenElement

fullscreenElement プロパティは、現在全画面表示されている Element を指示します。これが null でない場合、文書（またはシャドウ DOM）は全画面モードになっています。もしこれが null ならば、文書（またはシャドウ DOM）は全画面モードではありません。

Document.fullscreenEnabled

fullscreenEnabled プロパティは、現在文書内の全画面モードがリクエストされる状態であるかどうかを指示します。

モバイルブラウザーのビューポートの拡大縮小

モバイルブラウザーによっては、全画面モードのときにビューポートメタタグの設定を無視し、ユーザーによる拡大縮小をブロックするものがあります。例えば、全画面モードでないときにピンチ操作で拡大縮小することができたとしても、全画面モードで表示されたページではピンチ操作で拡大縮小するジェスチャーが動作しないことがあります。

ユーザーが知りたいこと

ユーザーには、Esc キー（または F11）を押して全画面モードを終了できることを必ず伝えておくとよいでしょう。

また、全画面モード中に他のページに移動したり、タブを切り替えたり、他のアプリケーションに切り替える（例: Alt-Tab など）と、全画面モードも終了してしまいます。

例

この例では、ウェブページの中に動画を表示しています。Return または Enter キーを押すと、ユーザーは動画のウィンドウ表示と全画面表示を切り替えて表示することができます。

ライブ例の表示

Enter キーの監視

ページが読み込まれると、このコードが実行され、 Enter キーを待ち受けるためのイベントリスナーが設定されます。

js
document.addEventListener(
  "keydown",
  (e) => {
    if (e.keyCode === 13) {
      toggleFullScreen();
    }
  },
  false,
);

全画面モードのトグル切り替え

このコードは、上図のようにユーザーが Enter キーを押したときに呼び出されます。

js
function toggleFullScreen() {
  if (!document.fullscreenElement) {
    document.documentElement.requestFullscreen();
  } else if (document.exitFullscreen) {
    document.exitFullscreen();
  }
}

これは document の fullscreenElement 属性の値を調べることから始まります。もし null ならば、文書内のモードは現在ウィンドウモードなので、全画面モードに切り替える必要があります。全画面モードへの切り替えは element.requestFullscreen() を呼び出すことで行われます。

もし既に全画面モードが有効な場合（fullscreenElement が null でない場合）、 document.exitFullscreen() を呼び出すことになります。

接頭辞

今のところ、すべてのブラウザーが接頭辞なしバージョンの API を実装しているわけではありません（ベンダーに依存しない全画面 API へのアクセスには Fscreen を使用することができます）。以下は、接頭辞と名前の異なる形をまとめた表です。

標準 WebKit (Safari) / Blink (Chrome & Opera) / Edge Gecko (Firefox) Internet Explorer Document.fullscreenDocument.fullscreenEnabled Document.fullscreenElement Document.exitFullscreen()Element.requestFullscreen()

webkitIsFullScreen	mozFullScreen	-
webkitFullscreenEnabled	mozFullScreenEnabled	msFullscreenEnabled
webkitFullscreenElement	mozFullScreenElement	msFullscreenElement
webkitExitFullscreen()	mozCancelFullScreen()	msExitFullscreen()
webkitRequestFullscreen()	mozRequestFullScreen()	msRequestFullscreen()