ピクチャインピクチャ API
Limited availability
This feature is not Baseline because it does not work in some of the most widely-used browsers.
ピクチャインピクチャ 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 ハンドラーから呼び出されます。
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