運用 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 說明文件。