Element: requestFullscreen() メソッド

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

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

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

構文

js
requestFullscreen()
requestFullscreen(options)

引数

options 省略可

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

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

"hide"

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

"show"

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

"auto"

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

screen 省略可

要素を全画面モードで表示したい画面を指定します。これは ScreenDetailed オブジェクトを値として取り、選択された画面を表します。

返値

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

例外

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

TypeError

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

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

セキュリティ

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

使用上のメモ

互換性のある要素

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