تصویر در تصویر برای هر عنصر، نه فقط <ویدئو>

François Beaufort

API تصویر در تصویر سند، امکان باز کردن یک پنجره همیشه در بالا را فراهم می‌کند که می‌تواند با محتوای HTML دلخواه پر شود. این API تصویر در تصویر موجود برای <video> را گسترش می‌دهد که فقط اجازه می‌دهد یک عنصر <video> HTML در یک پنجره تصویر در تصویر (PiP) قرار گیرد.

پنجره تصویر در تصویر در API تصویر در سند، مشابه یک پنجره خالی با همان مبدأ است که با استفاده از window.open() باز می‌شود، با برخی تفاوت‌ها:

• پنجره تصویر در تصویر روی پنجره‌های دیگر شناور است.
• پنجره تصویر در تصویر هرگز بیشتر از پنجره باز شده عمر نمی‌کند.
• پنجره تصویر در تصویر قابل پیمایش نیست.
• موقعیت پنجره تصویر در تصویر را نمی‌توان توسط وب‌سایت تنظیم کرد.

وضعیت

موارد استفاده

شما می‌توانید از این API به روش‌های مختلفی استفاده کنید، از جمله پخش‌کننده‌های ویدیوی سفارشی، کنفرانس ویدیویی و برنامه‌های بهره‌وری.

پخش کننده ویدیوی سفارشی

یک وب‌سایت می‌تواند با استفاده از API تصویر در تصویر موجود برای <video> ، تجربه ویدیوی تصویر در تصویر را ارائه دهد، اما این API بسیار محدود است. پنجره PiP موجود ورودی‌های کمی را می‌پذیرد و توانایی محدودی برای استایل‌بندی آنها دارد. با یک سند کامل در تصویر در تصویر، وب‌سایت می‌تواند کنترل‌ها و ورودی‌های سفارشی (به عنوان مثال، زیرنویس‌ها ، لیست‌های پخش، حذف زمان، لایک کردن و دیسلایک کردن ویدیوها) را برای بهبود تجربه ویدیوی PiP کاربر ارائه دهد.

کنفرانس ویدیویی

کاربران اغلب، در طول یک جلسه کنفرانس ویدیویی، مانند هنگام ارائه از یک برگه دیگر به تماس، یادداشت‌برداری یا سایر فعالیت‌های چندوظیفه‌ای، به طور موقت از تب مرورگر خارج می‌شوند. با این حال، در بیشتر موارد، کاربر هنوز می‌خواهد تماس را ببیند، بنابراین این یک مورد استفاده ایده‌آل برای تصویر در تصویر است. بار دیگر، تجربه فعلی که یک وب‌سایت کنفرانس ویدیویی می‌تواند با API تصویر در تصویر برای <video> ارائه دهد، از نظر سبک و ورودی محدود است. با یک سند کامل در تصویر در تصویر، وب‌سایت می‌تواند به راحتی چندین جریان ویدیویی را در یک پنجره PiP ترکیب کند، بدون اینکه به هک‌های canvas متکی باشد و کنترل‌های سفارشی مانند ارسال پیام، بی‌صدا کردن کاربر دیگر یا بالا بردن دست را ارائه دهد.

بهره‌وری

تحقیقات نشان داده است که کاربران به روش‌های بیشتری برای بهره‌وری در وب نیاز دارند. قابلیت تصویر در تصویر به برنامه‌های وب انعطاف‌پذیری لازم برای انجام کارهای بیشتر را می‌دهد. چه ویرایش متن، یادداشت‌برداری، فهرست وظایف، پیام‌رسانی و چت یا ابزارهای طراحی و توسعه باشد، برنامه‌های وب اکنون می‌توانند محتوای خود را همیشه در دسترس نگه دارند.

رابط

خواص

documentPictureInPicture.window

در صورت وجود، پنجره تصویر در تصویر فعلی را برمی‌گرداند. در غیر این صورت، null را برمی‌گرداند.

روش‌ها

documentPictureInPicture.requestWindow(options)

یک promise را برمی‌گرداند که هنگام باز شدن پنجره تصویر در تصویر اجرا می‌شود. اگر promise بدون اشاره کاربر فراخوانی شود، رد می‌شود. دیکشنری options شامل اعضای اختیاری زیر است:

width

عرض اولیه پنجره تصویر در تصویر را تنظیم می‌کند.

height

ارتفاع اولیه پنجره تصویر در تصویر را تنظیم می‌کند.

disallowReturnToOpener

اگر مقدار آن درست باشد، دکمه‌ی «بازگشت به برگه» را در پنجره‌ی تصویر در تصویر پنهان می‌کند. این گزینه به طور پیش‌فرض نادرست است.

preferInitialWindowPlacement

اگر مقدار true باشد، پنجره‌ی تصویر در تصویر را در موقعیت و اندازه‌ی پیش‌فرضش باز می‌کند. این مقدار به‌طور پیش‌فرض 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>

باز کردن پنجره تصویر در تصویر

کد جاوا اسکریپت زیر، زمانی که کاربر روی دکمه‌ی باز کردن یک پنجره‌ی خالی تصویر در تصویر کلیک می‌کند، تابع documentPictureInPicture.requestWindow() را فراخوانی می‌کند. promise برگردانده شده با یک شیء جاوا اسکریپت پنجره‌ی تصویر در تصویر (Picture-in-Picture window) اجرا می‌شود. پخش‌کننده‌ی ویدیو با استفاده از 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() را روی اندازه ایده‌آل پنجره PiP تنظیم کنید. اگر مقادیر گزینه‌ها برای اندازه پنجره کاربرپسند خیلی بزرگ یا خیلی کوچک باشند، کروم ممکن است آنها را کاهش دهد.

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);
});

دکمه «بازگشت به برگه» را در پنجره PiP پنهان کنید

برای پنهان کردن دکمه در پنجره تصویر در تصویر که به کاربر اجازه می‌دهد به برگه بازکننده برگردد، گزینه 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();

وقتی وب‌سایت وارد PiP می‌شود، به آن گوش دهید

برای اطلاع از زمان باز شدن پنجره تصویر در تصویر، به رویداد "enter" در documentPictureInPicture گوش دهید. این رویداد شامل یک شیء window برای دسترسی به پنجره تصویر در تصویر است.

documentPictureInPicture.addEventListener("enter", (event) => {
  const pipWindow = event.window;
});

دسترسی به عناصر در پنجره PiP

دسترسی به عناصر پنجره تصویر در تصویر از طریق شیء برگردانده شده توسط 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;
}

مدیریت رویدادها از پنجره PiP

دکمه‌ها و کنترل‌ها را ایجاد کنید و به رویدادهای ورودی کاربر (مانند "click" ) پاسخ دهید، همانطور که همیشه در جاوا اسکریپت انجام می‌شود.

// 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);

تغییر اندازه پنجره PiP

برای تغییر اندازه پنجره تصویر در تصویر، از متدهای 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() Window برای فوکوس کردن پنجره‌ی بازشونده از پنجره‌ی تصویر در تصویر استفاده کنید. این متد به یک اشاره‌ی کاربر نیاز دارد.

const returnToTabButton = pipWindow.document.createElement("button");
returnToTabButton.textContent = "Return to opener tab";
returnToTabButton.addEventListener("click", () => {
  window.focus();
});
pipWindow.document.body.append(returnToTabButton);

حالت نمایش PiP در CSS

از حالت نمایش picture-in-picture CSS برای نوشتن قوانین خاص CSS استفاده کنید که فقط زمانی اعمال می‌شوند که (بخشی از) برنامه وب در حالت تصویر در تصویر نمایش داده شود.

@media all and (display-mode: picture-in-picture) {
  body {
    margin: 0;
  }
  h1 {
    font-size: 0.8em;
  }
}

تشخیص ویژگی

برای بررسی اینکه آیا API تصویر در تصویر سند پشتیبانی می‌شود، از دستور زیر استفاده کنید:

if ('documentPictureInPicture' in window) {
  // The Document Picture-in-Picture API is supported.
}

دموها

• پخش‌کننده‌ی VideoJS : با نسخه آزمایشی پخش‌کننده‌ی VideoJS از API تصویر در تصویر اسناد کار کنید.
• Tomodoro ، یک برنامه وب pomodoro، در صورت وجود از API تصویر در تصویر اسناد استفاده می‌کند. به درخواست GitHub آنها مراجعه کنید.

بازخورد خود را به اشتراک بگذارید

مشکلات را به همراه پیشنهادات و سوالات در گیت‌هاب ثبت کنید .

لینک‌های مفید

• توضیح دهنده عمومی
• مشخصات WICG
• اشکال ردیابی کروم
• ورودی ChromeStatus.com
• کامپوننت چشمک زن: Blink>Media>PictureInPicture
• بررسی تگ
• قصد آزمایش
• قصد ارسال