Element.requestFullscreen()

Element.requestFullscreen() メソッドは、要素を全画面表示するための非同期的な要求を発行します。

要素が全画面モードに移行することは保証されていません。全画面モードに移行する許可が与えられている場合は、返される Promise が解決され、文書が全画面モードになったことを知ることができる fullscreenchange イベントを受け取るようになります。権限が拒否された場合は、代わりに fullscreenerror イベントを受け取ります。 このメソッドはユーザーの操作または機器の方向の変更によって呼び出す必要があり、そうでなければ失敗します。

構文

requestFullscreen()
requestFullscreen(options)

引数

options 省略可

全画面モードへの移行時の挙動を制御するオブジェクトです。利用できるオプションは以下の通りです。

要素が全画面モードのときにナビゲーション UI を表示するかどうかを制御します。 既定値では "auto" であり、これはブラウザーが何をすべきかを決定することを示す。

"hide"

このとき、ブラウザーのナビゲーションインターフェースは非表示になり、画面全体が要素の表示に割り当てられます。

"show"

ブラウザーは、ページナビゲーションコントロールや、場合によっては他のユーザーインターフェイスを表示します。要素の寸法（および画面の知覚サイズ）は、このユーザーインターフェイスのためのスペースを残すために締め付けられます。

"auto"

上記の設定のうち、どれを適用するかはブラウザーが選択します。 これが既定値です。

返値

全画面への移行が完了した時に、 undefined の値で解決する Promise です。

例外

requestFullscreen() プロシージャは、従来の例外を発生させるのではなく、返された Promise を拒否することでエラー状況を知らせます。拒絶ハンドラーは以下の例外値のいずれかを受け取ります。

TypeError

例外 TypeError は以下のいずれかの状況で送出されることがあります。

  • その要素を含む文書が完全にアクティブでない、つまり、現在のアクティブ文書でない。
  • その要素が文書内に含まれていない。
  • この要素は、機能ポリシーの設定または他のアクセス制御機能により、 "fullscreen" 機能を使用することが許可されていない。
  • 要素とその文書が同じノードである。

セキュリティ

ユーザーによる一時的な有効化が必要です。この機能が動作するためには、ユーザーがページまたは UI 要素と対話する必要があります。

使用上のメモ

互換性のある要素

全画面モードにするための要素は、次のようないくつかの単純な条件を満たしていなければなりません。

  • 標準の HTML 要素または <svg> または <math> のいずれかであること。
  • <dialog> 要素ではないこと。
  • 最上位の文書内か、 allowfullscreen 属性を適用した <iframe> 内に位置していなければなりません。

さらに、もちろん、機能ポリシー "fullscreen" の権限も付与されていなければなりません。

全画面起動の検出

全画面モードへの切り替えが成功したかどうかは、 requestFullscreen() が返す Promise を使用することで判断することができます。下記の例にある通りです。

他のコードが全画面モードのオンとオフを切り替えたことを知るためには、 fullscreenchange イベントに対するリスナーを Document に設置する必要があります。 また、例えばユーザーが手動で全画面モードを切り替えたときや、ユーザーがアプリケーションを切り替えてアプリケーションが一時的に全画面モードを終了したときなどを認識するために fullscreenchange を待ち受けすることも重要です。

例

全画面モードのリクエスト

この関数は、文書内で最初に得られた <video> 要素を全画面モードに切り替えたり、全画面モードを終了させたりします。

function toggleFullscreen() {
  let elem = document.querySelector("video");

  if (!document.fullscreenElement) {
    elem.requestFullscreen().catch((err) => {
      alert(`Error attempting to enable fullscreen mode: ${err.message} (${err.name})`);
    });
  } else {
    document.exitFullscreen();
  }
}

文書内の文書がまだ全画面モードでなければ、 document.fullscreenElement に値があるかどうかを見て検出し、動画の requestFullscreen() メソッドを呼び出します。成功した場合は何らかの処理をする必要はありませんが、リクエストに失敗した場合はプロミスの catch() ハンドラーが適切なエラーメッセージとともに警告を表示します。

逆に、既に全画面モードが有効な場合は、 document.exitFullscreen() を呼び出して全画面モードを無効化します。

この例をその場で見ることができます。また、コードを見たり改造したりすることが Glitch でできます。

この例では、 requestFullscreen() を文書の Document.documentElement、すなわち文書のルートである <html> 要素に対して呼び出すことによって、文書全体を全画面モードにすることができるようになっています。 

let elem = document.documentElement;

elem.requestFullscreen({ navigationUI: "show" }).then(() => {}).catch((err) => {
  alert(`An error occurred while trying to switch into fullscreen mode: ${err.message} (${err.name})`);
});

プロミスの解決ハンドラーは何もしませんが、プロミスが拒否された場合は alert() を呼び出すことでエラーメッセージが表示します。

仕様書

Specification
Fullscreen API Standard
# ref-for-dom-element-requestfullscreen①

ブラウザーの互換性

BCD tables only load in the browser

関連情報