หน้านี้ได้รับการแปลโดย Cloud Translation API

การแสดงภาพซ้อนภาพสำหรับองค์ประกอบใดๆ ไม่ใช่แค่ <วิดีโอ>

François Beaufort

การสนับสนุนเบราว์เซอร์

Document Picture-in-Picture API ทำให้สามารถเปิดหน้าต่างด้านบนตลอดเวลาซึ่งสามารถเติมเนื้อหา HTML ที่กำหนดเองได้ ซึ่งจะขยาย Picture-in-Picture API สำหรับ <video> ที่มีอยู่ซึ่งอนุญาตให้เพิ่มองค์ประกอบ HTML <video> ลงในหน้าต่างการแสดงภาพซ้อนภาพเท่านั้น

หน้าต่าง Picture-in-Picture ใน Document Picture-in-Picture API จะคล้ายกับหน้าต่างต้นทางเดียวกันที่ว่างเปล่าซึ่งเปิดผ่าน window.open() โดยมีความแตกต่างบางอย่างดังนี้

หน้าต่างการแสดงภาพซ้อนภาพจะลอยอยู่ด้านบนหน้าต่างอื่นๆ
หน้าต่างการแสดงภาพซ้อนภาพจะไม่กินพื้นที่หน้าต่างที่เปิดอยู่
ไม่สามารถนำทางหน้าต่างการแสดงภาพซ้อนภาพได้
เว็บไซต์ไม่สามารถกำหนดตำแหน่งหน้าต่างการแสดงภาพซ้อนภาพได้

หน้าต่างการแสดงภาพซ้อนภาพกำลังเล่นวิดีโอตัวอย่างของ Sintel — หน้าต่างการแสดงภาพซ้อนภาพที่สร้างด้วย Document Picture-in-Picture API (การสาธิต)

สถานะปัจจุบัน

ขั้นตอน	สถานะ
1. สร้างข้อความอธิบาย	เสร็จสมบูรณ์
2. สร้างฉบับร่างเริ่มต้นของข้อกำหนด	กำลังดำเนินการ
3. รวบรวมความคิดเห็นและทำซ้ำเกี่ยวกับการออกแบบ	กำลังดำเนินการ
4. ช่วงทดลองใช้จากต้นทาง	เสร็จสมบูรณ์
5. เปิดตัว	เสร็จสมบูรณ์ (เดสก์ท็อป)

Use Case

วิดีโอเพลเยอร์ที่กำหนดเอง

เว็บไซต์สามารถให้บริการวิดีโอการแสดงภาพซ้อนภาพด้วย 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);
});

หมายเหตุ: ข้อกำหนดเวอร์ชันก่อนหน้ารองรับตัวเลือก copyStyleSheets จึงไม่เป็นเช่นนั้นแล้ว

แฮนเดิลเมื่อปิดหน้าต่างการแสดงภาพซ้อนภาพ

ฟังเหตุการณ์หน้าต่าง "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() Window เพื่อปรับขนาดหน้าต่างการแสดงภาพซ้อนภาพ ทั้ง 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() Window เพื่อโฟกัสหน้าต่างที่เปิดจากหน้าต่างการแสดงภาพซ้อนภาพ วิธีนี้ต้องใช้ท่าทางสัมผัสของผู้ใช้

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 ซึ่งเป็นเว็บแอป Pomodoro — หน้าต่างการแสดงภาพซ้อนภาพใน Tomodoro

ความคิดเห็น

โปรดแจ้งปัญหาบน GitHub พร้อมคำแนะนำและคำถาม

ลิงก์ที่มีประโยชน์

คำอธิบายแบบสาธารณะ
ข้อกำหนดของ WICG
ข้อบกพร่องในการติดตาม Chromium
รายการ ChromeStatus.com
คอมโพเนนต์การกะพริบ: Blink>Media>PictureInPicture
ตรวจสอบแท็ก
ความตั้งใจในการทดสอบ
ตั้งใจที่จะจัดส่ง

ข้อความแสดงการยอมรับ

รูปภาพหลักของ Jakob Owens