ピクチャインピクチャ 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 ハンドラーから呼び出されます。

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

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

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

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

仕様書

ブラウザーの互換性

関連情報

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