文書ピクチャインピクチャ API

概念と使い方

ウェブアプリで、アプリが実行されているメインウィンドウとは別に、別のウィンドウを用意しておくと便利な場合があります。特定のアプリの内容を表示したまま他のウィンドウを閲覧したい場合や、そのコンテンツ専用の空間を確保しつつ、メインのアプリウィンドウを空けて他のコンテンツを表示したい場合などです。通常の新しいブラウザーウィンドウを開くだけで対応することも可能ですが、これには 2 つの大きな問題があります。

1. 2 つのウィンドウ間で状態情報の共有を適切に処理する必要があります。
2. 追加されたアプリのウィンドウは常に最前面に表示されるわけではないため、他のウィンドウに隠れてしまうことがあります。

これらの問題を解決するため、ウェブブラウザーは、アプリが同じセッションの一部として常に最前面に表示されるウィンドウを生成できる API を導入しました。最初に認知された用途は、別のウィンドウで動画コンテンツを再生し続け、ユーザーが他のコンテンツを見ながらその視聴を継続できるようにすることでした。これは、<video> 用のピクチャインピクチャ API を使用して実装され、<video> 要素に対して直接適用することで、その要素を別のウィンドウに配置します。

しかし、この API にはいくつかの制限があることが判明しています。具体的には、常に最前面に表示されるウィンドウには、ブラウザーが生成する最小限のコントロールと共に、単一の <video> 要素しか配置できないというものです。より柔軟性を高めるため、文書ピクチャインピクチャ API が導入されました。これにより、あらゆるコンテンツを常に最前面に表示されるウィンドウに配置できるようになり、以下のような幅広い用途に対応できます。

• カスタムコントロールとスタイルを備えた、1 つまたは複数の動画を再生する「常に最前面表示」のカスタム動画プレーヤー。
• 他の参加者の映像を常に表示できる動画会議システム。さらに、コンテンツの共有、ミュート、通話の終了などの操作機能も備えています。
• タイマー、メモ、ToDo リスト、メッセンジャーツールなど、常に表示される生産性向上ツール。
• メインアプリのウィンドウをすっきりとした状態に保ちつつ、追加コンテンツを表示するための独立したウィンドウ。例えば、アクションゲームやロールプレイングゲームをプレイする際、ゲームの操作方法、説明、設定などの情報を追加ウィンドウに表示し、メインウィンドウではゲーム内のロケーションやマップを表示できるようにする場合など。

どの様に動作するか

現在の文書コンテキストにおける、常に最前面に表示されるピクチャインピクチャ (PiP) ウィンドウを表す新しい DocumentPictureInPicture オブジェクトのインスタンスは、Window.documentPictureInPicture を通じて利用可能です。ピクチャインピクチャーウィンドウは、DocumentPictureInPicture.requestWindow() メソッドを呼び出すことで開くことができます。このメソッドは、ウィンドウ自身の Window オブジェクトを返値とする Promise を返します。

ピクチャインピクチャー (PIP) ウィンドウは、Window.open() を通じて開かれる同一オリジンの空白ウィンドウと似ていますが、いくつかの違いがあります。

• ピクチャインピクチャウィンドウは、他のウィンドウの上に表示されます。
• ピクチャインピクチャウィンドウは、それを開いたウィンドウが閉じられると自動的に閉じられます。
• ピクチャインピクチャウィンドウ内では、ページ移動を行うことはできません。
• ピクチャインピクチャウィンドウの位置は、ウェブサイト側で設定することはできません。
• ピクチャインピクチャウィンドウは、ブラウザーのタブごとに一度に 1 つに制限されており、ユーザーエージェントによっては、開いているピクチャインピクチャウィンドウの総数がさらに制限される場合があります。

それ以外にも、ピクチャインピクチャ (PiP) ウィンドウの Window インスタンスを自由に操作できます。例えば、そこに表示したいコンテンツをその DOM に追加したり、スタイルシートをコピーして、追加されたコンテンツがメインウィンドウ内にあるときと同じようにスタイルが適用されるようにしたりできます。また、ピクチャインピクチャウィンドウを閉じ（ブラウザーが提供するコントロールをクリックするか、そのウィンドウに対して Window.close() を実行することで）、標準の pagehide イベントを使用して、ウィンドウが閉じられたことに反応することもできます。ウィンドウが閉じられた際は、そこに表示されていたコンテンツをメインのアプリウィンドウに戻す必要があります。

詳しい使用方法については、文書ピクチャインピクチャ API の使用をご覧ください。

インターフェイス

DocumentPictureInPicture

文書ピクチャインピクチャ (PIP) ウィンドウを作成および処理するためのエントリーポイント。

DocumentPictureInPictureEvent

ピクチャインピクチャウィンドウが開かれた際に発生する enter イベントのイベントオブジェクトです。

他インターフェイスへの拡張

Window.documentPictureInPicture

現在の文書コンテキストにおける DocumentPictureInPicture オブジェクトへの参照を返します。

CSS への追加

display-mode の picture-in-picture 値

CSS のメディア特性値で、ピクチャインピクチャモードで表示されているかどうかに応じて開発者が CSS を適用できるようにするためのものです。

例

実際に動作するデモについては、Document Picture-in-Picture API Example の例をご覧ください（ソースコードの全文も参照してください）。

仕様書

ブラウザーの互換性