Document Picture-in-Picture API 就會開啟螢幕長亮視窗,在其中填入任意 HTML 內容。它擴充了現有的 <video>
的子母畫面 API,允許將 HTML <video>
元素放入子母畫面視窗。
Document Picture-in-Picture API 中的子母畫面視窗與透過 window.open()
開啟的空白相同來源視窗類似,但有一些差異:
- 子母畫面視窗懸浮在其他視窗上方。
- 子母畫面視窗永遠不會超過開啟視窗。
- 無法瀏覽子母畫面視窗。
- 網站無法設定子母畫面視窗位置。
![播放 Sintel 預告片的子母畫面視窗。](https://developer.chrome.google.cn/static/docs/web-platform/document-picture-in-picture/image/a-picture-picture-window-a75f117724132.png?authuser=19&hl=zh-tw)
目前狀態
步驟 | 狀態 |
---|---|
1. 建立說明 | 完成 |
2. 建立規格的初始草稿 | 進行中 |
3. 收集意見回饋與在設計上反覆測試 | 進行中 |
4. 來源試用 | 完成 |
5. 啟動 | 完成 (電腦) |
用途
自訂影片播放器
網站可以使用現有的 <video>
的子母畫面 API,提供子母畫面影片體驗,但相當有限。現有的子母畫面視窗接受幾項輸入內容,但樣式功能有限。透過網站提供完整的子母畫面功能,網站可提供自訂控制選項和輸入內容 (例如字幕、播放清單、時間進度控制鈕、對影片按讚和按倒讚),藉此改善使用者的子母畫面影片體驗。
視訊會議
使用者在視訊會議過程中,經常會基於各種原因 (例如,在通話期間使用其他分頁或進行多工處理) 離開瀏覽器分頁,但仍然希望看到通話,因此最適合使用子母畫面功能。再次提醒,目前的視訊會議網站可透過 <video>
的 Picture-in-Picture API 提供可用的風格和輸入內容,透過子母畫面功能的完整文件,網站可以將多個影片串流輕鬆合併為單一子母畫面視窗,不必依賴 Canvas 駭客,同時提供自訂控制選項,例如傳送訊息、將其他使用者設為靜音或舉手。
效率提升
研究顯示,使用者需要更多方法,才能在網路上維持工作效率。子母畫面中的文件可靈活地透過網頁應用程式完成更多工作。無論是文字編輯、記事、工作清單、訊息與即時通訊,還是設計與開發工具,網頁應用程式現在都能隨時存取內容。
介面
屬性
documentPictureInPicture.window
- 傳回目前的子母畫面視窗 (如有)。否則,則會傳回
null
。
方法
documentPictureInPicture.requestWindow(options)
傳回在開啟子母畫面視窗時解析的承諾。 如果呼叫這個方法時沒有使用者手勢,承諾會遭到拒絕。
options
字典包含下列成員:width
- 設定子母畫面視窗的初始寬度。
height
- 設定子母畫面視窗的初始高度。
disallowReturnToOpener
- 隱藏「返回分頁」按鈕。此屬性預設為 false。
活動
documentPictureInPicture.onenter
- 在
documentPictureInPicture
開啟子母畫面視窗時觸發。
範例
下列 HTML 會設定自訂影片播放器和按鈕元素,用於在子母畫面視窗中開啟影片播放器。
<div id="playerContainer">
<div id="player">
<video id="video"></video>
</div>
</div>
<button id="pipButton">Open Picture-in-Picture window</button>
開啟子母畫面視窗
下列 JavaScript 會在使用者點選按鈕開啟空白的子母畫面視窗時呼叫 documentPictureInPicture.requestWindow()
。傳回的承諾會使用子母畫面視窗 JavaScript 物件解析。系統會使用 append()
將影片播放器移至該視窗。
pipButton.addEventListener('click', async () => {
const player = document.querySelector("#player");
// Open a Picture-in-Picture window.
const pipWindow = await documentPictureInPicture.requestWindow();
// Move the player to the Picture-in-Picture window.
pipWindow.document.body.append(player);
});
設定子母畫面視窗的大小
如要設定子母畫面視窗的大小,請將 documentPictureInPicture.requestWindow()
的 width
和 height
選項設為所需的子母畫面視窗大小。如果選項值太大或太小,導致 Chrome 無法容納視窗的大小,就可能會限制選項值。
pipButton.addEventListener("click", async () => {
const player = document.querySelector("#player");
// Open a Picture-in-Picture window whose size is
// the same as the player's.
const pipWindow = await documentPictureInPicture.requestWindow({
width: player.clientWidth,
height: player.clientHeight,
});
// Move the player to the Picture-in-Picture window.
pipWindow.document.body.append(player);
});
隱藏「返回分頁」子母畫面視窗的按鈕
如要在子母畫面視窗中隱藏按鈕,方便使用者返回開啟分頁,請將 documentPictureInPicture.requestWindow()
的 disallowReturnToOpener
選項設為 true
。
pipButton.addEventListener("click", async () => {
// Open a Picture-in-Picture window which hides the "back to tab" button.
const pipWindow = await documentPictureInPicture.requestWindow({
disallowReturnToOpener: true,
});
});
將樣式表複製到子母畫面視窗
如要從原始視窗複製所有 CSS 樣式表,請透過明確連結或嵌入文件中 styleSheets
的方式迴圈,然後將這些項目附加到子母畫面視窗。請注意,此為一次性副本。
pipButton.addEventListener("click", async () => {
const player = document.querySelector("#player");
// Open a Picture-in-Picture window.
const pipWindow = await documentPictureInPicture.requestWindow();
// Copy style sheets over from the initial document
// so that the player looks the same.
[...document.styleSheets].forEach((styleSheet) => {
try {
const cssRules = [...styleSheet.cssRules].map((rule) => rule.cssText).join('');
const style = document.createElement('style');
style.textContent = cssRules;
pipWindow.document.head.appendChild(style);
} catch (e) {
const link = document.createElement('link');
link.rel = 'stylesheet';
link.type = styleSheet.type;
link.media = styleSheet.media;
link.href = styleSheet.href;
pipWindow.document.head.appendChild(link);
}
});
// Move the player to the Picture-in-Picture window.
pipWindow.document.body.append(player);
});
子母畫面視窗關閉時的處理方式
監聽視窗 "pagehide"
事件,瞭解子母畫面視窗何時關閉 (原因可能是網站已啟動該視窗,或使用者手動關閉)。事件處理常式非常適合用來從子母畫面視窗移除元素,如下所示。
pipButton.addEventListener("click", async () => {
const player = document.querySelector("#player");
// Open a Picture-in-Picture window.
const pipWindow = await documentPictureInPicture.requestWindow();
// Move the player to the Picture-in-Picture window.
pipWindow.document.body.append(player);
// Move the player back when the Picture-in-Picture window closes.
pipWindow.addEventListener("pagehide", (event) => {
const playerContainer = document.querySelector("#playerContainer");
const pipPlayer = event.target.querySelector("#player");
playerContainer.append(pipPlayer);
});
});
使用 close()
方法,以程式輔助方式關閉子母畫面視窗。
// Close the Picture-in-Picture window programmatically.
// The "pagehide" event will fire normally.
pipWindow.close();
監聽網站何時進入子母畫面
監聽 documentPictureInPicture
的 "enter"
事件,瞭解子母畫面視窗的開啟時間。這個事件包含 window
物件,用於存取子母畫面視窗。
documentPictureInPicture.addEventListener("enter", (event) => {
const pipWindow = event.window;
});
存取子母畫面視窗中的元素
透過 documentPictureInPicture.requestWindow()
傳回的物件或 documentPictureInPicture.window
存取子母畫面視窗中的元素,如下所示。
const pipWindow = documentPictureInPicture.window;
if (pipWindow) {
// Mute video playing in the Picture-in-Picture window.
const pipVideo = pipWindow.document.querySelector("#video");
pipVideo.muted = true;
}
處理子母畫面視窗中的事件
建立按鈕和控制項,並回應使用者的輸入事件 (例如 "click"
),做法與在 JavaScript 中一樣。
// Add a "mute" button to the Picture-in-Picture window.
const pipMuteButton = pipWindow.document.createElement("button");
pipMuteButton.textContent = "Mute";
pipMuteButton.addEventListener("click", () => {
const pipVideo = pipWindow.document.querySelector("#video");
pipVideo.muted = true;
});
pipWindow.document.body.append(pipMuteButton);
調整子母畫面視窗大小
使用 resizeBy()
和 resizeTo()
視窗方法調整子母畫面視窗的大小。這兩種方法都需要使用者手勢。
const resizeButton = pipWindow.document.createElement('button');
resizeButton.textContent = 'Resize';
resizeButton.addEventListener('click', () => {
// Expand the Picture-in-Picture window's width by 20px and height by 30px.
pipWindow.resizeBy(20, 30);
});
pipWindow.document.body.append(resizeButton);
將焦點移至開啟的視窗
使用 focus()
視窗方法,將焦點從子母畫面視窗聚焦。這個方法需要使用者做出手勢。
const returnToTabButton = pipWindow.document.createElement("button");
returnToTabButton.textContent = "Return to opener tab";
returnToTabButton.addEventListener("click", () => {
window.focus();
});
pipWindow.document.body.append(returnToTabButton);
CSS 子母畫面顯示模式
使用 CSS picture-in-picture
顯示模式編寫特定的 CSS 規則,只有在網頁應用程式以子母畫面模式顯示時,才會套用這些規則 (其中的一部分)。
@media all and (display-mode: picture-in-picture) {
body {
margin: 0;
}
h1 {
font-size: 0.8em;
}
}
特徵偵測
如要檢查系統是否支援 Document Picture-in-Picture API,請使用以下工具:
if ('documentPictureInPicture' in window) {
// The Document Picture-in-Picture API is supported.
}
示範
VideoJS 播放器
如要暢玩 Document Picture-in-Picture API,即可享受 VideoJS 播放器示範影片。請務必查看原始碼。
波莫多羅
Tomodoro 是 Pomodoro 網頁應用程式,在可用的情況下,也會利用 Document Picture-in-Picture API (請參閱 GitHub 提取要求)。
![Tomodoro 是知名的網頁應用程式 Tomodoro。](https://developer.chrome.google.cn/static/docs/web-platform/document-picture-in-picture/image/screenshot-tomodoro-po-6e0b39f6f0b17.png?authuser=19&hl=zh-tw)
意見回饋
歡迎前往 GitHub 回報問題,並提供建議和問題。
實用連結
特別銘謝
主頁橫幅由 Jakob Owens。