Picture-in-Picture API

介面

PictureInPictureWindow

表示浮動的影片視窗；包含 width 和 height 屬性，以及一個 onresize 事件處理程式屬性。

PictureInPictureEvent

表示與畫中畫相關的事件，包括 enterpictureinpicture、leavepictureinpicture 和 resize。

例項方法

畫中畫 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 屬性告訴您當前在浮動視窗（或 shadow DOM）中顯示的 Element 是什麼。如果此值為 null，則文件（或 shadow DOM）當前沒有節點處於畫中畫模式。

事件

畫中畫 API 定義了三個事件，可用於檢測畫中畫模式何時被切換以及浮動影片視窗何時被調整大小。

enterpictureinpicture

當 HTMLVideoElement 進入畫中畫模式時傳送。

leavepictureinpicture

當 HTMLVideoElement 離開畫中畫模式時傳送。

resize

當 PictureInPictureWindow 更改大小時傳送。

新增控制元件

如果透過 媒體會話 API 設定了媒體操作處理程式，則瀏覽器會將這些操作的相應控制元件新增到畫中畫疊加層。例如，如果設定了 "nexttrack" 操作，則可能會在畫中畫檢視中顯示一個跳過按鈕。不支援新增自定義 HTML 按鈕或控制元件。

控制樣式

:picture-in-picture CSS 偽類匹配當前處於畫中畫模式的影片元素，允許您配置樣式表，以便在影片在畫中畫和傳統顯示模式之間切換時自動調整內容的大小、樣式或佈局。

控制訪問

可以使用 許可權策略控制畫中畫模式的可用性。畫中畫模式功能由字串 "picture-in-picture" 標識，預設允許列表值為 *，這意味著在頂層文件上下文中以及與頂層文件同源的巢狀瀏覽上下文中都允許畫中畫模式。

示例

切換畫中畫模式

在此示例中，我們在網頁中有一個 <video> 元素、一個用於切換畫中畫的 <button>，以及一個用於記錄示例相關資訊的元素。<button> 元素在確定瀏覽器支援之前，最初是 disabled 的。

<video
  src="/shared-assets/videos/friday.mp4"
  id="video"
  muted
  controls
  loop
  width="300"></video>

<button id="pip-button" disabled>Toggle PiP</button>
<pre id="log"></pre>

body {
  font:
    14px "Open Sans",
    sans-serif;
  padding: 0.5em;
}

button {
  display: block;
  margin-block: 1rem;
}

我們首先使用 document.pictureInPictureEnabled 檢查瀏覽器是否支援 PiP，如果不支援，我們將該資訊記錄到 <pre> 元素中。如果瀏覽器支援，我們就可以啟用切換來進入和退出 PiP。

對於控制元件，對 <button> 元素上的事件偵聽器會呼叫我們定義的 togglePictureInPicture() 函式。在 togglePictureInPicture() 中，一個 if 語句會檢查 document 的 pictureInPictureElement 屬性的值。

• 如果值為 null，則沒有影片在浮動視窗中，因此我們可以請求影片進入畫中畫模式。我們透過在 <video> 元素上呼叫 HTMLVideoElement.requestPictureInPicture() 來實現這一點。
• 如果值不是 null，則表示當前有一個元素處於畫中畫模式。然後，我們可以呼叫 document.exitPictureInPicture() 將影片恢復到其初始框中，從而退出畫中畫模式。

const video = document.getElementById("video");
const pipButton = document.getElementById("pip-button");
const log = document.getElementById("log");

if (document.pictureInPictureEnabled) {
  pipButton.removeAttribute("disabled");
} else {
  log.innerText = "PiP not supported. Check browser compatibility for details.";
}

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

pipButton.addEventListener("click", togglePictureInPicture);

:picture-in-picture {
  outline: 5px dashed green;
}

單擊“切換 PiP”按鈕可讓使用者在頁面內播放影片和在浮動視窗中播放影片之間切換

規範

瀏覽器相容性

另見

• HTMLVideoElement.requestPictureInPicture()
• HTMLVideoElement.disablePictureInPicture
• Document.pictureInPictureEnabled
• Document.exitPictureInPicture()
• Document.pictureInPictureElement
• :picture-in-picture
• 文件畫中畫 API