'תמונה בתוך תמונה' לכל רכיב, לא רק ל<סרטון>

François Beaufort

ממשק ה-API של תמונה בתוך תמונה במסמך מאפשר לפתוח חלון שתמיד מוצג בחזית, שאפשר לאכלס אותו בתוכן HTML שרירותי. הוא מרחיב את Picture-in-Picture API הקיים ל-<video> שמאפשר רק להציב רכיב HTML <video> בחלון Picture-in-Picture ‏ (PiP).

החלון של תמונה בתוך תמונה ב-Document Picture-in-Picture API דומה לחלון ריק מאותו מקור שנפתח באמצעות window.open(), אבל יש כמה הבדלים:

• החלון של 'תמונה בתוך תמונה' צף מעל חלונות אחרים.
• החלון של 'תמונה בתוך תמונה' אף פעם לא נסגר לפני החלון שממנו הוא נפתח.
• אי אפשר לנווט בחלון של מצב 'תמונה בתוך תמונה'.
• האתר לא יכול להגדיר את המיקום של חלון התמונה בתוך תמונה.

סטטוס

תרחישים לדוגמה

אפשר להשתמש ב-API הזה במגוון דרכים, כולל נגני וידאו בהתאמה אישית, שיחות ועידה בווידאו ואפליקציות פרודוקטיביות.

נגן וידאו בהתאמה אישית

אתר יכול לספק חוויית צפייה בסרטון במצב 'תמונה בתוך תמונה' באמצעות ה-API הקיים של 'תמונה בתוך תמונה' ל-<video>, אבל האפשרויות מוגבלות מאוד. חלון ה-PiP הקיים מקבל מעט קלט, והיכולת שלו לעיצוב מוגבלת. עם מסמך מלא במצב 'תמונה בתוך תמונה', האתר יכול לספק אמצעי בקרה וקלט בהתאמה אישית (לדוגמה, כתוביות, פלייליסטים, סרגל ניווט בזמן, סימון לייק או דיסלייק לסרטונים) כדי לשפר את חוויית הצפייה בסרטון במצב PiP.

שיחת ועידה בווידאו

במהלך שיחות ועידה בווידאו, משתמשים עוזבים לעיתים קרובות את כרטיסיית הדפדפן באופן זמני, למשל כשהם משתפים מסך מכרטיסייה אחרת בשיחה, כשהם רושמים הערות או כשהם מבצעים פעולות אחרות של ריבוי משימות. אבל ברוב המקרים המשתמש עדיין רוצה לראות את השיחה, ולכן זהו מקרה שימוש אידיאלי לתמונה בתוך תמונה. שוב, הממשק הנוכחי שאתר לשיחות ועידה בווידאו יכול לספק באמצעות Picture-in-Picture API ל-<video> מוגבל בסגנון ובקלט. כשמשתמשים במסמך מלא במצב 'תמונה בתוך תמונה', האתר יכול לשלב בקלות כמה שידורי וידאו בחלון PiP אחד, בלי להסתמך על פריצות ל-canvas, ולספק אמצעי בקרה מותאמים אישית, כמו שליחת הודעה, השתקת משתמש אחר או הרמת יד.

פרודוקטיביות

מחקרים הראו שהמשתמשים צריכים יותר דרכים להיות פרודוקטיביים באינטרנט. התכונה 'מסמך במצב תמונה בתוך תמונה' מאפשרת לאפליקציות אינטרנט לבצע יותר פעולות בצורה גמישה. בין אם מדובר בעריכת טקסט, בסיכום פגישות, ברשימות משימות, בהודעות ובצ'אט, או בכלי עיצוב ופיתוח, אפליקציות אינטרנט יכולות עכשיו לשמור על נגישות התוכן שלהן תמיד.

ממשק

מאפיינים

documentPictureInPicture.window

‫

מחזירה את חלון התמונה בתוך תמונה הנוכחי, אם יש כזה. אחרת, מוחזר הערך null.

Methods

documentPictureInPicture.requestWindow(options)

מחזירה הבטחה שמושלמת כשחלון של תמונה בתוך תמונה נפתח. ההבטחה נדחית אם היא נקראת ללא תנועת משתמש. המילון options מכיל את החברים האופציונליים הבאים:

width

הגדרה של הרוחב הראשוני של חלון התמונה בתוך תמונה.

height

הגדרת הגובה הראשוני של חלון התמונה בתוך תמונה.

disallowReturnToOpener

אם הערך הוא true, הכפתור 'חזרה לכרטיסייה' מוסתר בחלון של 'תמונה בתוך תמונה'. ברירת המחדל היא False.

preferInitialWindowPlacement

אם הערך הוא true, חלון התמונה בתוך תמונה ייפתח במיקום ובגודל ברירת המחדל שלו. ברירת המחדל היא False.

אירועים

documentPictureInPicture.onenter

‫

Fired on 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() מתבצעת כשמשתמש לוחץ על הלחצן כדי לפתוח חלון ריק של תמונה בתוך תמונה. אובייקט ה-promise שמוחזר נפתר באמצעות אובייקט 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,
  });
});

פתיחת חלון ה-PiP במיקום ובגודל ברירת המחדל

כדי לא להשתמש מחדש במיקום או בגודל של החלון הקודם של 'תמונה בתוך תמונה', מגדירים את האפשרות preferInitialWindowPlacement של documentPictureInPicture.requestWindow() לערך true.

pipButton.addEventListener("click", async () => {
  // Open a Picture-in-Picture window in its default position / size.
  const pipWindow = await documentPictureInPicture.requestWindow({
    preferInitialWindowPlacement: true,
  });
});

העתקת גיליונות סגנונות ל-PiP

כדי להעתיק את כל גיליונות הסגנונות של 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);
});

טיפול בסגירה של חלון ה-PiP

כדי לדעת מתי חלון התמונה בתוך תמונה נסגר (כי האתר יזם את הסגירה או שהמשתמש סגר אותו באופן ידני), צריך להאזין לאירוע "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 כדי לשנות את הגודל של החלון של 'תמונה בתוך תמונה'. שתי השיטות דורשות תנועת משתמש.

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 PiP

אפשר להשתמש במצב התצוגה 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, אפליקציית אינטרנט לשיטת פומודורו, משתמשת ב-Document Picture-in-Picture API כשהוא זמין. אפשר לראות את בקשת המיזוג ב-GitHub.

שיתוף משוב

דיווח על בעיות ב-GitHub עם הצעות ושאלות.

קישורים מועילים

• הסבר לציבור
• מפרט WICG
• באג למעקב ב-Chromium
• ערך ב-ChromeStatus.com
• רכיב Blink: ‏ Blink>Media>PictureInPicture
• TAG Review
• הבעת עניין בהשתתפות בניסוי
• כוונה לשלוח