運用 Document Picture-in-Picture API 發揮令人期待的用途

Jad Joubran

發布日期：2025 年 3 月 4 日

Document Picture-in-Picture API (Document PiP API) 可讓網頁應用程式開啟浮動式、一律置頂的視窗 (子母畫面視窗)，用於顯示任何 HTML 內容。

這個 API 是 <video> 的 Picture-in-Picture API 的基礎，可讓您繼續在 PiP 視窗中觀看影片。

由於 Document PiP API 可顯示任何任意 HTML 內容，因此您可以利用這項 API 開發令人興奮的新用途。

瀏覽器支援和漸進式改善

在撰寫本文時，Document Picture-in-Picture API 的使用範圍有限。

不過，這不應阻止您使用漸進式增強或優雅降級。

規劃用途時，請務必將其視為漸進式增強功能，而非標準功能。本文將說明優雅降級的範例。

使用 Document PiP API 改善學習者的使用者體驗

LearnHTMLCSS.online 是互動式學習平台，可教導語意和無障礙的 HTML 和 CSS。這項工具提供互動式文字編輯器和瀏覽器預覽視窗。

下列螢幕錄影畫面顯示應用程式的版面配置，畫面分為兩欄。第一個欄包含程式碼編輯器。第二欄包含分頁版面配置。根據預設，使用者可以查看挑戰說明，並點選「瀏覽器」分頁標籤查看即時預覽畫面。

有時您可能會想將瀏覽器預覽視窗設為最大化。這是新增支援 Document Picture-in-Picture API 的絕佳時機。

如要實作這項功能，請先檢查瀏覽器支援情形：

const isPipSupported = "documentPictureInPicture" in window;

您現在可以使用這個變數包裝任何 documentPictureInPicture 呼叫，或從依賴文件 PiP 的函式中提早傳回。下列程式碼會檢查是否支援文件 PiP，然後開啟文件 PiP 視窗。

async function initDocumentPip() {
  if (!isPipSupported) {
    return false;
  }

  const pipWindow = await documentPictureInPicture.requestWindow({
    width: window.innerWidth,
    height: window.innerHeight,
  });
}

視用途而定，您可以為視窗指定任意寬度和高度。您可以嘗試比對特定元素、目前文件，甚至提供固定值。

目前您有空白文件。您現在需要填入內容。

// htmlCode is the HTML code of the challenge
pipWindow.document.documentElement.innerHTML = htmlCode;

如有 CSS 程式碼相關問題，你也需要同步 CSS。

大功告成！你現在可以使用最大化按鈕在獨立的 PiP 視窗中開啟瀏覽器預覽分頁。除了將瀏覽器預覽分頁設為最大化，你還可以將其移至獨立的螢幕 (如果有外接螢幕)，甚至在直欄版面配置中重新排列主要網頁應用程式和瀏覽器預覽分頁。

備用

請注意，這個 API 的供應情形有限。在瀏覽器和不支援此 API 的裝置上，您需要提供備用 (優雅降級) 行為。

我們可以讓最大化按鈕占用目前網頁應用程式中的所有剩餘空間，而非將整個瀏覽器預覽分頁拉出。

請在不同瀏覽器中試試這個行為：https://learnhtmlcss.online/app.html?id=2096

別忘了留意工具提示中的細節。當 isPipSupported 為 true 時，最大化/最小化按鈕的工具提示會在「進入子母畫面」和「退出子母畫面」之間切換。另一方面，如果 isPipSupported 為 false，則備用行為會以 Maximize 和 Minimize 說明。

如您所見，當 Picture-in-Picture API 與漸進式增強或漸進式降級搭配使用時，就能為您的網頁應用程式帶來令人振奮的新用途。

不要讓有限的瀏覽器支援功能限制您，也別忘了提供適當的備用用途。

請參閱 Document PiP 說明文件，瞭解這個 API 的各種範例和用途。