全画面 API のガイド
============

この記事では、全画面 API を使用して指定された要素を全画面モードにする方法と、ブラウザーの全画面モードへの移行と終了を検出する方法について説明します。

全画面モードの有効化
----------

全画面モードで表示したい要素（例えば `<video>` など）がある場合、その `requestFullscreen()` メソッドを呼び出すことによって、全画面モードで表示させることができます。

この `<video>` 要素について考えてみましょう。


```html
<video controls id="myvideo">
  <source src="somevideo.webm"></source>
  <source src="somevideo.mp4"></source>
</video>
```


この video 要素を以下のように全画面化することができます。


```js
const elem = document.getElementById("myvideo");
if (elem.requestFullscreen) {
  elem.requestFullscreen();
}
```


このコードでは、`requestFullscreen()` メソッドが存在するかどうかを調べてから、それを呼び出しています。

### 表示の差異について

ここで、現時点での Gecko と WebKit の実装の重要な違いに注目しておきましょう。Gecko は自動的に CSS ルール "`width: 100%; height: 100%;`" を要素に追加し、画面の内側へ引き伸ばすようにします。 WebKit はこのようなことはせず、代わりに全画面表示の要素を同じ大きさで、それ以外は真っ黒な画面の中央に配置します。 WebKit で同じ全画面表示を取得するには、自分自身で "`width: 100%; height: 100%;`" を CSS ルールに追加する必要があります。


```css
#myvideo:-webkit-full-screen {
  width: 100%;
  height: 100%;
}
```


一方、 WebKit の動作を Gecko 上で模倣しようとする場合、表示したい要素を別の要素の内部に配置し、その要素を代わりに全画面化し、 CSS ルールを使用して内側の要素を表示したい外観に一致するように調整する必要があります。

### 通知

全画面モードが正常に実行されると、その要素を含む文書は `fullscreenchange` イベントを受け取ります。全画面モードが終了すると、その文書は再び `fullscreenchange` イベントを受け取ります。なお、 `fullscreenchange` イベントは、文書が全画面モードに入るか抜けるかについての情報そのものは提供しませんが、もし文書に null ではない `fullscreenElement` があれば、全画面モードであることが分かります。

### 全画面リクエストに失敗した場合

全画面モードに切り替わることは保証されていません。例えば、`<iframe>` 要素には全画面モードでコンテンツを表示することを許可するための`allowfullscreen` 属性があります。また、ウィンドウ形式のプラグインなど、特定の種類の中身は全画面モードで表示することができません。全画面表示できない要素（またはその親や子孫）を全画面表示にしようとしても、これはうまくいきません。その代わりに、全画面表示をリクエストされた要素は `mozfullscreenerror` イベントを受け取ります。全画面表示に失敗した場合、 Firefox はウェブコンソールにエラーメッセージをログ出力し、なぜ失敗したのかを説明します。しかし、 Chrome や Opera の新しいバージョンでは、そのような警告は生成されません。

**メモ:** 全画面リクエストは、イベントハンドラー内で呼び出す必要があり、そうでない場合は拒否されます。

全画面モードからの脱出
-----------

ユーザーは常に自分自身で全画面モードを終了することができます。ユーザーが知りたいことを参照してください。また、 `Document.exitFullscreen()` メソッドを呼び出すことで、プログラム的にそうすることも可能です。

その他の情報
------

`Document` は、全画面表示のウェブアプリケーションを開発する際に有益な追加情報を提供します。

`Document.fullscreenElement` / `ShadowRoot.fullscreenElement`

`fullscreenElement` プロパティは、現在全画面表示されている `Element` を指示します。これが null でない場合、文書（またはシャドウ DOM）は全画面モードになっています。もしこれが null ならば、文書（またはシャドウ DOM）は全画面モードではありません。

`Document.fullscreenEnabled`

`fullscreenEnabled` プロパティは、現在文書内の全画面モードがリクエストされる状態であるかどうかを指示します。

### モバイルブラウザーのビューポートの拡大縮小

モバイルブラウザーによっては、全画面モードのときにビューポートメタタグの設定を無視し、ユーザーによる拡大縮小をブロックするものがあります。例えば、全画面モードでないときにピンチ操作で拡大縮小することができたとしても、全画面モードで表示されたページではピンチ操作で拡大縮小するジェスチャーが動作しないことがあります。

ユーザーが知りたいこと
-----------

ユーザーには、`Esc` キー（または `F11`）を押して全画面モードを終了できることを必ず伝えておくとよいでしょう。

また、全画面モード中に他のページに移動したり、タブを切り替えたり、他のアプリケーションに切り替える（例: `Alt`-`Tab` など）と、全画面モードも終了してしまいます。

例
-

この例では、ウェブページの中に動画を表示しています。`Return` または `Enter` キーを押すと、ユーザーは動画のウィンドウ表示と全画面表示を切り替えて表示することができます。

ライブ例の表示

### Enter キーの監視

ページが読み込まれると、このコードが実行され、 `Enter` キーを待ち受けるためのイベントリスナーが設定されます。


```js
document.addEventListener(
  "keydown",
  (e) => {
    if (e.keyCode === 13) {
      toggleFullScreen();
    }
  },
  false,
);
```

### 全画面モードのトグル切り替え

このコードは、上図のようにユーザーが `Enter` キーを押したときに呼び出されます。


```js
function toggleFullScreen() {
  if (!document.fullscreenElement) {
    document.documentElement.requestFullscreen();
  } else if (document.exitFullscreen) {
    document.exitFullscreen();
  }
}
```


これは `document` の `fullscreenElement` 属性の値を調べることから始まります。もし `null` ならば、文書内のモードは現在ウィンドウモードなので、全画面モードに切り替える必要があります。全画面モードへの切り替えは `element.requestFullscreen()` を呼び出すことで行われます。

もし既に全画面モードが有効な場合（`fullscreenElement` が `null` でない場合）、 `document.exitFullscreen()` を呼び出すことになります。

接頭辞
---

今のところ、すべてのブラウザーが接頭辞なしバージョンの API を実装しているわけではありません（ベンダーに依存しない全画面 API へのアクセスには Fscreen を使用することができます）。以下は、接頭辞と名前の異なる形をまとめた表です。

| 標準 | WebKit (Safari) / Blink (Chrome & Opera) / Edge | Gecko (Firefox) | Internet Explorer |
| --- | --- | --- | --- |
| `Document.fullscreen` 
非推奨
 | `webkitIsFullScreen` | `mozFullScreen` | - |
| `Document.fullscreenEnabled` | `webkitFullscreenEnabled` | `mozFullScreenEnabled` | `msFullscreenEnabled` |
| `Document.fullscreenElement` | `webkitFullscreenElement` | `mozFullScreenElement` | `msFullscreenElement` |
| `Document.exitFullscreen()` | `webkitExitFullscreen()` | `mozCancelFullScreen()` | `msExitFullscreen()` |
| `Element.requestFullscreen()` | `webkitRequestFullscreen()` | `mozRequestFullScreen()` | `msRequestFullscreen()` |

仕様書
---

| Specification |
| --- |
| Fullscreen API Standard # ref-for-dom-document-fullscreenenabled① |
| Fullscreen API Standard # dom-document-fullscreen |

ブラウザーの互換性
---------

### api.Document.fullscreenEnabled

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

### api.Document.fullscreen

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* 全画面モードの使用
* `Element.requestFullscreen()`
* `Document.exitFullscreen()`
* `Document.fullscreen`
* `Document.fullscreenElement`
* `:fullscreen`, `::backdrop`
* `allowfullscreen`