文件畫中畫 API

可用性有限

此特性不是基線特性，因為它在一些最廣泛使用的瀏覽器中不起作用。

實驗性： 這是一項實驗性技術
在生產中使用此技術之前，請仔細檢查瀏覽器相容性表格。

安全上下文： 此功能僅在安全上下文（HTTPS）中可用，且支援此功能的瀏覽器數量有限。

文件畫中畫 API 使得能夠開啟一個始終置頂的視窗，該視窗可以填充任意 HTML 內容 — 例如帶有自定義控制元件的影片，或顯示視訊會議參與者的一組流。它擴充套件了早期的 <video> 的畫中畫 API，該 API 特別允許將 HTML <video> 元素放入一個始終置頂的視窗。

概念與用法

對於 Web 應用來說，除了應用執行的主視窗之外，還有一個不同的視窗供其使用通常很有幫助。你可能想在檢視其他視窗的同時保持特定應用內容可見，或者你可能想為該內容提供自己的空間，同時讓主應用視窗保持空閒以顯示其他內容。你可以透過開啟一個常規的新瀏覽器視窗來處理這個問題，但這有兩個主要問題：

你必須處理兩個視窗之間狀態資訊的共享。
附加的應用視窗不會始終置頂，因此可能被其他視窗隱藏。

為了解決這些問題，Web 瀏覽器引入了 API，允許應用生成一個屬於同一會話的始終置頂視窗。第一個公認的用例是讓影片內容在單獨的視窗中播放，以便使用者在檢視其他內容時可以繼續觀看。這可以透過 <video> 的畫中畫 API 來處理，該 API 直接應用於 <video> 元素，將其放入單獨的視窗中。

然而，這個 API 被發現有些侷限 — 你只能將單個 <video> 元素放入始終置頂的視窗中，並且只有最小的瀏覽器生成的控制元件。為了提供更大的靈活性，引入了文件畫中畫 API。這允許將任何內容放入始終置頂的視窗中，適用於廣泛的用例，包括：

一個始終置頂的自定義影片播放器，顯示一個或多個帶有自定義控制元件和樣式的影片。
一個視訊會議系統，允許使用者始終看到其他參與者的流，以及用於演示內容、靜音、結束通話等的控制元件。
始終可見的生產力工具，如計時器、筆記、待辦事項列表、即時訊息工具等。
一個單獨的視窗，用於存放附加內容，同時保持主應用視窗整潔。例如，你可能正在執行一個動作或角色扮演遊戲，你想在附加視窗中顯示遊戲控制元件、說明或背景故事，讓主視窗保持空閒以顯示遊戲地點和地圖。

透過 Window.documentPictureInPicture 可訪問一個代表當前文件上下文的始終置頂畫中畫視窗的新 DocumentPictureInPicture 物件例項。透過呼叫 DocumentPictureInPicture.requestWindow() 方法開啟畫中畫視窗，該方法返回一個 Promise，該 Promise 會解析為視窗自身的 Window 物件。

畫中畫視窗類似於透過 Window.open() 開啟的空白同源視窗，但有一些區別：

畫中畫視窗浮動在其他視窗的上方。
畫中畫視窗的生命週期不會超過開啟它的視窗。
畫中畫視窗無法導航。
網站無法設定畫中畫視窗的位置。
一個瀏覽器標籤頁一次最多隻能有一個畫中畫視窗，使用者代理可能會進一步限制開啟的畫中畫視窗的總數。

除此之外，你可以隨意操作畫中畫視窗的 Window 例項，例如將你想要顯示的內容追加到其 DOM 中，並將樣式表複製到其中，以便追加的內容與在主視窗中的樣式相同。你也可以關閉畫中畫視窗（透過點選瀏覽器提供的控制元件，或在上面執行 Window.close()），然後使用標準的 pagehide 事件對關閉做出響應。當它關閉時，你需要將它顯示的內容放回主應用視窗。

有關詳細的使用指南，請參閱使用文件畫中畫 API。