全画面 API
全画面 API は、特定の要素 (Element
) (およびその子孫)を全画面モードで表示したり、必要なくなったときに全画面モードを抜けたりする方法を追加します。これによって、要求されたコンテンツ — オンラインゲームなど — がユーザーの画面全体で表示され、全画面モードが終了するまで、ブラウザーのユーザーインターフェイス要素や他のアプリケーションをすべて画面から排除することができます。
API の使い方についての詳細は、 全画面 API ガイドをご覧ください。
インターフェイス
全画面 API 自体に独自のインターフェイスはありません。その代わりに、全画面機能を提供するために必要なメソッド、プロパティ、イベントハンドラーを数多くの他のインターフェイスに追加しています。これらは以下の節に挙げています。
インスタンスメソッド
Document インターフェイスのインスタンスメソッド
Document.exitFullscreen()
-
ユーザーエージェントが全画面モードからウィンドウモードに切り替えることをリクエストします。返される
Promise
は、全画面モードが完全に終了したときに解決します。
Element インターフェイスのインスタンスメソッド
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"
であり、最上位の文書コンテキストでは全画面モードが許可されており、最上位文書と同じオリジンから読み込まれた内側の閲覧コンテキストも同様です。
使用上のメモ
ユーザーは全画面モードを解除するのを、サイトやアプリがプログラム的に行うのを待つのではなく、 ESC または F11 キーを押すことで抜けることを選択することができます。ユーザーインターフェイスの中で、これができることをユーザーに知らせるための適切なユーザーインターフェイス要素を、ユーザーインターフェイスのどこかで提供することを忘れないでください。
メモ: 全画面モードであるときに別のページへ移動する、タブを切り替える、あるいは別のアプリケーションに切り替える (例えば Alt-Tab を使用) と、同様に全画面モードを解除します。
例
単純な全画面の使用
この例では、ウェブページ内に動画が表示されます。 Enter キーを押すと、動画をウィンドウ内表示と全画面表示とで切り替えることができます。
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()
を呼び出すことで、全画面モードを終了します。
仕様書
ブラウザーの互換性
api.Document.fullscreenElement
Report problems with this compatibility data on GitHubdesktop | mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
fullscreenElement |
Legend
Tip: you can click/tap on a cell for more information.
- Full support
- Full support
- Partial support
- Partial support
- Uses a non-standard name.
- Requires a vendor prefix or different name for use.
- Has more compatibility info.
api.Document.fullscreenEnabled
Report problems with this compatibility data on GitHubdesktop | mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
fullscreenEnabled |
Legend
Tip: you can click/tap on a cell for more information.
- Full support
- Full support
- Partial support
- Partial support
- No support
- No support
- Uses a non-standard name.
- Requires a vendor prefix or different name for use.
- Has more compatibility info.
api.Document.exitFullscreen
Report problems with this compatibility data on GitHubdesktop | mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
exitFullscreen | ||||||||||||
Returns a Promise |
Legend
Tip: you can click/tap on a cell for more information.
- Full support
- Full support
- Partial support
- Partial support
- No support
- No support
- Uses a non-standard name.
- Requires a vendor prefix or different name for use.
- Has more compatibility info.
api.Element.requestFullscreen
Report problems with this compatibility data on GitHubdesktop | mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
requestFullscreen | ||||||||||||
options.navigationUI parameter | ||||||||||||
options.screen parameter | ||||||||||||
Returns a Promise |
Legend
Tip: you can click/tap on a cell for more information.
- Full support
- Full support
- Partial support
- Partial support
- No support
- No support
- Experimental. Expect behavior to change in the future.
- Uses a non-standard name.
- Requires a vendor prefix or different name for use.
- Has more compatibility info.
api.Document.fullscreen
Report problems with this compatibility data on GitHubdesktop | mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
fullscreen |
Legend
Tip: you can click/tap on a cell for more information.
- Full support
- Full support
- Partial support
- Partial support
- No support
- No support
- Deprecated. Not for use in new websites.
- Uses a non-standard name.
- Has more compatibility info.