ピクチャインピクチャ API
==============

**ピクチャインピクチャ API** (Picture-in-Picutre API) では、ウェブサイトが他のウィンドウの上に常に浮かぶ動画ウィンドウを作成し、ユーザーが他のコンテンツサイトや端末上のアプリケーションを操作しながらメディアを視聴し続けることができます。

インターフェイス
--------

`PictureInPictureWindow`

浮動動画ウィンドウを表します。これには `width` および `height`、そして `onresize` イベントハンドラープロパティがあります。

インスタンスメソッド
----------

ピクチャインピクチャ API は、 `HTMLVideoElement` と `Document` インターフェイスにメソッドを追加し、浮動動画ウィンドウを切り替えられるようにします。

### HTMLVideoElement インターフェイスのインスタンスメソッド

`HTMLVideoElement.requestPictureInPicture()`

ユーザーエージェントが動画をピクチャインピクチャモードにするようリクエストします。

### Document インターフェイスのインスタンスメソッド

`Document.exitPictureInPicture()`

ユーザーエージェントがピクチャインピクチャモードの要素を元のボックスに返すようにリクエストします。

インスタンスプロパティ
-----------

ピクチャインピクチャ API は、`HTMLVideoElement`、`Document`、`ShadowRoot` の各インターフェイスを拡張し、浮動動画ウィンドウモードに対応しているかどうか、利用できるかどうか、ピクチャインピクチャモードが現在有効かどうか、どの動画が浮動しているかを判断するために使用できるプロパティを提供します。

### HTMLVideoElement インターフェイスのインスタンスプロパティ

`HTMLVideoElement.disablePictureInPicture`

`disablePictureInPicture` プロパティは、ユーザーエージェントにピクチャインピクチャをユーザーに提案しない、または自動的にリクエストしないようにするヒントを提供します。

### Document インターフェイスのインスタンスプロパティ

`Document.pictureInPictureEnabled`

`pictureInPictureEnabled` プロパティはピクチャインピクチャモードが使用可能かどうかを指示します。何らかの理由でピクチャインピクチャモードが利用できない場合（例えば、`"picture-in-picture"` 機能が許可されていない、またはピクチャインピクチャモードに対応していない場合）は `false` となります。

### Document または ShadowRoot インターフェイスのインスタンスプロパティ

`Document.pictureInPictureElement` / `ShadowRoot.pictureInPictureElement`

`pictureInPictureElement` プロパティで、浮動ウィンドウ（またはシャドウ DOM）に現在表示されている要素 (`Element`) を伝えます。これが `null` である場合、文書（またはシャドウ DOM）内には現在ピクチャインピクチャモードになっているノードがありません。

イベント
----

*ピクチャインピクチャ API では 3 つのイベントを定義しており、ピクチャインピクチャモードが切り替わったときや、浮動要素であるウィンドウのサイズが変更されたことを検出するために利用できます。*

`enterpictureinpicture`

ピクチャインピクチャモードになったときに `HTMLVideoElement` に送られます。

`leavepictureinpicture`

ピクチャインピクチャモードから抜けるときに `HTMLVideoElement` に送られます。

`resize`

サイズ変更時に `PictureInPictureWindow` に送られます。

コントロールの追加
---------

メディアアクションハンドラーがメディアセッション API を介して設定されている場合、それらのアクションのための適切なコントロールがブラウザーによってピクチャインピクチャのオーバーレイに追加されます。例えば、 `"nexttrack"` アクションが設定されている場合、ピクチャインピクチャビューにスキップボタンが表示されるかもしれません。独自の HTML ボタンやコントロールを追加するための対応はありません。

スタイルの制御
-------

`:picture-in-picture` は CSS の擬似クラスで、現在ピクチャインピクチャモードになっている動画要素に一致します。これにより、動画がピクチャインピクチャモードと従来の表示モードを行き来するときに、コンテンツのサイズやスタイル、レイアウトを自動的に調整するようにスタイルシートを設定することができます。

アクセスの制御
-------

ピクチャインピクチャモードが利用できるかは、権限ポリシーを使って制御することができます。全画面モード機能は文字列 `"picture-in-picture"` で識別され、既定値の allowlist 値は `"self"` です。これは、ピクチャインピクチャモードが最上位の文書コンテキストで許可されることと、最上位の文書と同じオリジンから読み込まれた入れ子の閲覧コンテキストで許可されることを意味します。

例
-

この例では、ウェブページに動画を表示しています。下記のボタンをクリックすると、ユーザーは浮動動画ウィンドウを切り替えることができます。

### ピクチャインピクチャモードの切り替え

このコードは、ユーザーが "Toggle Picture-in-Picture" ボタンをクリックすると、 click ハンドラーから呼び出されます。


```js
function togglePictureInPicture() {
  if (document.pictureInPictureElement) {
    document.exitPictureInPicture();
  } else if (document.pictureInPictureEnabled) {
    video.requestPictureInPicture();
  }
}
```


このブロックは `document` の `pictureInPictureElement` 属性の値を見ていきます。

値が `null` でない場合、要素が現在ピクチャインピクチャモード、つまり浮動ウィンドウの中にあります。 `document.exitPictureInPicture()` を呼び出すと、動画を最初のボックスに戻ります。

値が `null` の場合、動画は浮動ウィンドウにありません。そこで、動画にピクチャインピクチャモードになるようリクエストします。そのためには、 `<video>` 要素で `HTMLVideoElement.requestPictureInPicture()` を呼び出します。

仕様書
---

| Specification |
| --- |
| Picture-in-Picture # interface-picture-in-picture-window |

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

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

関連情報
----

* `HTMLVideoElement.requestPictureInPicture()`
* `HTMLVideoElement.disablePictureInPicture`
* `Document.pictureInPictureEnabled`
* `Document.exitPictureInPicture()`
* `Document.pictureInPictureElement`
* `:picture-in-picture`