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

Jad Joubran

發布日期：2025 年 3 月 4 日

文件子母畫面 API (文件 PiP API) 可讓網路應用程式開啟浮動的置頂視窗 (子母畫面視窗)，顯示任意 HTML 內容。

這個 API 是以 <video>的子母畫面 API 為基礎建構而成，可讓您在子母畫面視窗中繼續觀看影片。

由於 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 呼叫，或從依附於 Document PiP 的函式提早傳回。下列程式碼會檢查是否支援 Document PiP，然後開啟 Document 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。

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

備用

請注意，這項 API 的適用範圍有限。在不支援這項 API 的瀏覽器和裝置上，您必須提供備援 (正常降級) 行為。

我們不必讓最大化按鈕拉出整個瀏覽器預覽分頁，而是讓它占滿目前網頁應用程式的所有剩餘空間。

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

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

如您所見，Document Picture-in-Picture API 搭配漸進增強或優雅降級功能，可為網頁應用程式解鎖令人期待的新用途。

不要讓瀏覽器支援限制成為阻礙，也別忘了要有適當的回退使用情境。

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