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
イベントを受け取ります。
このメソッドはユーザーの操作または機器の方向の変更によって呼び出す必要があり、そうでなければ失敗します。
構文
requestFullscreen()
requestFullscreen(options)
引数
options
省略可-
全画面モードへの移行時の挙動を制御するオブジェクトです。利用できるオプションは以下の通りです。
-
要素が全画面モードのときにナビゲーション UI を表示するかどうかを制御します。 既定値では
"auto"
であり、これはブラウザーが何をすべきかを決定することを示す。 screen
省略可 Experimental-
要素を全画面モードで表示したい画面を指定します。これは
ScreenDetailed
オブジェクトを値として取り、選択された画面を表します。
-
返値
全画面への移行が完了した時に、 undefined
の値で解決する Promise
です。
例外
requestFullscreen()
プロシージャは、従来の例外を発生させるのではなく、返された Promise
を拒否することでエラー状況を知らせます。拒絶ハンドラーは以下の例外値のいずれかを受け取ります。
TypeError
-
例外
TypeError
は以下のいずれかの状況で送出されることがあります。- その要素を含む文書が完全にアクティブでない、つまり、現在のアクティブ文書でない。
- その要素が文書内に含まれていない。
- この要素は、権限ポリシーの設定または他のアクセス制御機能により、
fullscreen
機能を使用することが許可されていない。 - 要素とその文書が同じノードである。
- この要素がポップオーバーであり、既に
HTMLElement.showPopover()
で表示されている。
セキュリティ
ユーザーによる一時的な有効化が必要です。この機能が動作するためには、ユーザーがページまたは UI 要素と対話する必要があります。
使用上のメモ
互換性のある要素
全画面モードにするための要素は、次のようないくつかの単純な条件を満たしていなければなりません。
- 標準の HTML 要素または
<svg>
または<math>
のいずれかであること。 <dialog>
要素ではないこと。- 最上位の文書内か、
allowfullscreen
属性を適用した<iframe>
内に位置していなければなりません。
さらに、設定された権限ポリシーがこの機能の使用を許可している必要があります。
全画面起動の検出
全画面モードへの切り替えが成功したかどうかは、 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 でできます。
navigationUI の使用
この例では、 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()
を呼び出すことでエラーメッセージが表示します。
screen オプションの使用
要素を OS の第 1 画面で全画面にしたい場合は、以下のようなコードを使用することで実現できます。
try {
const primaryScreen = (await getScreenDetails()).screens.find(
(screen) => screen.isPrimary,
);
await document.body.requestFullscreen({ screen: primaryScreen });
} catch (err) {
console.error(err.name, err.message);
}
Window.getScreenDetails()
メソッドを使用して、現在の端末の ScreenDetails
オブジェクトを取得します。これには、利用できるさまざまな画面を表す ScreenDetailed
オブジェクトが格納されています。
仕様書
Specification |
---|
Fullscreen API Standard # ref-for-dom-element-requestfullscreen① |
ブラウザーの互換性
BCD tables only load in the browser