全画面 API

全画面 API 自体に独自のインターフェイスはありません。その代わりに、全画面機能を提供するために必要なメソッド、プロパティ、イベントハンドラーを数多くの他のインターフェイスに追加しています。これらは以下の節に挙げています。

全画面 API は Document および Element インターフェイスにメソッドを追加して、全画面モードを起動したり終了したりすることができるようにしています。

Document.exitFullscreen()

ユーザーエージェントが全画面モードからウィンドウモードに切り替えることをリクエストします。返される Promise は、全画面モードが完全に終了したときに解決します。

Element.requestFullscreen()

ユーザーエージェントに対して、指定された要素 (および、子孫まで) を全画面モードに配置し、ブラウザーのユーザーインターフェイス要素や他のアプリケーションをすべて画面から排除します。返される Promise は、全画面モードが起動したときに解決します。

Document インターフェイスはこのインターフェースは、全画面モードに対応していて利用できるかどうか、全画面モードが現在有効であれば、どの要素が画面を使用しているかを判断するために使用できるプロパティを提供します。

Document.fullscreenElement / ShadowRoot.fullscreenElement

fullscreenElement プロパティで、現在全画面モードで表示されている DOM （またはシャドウ DOM）上の要素 (Element) が分かります。これが null の場合、文書（またはシャドウ DOM）は全画面モードになっていません。

document.fullscreenEnabled

fullscreenEnabled プロパティで、全画面モードになることができるかどうかが分かります。何らかの理由で全画面モードが利用できない場合（例えば "fullscreen" 機能が許可されていない、あるいは全画面モードが対応していない場合）、これは false となります。

Document.fullscreen 非推奨

論理値で、文書に現在全画面モードで表示されている要素があるのであれば true、 それ以外は false を返します。

メモ: 代わりに Document または ShadowRoot の fullscreenElement プロパティを使用してください。これが null ではない場合、現在全画面モードで表示されている Element を表します。

全画面 API は 2 つのイベントを定義しており、全画面モードに移行したときと終了したとき、また全画面モードとウィンドウモードを切り替える途中でエラーが発生したことを検出するために利用することができます。

fullscreenchange

全画面モードに移行したり、終了したりした時に、 Element に対して送られます。

fullscreenerror

全画面モードに切り替えたり、終了したりした際にエラーが発生した時に、 Element に対して送られます。

全画面モードが利用可能であるかは、機能ポリシーを使用して制御することができます。全画面モードの機能は "fullscreen" の文字列によって識別され、既定の許可リストの値は "self" であり、最上位の文書コンテキストでは全画面モードが許可されており、最上位文書と同じオリジンから読み込まれた内側の閲覧コンテキストも同様です。

機能ポリシーを使用して API へのアクセスを制御することについて、詳しくは機能ポリシーの使用を参照してください。

ユーザーは全画面モードを解除するのを、サイトやアプリがプログラム的に行うのを待つのではなく、 ESC または F11 キーを押すことで抜けることを選択することができます。ユーザーインターフェイスの中で、これができることをユーザーに知らせるための適切なユーザーインターフェイス要素を、ユーザーインターフェイスのどこかで提供することを忘れないでください。

この例では、ウェブページ内に動画が表示されます。 Enter キーを押すと、動画をウィンドウ内表示と全画面表示とで切り替えることができます。

ライブデモを表示

ページが読み込まれると、 Enter キーを監視するイベントリスナーを設定するコードが実行されます。

document.addEventListener(
  "keydown",
  (e) => {
    if (e.key === "Enter") {
      toggleFullScreen();
    }
  },
  false,
);

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

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

これは document の fullscreenElement 属性の値を確認することから始まります。現実の配信では現時点で、接頭辞付きのバージョン (例えば mozFullscreenElement, msFullscreenElement, webkitFullscreenElement) をチェックしたほうがいいでしょう。値が null である場合は、文書がウィンドウモードであるので、全画面モードへ切り替えることが必要です。 Element.requestFullscreen() を呼び出して、全画面モードへ切り替えます。

すでに全画面モードが有効である (fullscreenElement が null ではない) 場合は、 document の Document.exitFullscreen() を呼び出すことで、全画面モードを終了します。

• 全画面モードの使用
• Element.requestFullscreen()
• Document.exitFullscreen()
• Document.fullscreen
• Document.fullscreenElement
• :fullscreen, ::backdrop
• allowfullscreen