Document Picture-in-Picture API ช่วยให้คุณเปิดหน้าต่างแบบเปิดตลอดเวลาที่มีเนื้อหา HTML ที่กำหนดเองได้ โดยจะขยาย API การแสดงภาพซ้อนภาพสำหรับ <video>
ที่มีอยู่ ซึ่งอนุญาตให้ใส่เฉพาะองค์ประกอบ HTML <video>
ในหน้าต่างการแสดงภาพซ้อนภาพเท่านั้น
หน้าต่างการแสดงภาพซ้อนภาพใน Document Picture-in-Picture API จะคล้ายกับหน้าต่างต้นทางเดียวกันที่ว่างเปล่าซึ่งเปิดผ่าน window.open()
โดยมีความแตกต่างบางอย่างดังนี้
- หน้าต่างการแสดงภาพซ้อนภาพลอยอยู่เหนือหน้าต่างอื่นๆ
- หน้าต่างการแสดงภาพซ้อนภาพจะไม่มีอายุการใช้งานนานกว่าหน้าต่างที่เปิดอยู่
- ไม่สามารถไปยังส่วนต่างๆ ของหน้าต่างการแสดงภาพซ้อนภาพ
- เว็บไซต์ไม่สามารถกำหนดตำแหน่งหน้าต่างการแสดงภาพซ้อนภาพ
![หน้าต่างการแสดงภาพซ้อนภาพที่กำลังเล่นวิดีโอตัวอย่างของ Sintel](https://developer.chrome.com/static/docs/web-platform/document-picture-in-picture/image/a-picture-picture-window-a75f117724132.png?authuser=19&hl=th)
สถานะปัจจุบัน
ขั้นตอน | สถานะ |
---|---|
1. สร้างคำอธิบาย | เสร็จสมบูรณ์ |
2. สร้างข้อกำหนดคร่าวๆ เบื้องต้น | กำลังดำเนินการ |
3. รวบรวมความคิดเห็นและ ทำซ้ำในการออกแบบ | กำลังดำเนินการ |
4. ช่วงทดลองใช้จากต้นทาง | เสร็จสมบูรณ์ |
5. เปิดตัว | เสร็จสมบูรณ์ (เดสก์ท็อป) |
กรณีการใช้งาน
วิดีโอเพลเยอร์ที่กำหนดเอง
เว็บไซต์สามารถมอบประสบการณ์การใช้งานวิดีโอการแสดงภาพซ้อนภาพได้ด้วย Picture-in-Picture API สำหรับ <video>
ที่มีอยู่แล้ว แต่ข้อจํากัดอย่างมาก หน้าต่างการแสดงภาพซ้อนภาพที่มีอยู่จะยอมรับอินพุตไม่กี่รายการ และสามารถจัดรูปแบบอินพุตเหล่านี้ได้ เมื่อเว็บไซต์มีเอกสารแบบการแสดงภาพซ้อนภาพฉบับสมบูรณ์ เว็บไซต์จึงมีการควบคุมและการป้อนข้อมูลแบบกำหนดเอง (เช่น คำบรรยายวิดีโอ เพลย์ลิสต์ ตัวควบคุมเวลา การกดชอบ และการกดไม่ชอบวิดีโอ) เพื่อปรับปรุงประสบการณ์การใช้งานวิดีโอการแสดงภาพซ้อนภาพของผู้ใช้
การประชุมทางวิดีโอ
ผู้ใช้อาจออกจากแท็บเบราว์เซอร์ในระหว่างเซสชันการประชุมทางวิดีโอด้วยเหตุผลหลายประการ (เช่น การนำเสนอแท็บอื่นไปยังการโทรหรือการทำงานหลายอย่างพร้อมกัน) ในขณะที่ยังต้องการดูการโทรจึงเป็นกรณีการใช้งานที่เหมาะสมสำหรับการแสดงภาพซ้อนภาพ ขอย้ำอีกครั้งว่าประสบการณ์ในปัจจุบันที่เว็บไซต์การประชุมทางวิดีโอสามารถให้บริการผ่าน Picture-in-Picture API สำหรับ <video>
ได้นั้นมีการจำกัดรูปแบบและการป้อนข้อมูล เว็บไซต์สามารถรวมสตรีมวิดีโอหลายรายการไว้ในหน้าต่าง PIP เดียวได้อย่างง่ายดายโดยไม่ต้องอาศัยการแฮ็ก Canvas และมอบการควบคุมที่กำหนดเอง เช่น การส่งข้อความ การปิดเสียงผู้ใช้รายอื่น หรือการยกมือ เมื่อมีเอกสารแบบภาพซ้อนภาพฉบับเต็ม
ประสิทธิภาพการทำงาน
งานวิจัยแสดงให้เห็นว่าผู้ใช้ต้องการวิธีใหม่ๆ ในการทำงานบนเว็บ เอกสารในการแสดงภาพซ้อนภาพช่วยให้เว็บแอปทำงานได้มากขึ้นอย่างยืดหยุ่น ไม่ว่าจะเป็นการแก้ไขข้อความ การจดโน้ต รายการงาน การรับส่งข้อความและแชท หรือเครื่องมือออกแบบและพัฒนาเว็บแอป ก็ช่วยให้เข้าถึงเนื้อหาได้ตลอดเวลา
SDK โฆษณา B
พร็อพเพอร์ตี้
documentPictureInPicture.window
- แสดงผลหน้าต่างการแสดงภาพซ้อนภาพปัจจุบัน หากมี ในกรณีอื่น ระบบจะแสดงผล
null
เมธอด
documentPictureInPicture.requestWindow(options)
แสดงสัญญาที่แก้ไขเมื่อหน้าต่างการแสดงภาพซ้อนภาพเปิดขึ้น คำสัญญาจะปฏิเสธหากระบบเรียกใช้โดยไม่ใช้การกระทำของผู้ใช้ พจนานุกรม
options
มีสมาชิกที่ไม่บังคับต่อไปนี้width
- ตั้งค่าความกว้างเริ่มต้นของหน้าต่างการแสดงภาพซ้อนภาพ
height
- ตั้งค่าความสูงเริ่มต้นของหน้าต่างการแสดงภาพซ้อนภาพ
disallowReturnToOpener
- ซ่อน "กลับไปที่แท็บ" ในหน้าต่างการแสดงภาพซ้อนภาพ หากเป็นจริง โดยค่าเริ่มต้น ค่านี้จะเป็นเท็จ
กิจกรรม
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);
});
กำหนดขนาดของหน้าต่างการแสดงภาพซ้อนภาพ
หากต้องการกำหนดขนาดของหน้าต่างการแสดงภาพซ้อนภาพ ให้ตั้งค่าตัวเลือก width
และ height
ของ documentPictureInPicture.requestWindow()
เป็นขนาดหน้าต่างการแสดงภาพซ้อนภาพที่ต้องการ 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);
});
ซ่อน "กลับไปที่แท็บ" ปุ่มของหน้าต่างการแสดงภาพซ้อนภาพ
หากต้องการซ่อนปุ่มในหน้าต่างการแสดงภาพซ้อนภาพเพื่อให้ผู้ใช้กลับไปยังแท็บเครื่องมือเปิด ให้ตั้งค่าตัวเลือก disallowReturnToOpener
เป็น documentPictureInPicture.requestWindow()
เป็น 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();
ฟังเมื่อเว็บไซต์เข้าสู่การแสดงภาพซ้อนภาพ
ฟังเหตุการณ์ "enter"
ในวันที่ documentPictureInPicture
เพื่อให้ทราบเมื่อหน้าต่างการแสดงภาพซ้อนภาพเปิดอยู่ เหตุการณ์มีออบเจ็กต์ 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()
เมธอด Windows เพื่อปรับขนาดหน้าต่างการแสดงภาพซ้อนภาพ ทั้ง 2 วิธีต้องใช้ท่าทางสัมผัสของผู้ใช้
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
ใช้โหมดการแสดงผล picture-in-picture
ของ CSS เพื่อเขียนกฎ 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 เว็บแอป Pomodoro](https://developer.chrome.com/static/docs/web-platform/document-picture-in-picture/image/screenshot-tomodoro-po-6e0b39f6f0b17.png?authuser=19&hl=th)
ความคิดเห็น
โปรดยื่นปัญหาเกี่ยวกับ GitHub พร้อมคำแนะนำและคำถาม
ลิงก์ที่มีประโยชน์
- คำอธิบายแบบสาธารณะ
- ข้อกำหนด WICG
- ข้อบกพร่องในการติดตาม Chromium
- รายการ ChromeStatus.com
- คอมโพเนนต์กะพริบ:
Blink>Media>PictureInPicture
- ตรวจสอบแท็ก
- ความตั้งใจในการทดสอบ
- ความตั้งใจที่จะจัดส่ง
กิตติกรรมประกาศ
รูปภาพหลักโดย Jakob Owens