Fullscreen API
Fullscreen API は、特定の Element
(およびその子孫) を全画面モードで表示したり、必要なくなったときに全画面モードを抜けたりする方法を追加します。これによって、要求されたコンテンツ — オンラインゲームなど — がユーザーの画面全体で表示され、全画面モードが終了するまで、ブラウザーのユーザーインターフェイス要素や他のアプリケーションをすべて画面から排除することができます。
API の使い方についての詳細は、 Fullscreen API ガイド (en-US)をご覧ください。
メモ: この API の対応はブラウザーによって、ベンダー接頭辞が必要かどうか、最新の仕様を実装しているかどうかがいくらか異なっています。この API の実装状況の詳細は、 Browser compatibility の節を参照してください。ベンダーに依存せずに Fullscreen API にアクセスできる Fscreen のようなライブラリの使用を検討したほうが良いかもしれません。
インターフェイス
Fullscreen API 自体に独自のインターフェイスはありません。その代わりに、全画面機能を提供するために必要なメソッド、プロパティ、イベントハンドラーを数多くの他のインターフェイスに追加しています。これらは以下の節に挙げています。
メソッド
Document インターフェイスのメソッド
Document.exitFullscreen()
- ユーザーエージェントが全画面モードからウィンドウモードに切り替えることをリクエストします。返される
Promise
は、全画面モードが完全に終了するときに解決します。
Element インターフェイスのメソッド
Element.requestFullscreen()
- ユーザーエージェントに対して、指定された要素 (および、子孫まで) を全画面モードに配置し、ブラウザーのユーザーインターフェイス要素や他のアプリケーションをすべて画面から排除します。返される
Promise
は、全画面モードが起動したときに解決します。
プロパティ
全画面モードで表示したい要素 (例えば <video>
要素) があるときに、その要素で requestFullscreen()
メソッドを呼び出すと全画面で表示できます。
DocumentOrShadowRoot.fullscreenElement
fullscreenElement
プロパティで、現在全画面モードで表示されている DOM (またはシャドウ DOM) 上のElement
が分かります。これがnull
の場合、文書は全画面モードになっていません。Document.fullscreenEnabled
fullscreenEnabled
プロパティで、全画面モードになることができるかどうかが分かります。全画面モードが何らかの理由で利用できない場合 ("fullscreen"
機能が許可されていない場合や、全画面モードに対応していない場合など) はfalse
になります。
イベントハンドラー
Fullscreen API は二つのイベントを定義しており、全画面モードに移行したときと終了したとき、また全画面モードとウィンドウモードを切り替える途中でエラーが発生したことを検出するために利用することができます。これらのイベントのイベントハンドラーは Document
および Element
インターフェイスで利用できます。
メモ: これらのイベントハンドラープロパティは、 HTML の content 属性として利用することはできません。言い換えれば、 fullscreenchange
および fullscreenerror
のためのイベントハンドラーを HTML コンテンツから指定することができません。 JavaScript コードによって追加する必要があります。
文書のイベントハンドラー
Document.onfullscreenchange
- 文書が全画面モードに配置されたとき、または全画面モードを終了したときに
Document
に対して送信されるfullscreenchange
イベントのイベントハンドラーです。このハンドラーは文書全体が全画面モードで表示された時のみ呼び出されます。 Document.onfullscreenerror
- 文書全体に対して全画面モードを有効または無効にしようとした際にエラーが発生したとき、
Document
に対して送信されるfullscreenerror
イベントのイベントハンドラーです。
要素のイベントハンドラー
Element.onfullscreenchange
- 要素が全画面モードに配置されたとき、または全画面モードを終了したときに要素に対して送信される
fullscreenchange
イベントのイベントハンドラーです。 Element.onfullscreenerror
- 要素が全画面モードに移行または終了しようとした際にエラーが発生したとき、要素に対して送信される
fullscreenerror
イベントのイベントハンドラーです。
廃止されたプロパティ
Document.fullscreen
Deprecated- 真偽値で、文書に現在全画面モードで表示されている要素があるのであれば
true
、 それ以外はfalse
を返します。メモ: 代わりにDocument
またはShadowRoot
のfullscreenElement
プロパティを使用してください。これがnull
ではない場合、現在全画面モードで表示されているElement
を表します。
イベント
Fullscreen API は二つのイベントを定義しており、全画面モードに移行したときと終了したとき、また全画面モードとウィンドウモードを切り替える途中でエラーが発生したことを検出するために利用することができます。
fullscreenchange
- 全画面モードに移行したり、終了したりした時に、
Document
またはElement
に対して送られます。 fullscreenerror
- 全画面モードに切り替えたり、終了したりした際にエラーが発生した時に、その
Document
またはElement
に対して送られます。
Dictionary
FullscreenOptions
(en-US)requestFullscreen()
を呼び出す時に指定することができる任意の設定を提供します。
アクセス制御
使用上のメモ
ユーザーは全画面モードを解除するのを、サイトやアプリがプログラム的に行うのを待つのではなく、 ESC または F11 キーを押すことで抜けることを選択することができます。ユーザーインターフェイスの中で、これができることをユーザーに知らせるための適切なユーザーインターフェイス要素を、ユーザーインターフェイスのどこかで提供することを忘れないでください。
メモ: 全画面モードであるときに別のページへ移動する、タブを切り替える、あるいは別のアプリケーションに切り替える (例えば Alt-Tab を使用) と、同様に全画面モードを解除します。
例
この例では、ウェブページ内に動画が表示されます。 Return または Enter キーを押すと、動画をウィンドウ内表示と全画面表示とで切り替えることができます。
Enter キーの監視
ページが読み込まれると、 Enter キーを監視するイベントリスナーを設定するコードが実行されます。
document.addEventListener("keypress", function(e) {
if (e.keyCode === 13) {
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()
を呼び出すことで、全画面モードを終了します。
仕様書
仕様書 | 状態 | 備考 |
---|---|---|
Fullscreen API | 現行の標準 | 初回定義 |
ブラウザーの対応
Document.fullscreen
BCD tables only load in the browser
Document.fullscreenEnabled
BCD tables only load in the browser