Картинка в картинке для любого элемента, а не только для <video>

François Beaufort

Поддержка браузера

• 116
• 116
• х
• х

Источник

API Document Picture-in-Picture позволяет открывать постоянное окно, которое можно заполнить произвольным HTML-содержимым. Он расширяет существующий API «Картинка в картинке» для <video> , который позволяет помещать в окно «Картинка в картинке» только HTML-элемент <video> .

Окно «Картинка в картинке» в API «Картинка в картинке документа» похоже на пустое окно того же происхождения, открытое с помощью window.open() , с некоторыми отличиями:

• Окно «Картинка в картинке» располагается поверх других окон.
• Окно «Картинка в картинке» никогда не переживет открывающееся окно.
• В окне «Картинка в картинке» невозможно перемещаться.
• Положение окна «Картинка в картинке» не может быть установлено на веб-сайте.

Окно «Картинка в картинке», созданное с помощью API Document «Картинка в картинке» ( демо ).

Текущий статус

Шаг	Статус
1. Создайте объяснитель	Полный
2. Создайте первоначальный проект спецификации.	В ходе выполнения
3. Соберите отзывы и доработайте дизайн	В ходе выполнения
4. Пробная версия происхождения	Полный
5. Запуск	Полный (Десктоп)

Варианты использования

Пользовательский видеоплеер

Веб-сайт может обеспечить просмотр видео «картинка в картинке» с помощью существующего API «картинка в картинке» для <video> , однако его возможности очень ограничены. Существующее окно «Картинка в картинке» принимает мало входных данных и имеет ограниченные возможности для их стилизации. Благодаря полному документу в формате «картинка в картинке» веб-сайт может предоставлять настраиваемые элементы управления и входные данные (например, субтитры , списки воспроизведения, скруббер времени, лайки и антипатии видео), чтобы улучшить работу пользователя с видео «картинка в картинке».

Видеоконференции

Пользователи часто покидают вкладку браузера во время сеанса видеоконференции по разным причинам (например, показ другой вкладки во время вызова или многозадачность), но при этом желают видеть вызов, поэтому это основной вариант использования функции «Картинка в Картина. Опять же, текущий опыт, который веб-сайт видеоконференций может предоставить через API «картинка в картинке» для <video> , ограничен по стилю и вводу. Благодаря полному документу в режиме «Картинка в картинке» веб-сайт может легко объединить несколько видеопотоков в одно окно PiP, не полагаясь на хаки холста и предоставляя настраиваемые элементы управления, такие как отправка сообщения, отключение звука другого пользователя или поднятие руки.

Производительность

Исследования показали, что пользователям нужно больше способов продуктивной работы в Интернете. Документ в режиме «Картинка в картинке» дает веб-приложениям гибкость, позволяющую достигать большего. Будь то редактирование текста, создание заметок, списки задач, обмен сообщениями и чат или инструменты дизайна и разработки, веб-приложения теперь могут всегда обеспечивать доступность своего контента.

Интерфейс

Характеристики

documentPictureInPicture.window

Возвращает текущее окно «Картинка в картинке», если оно есть. В противном случае возвращает null .

Методы

documentPictureInPicture.requestWindow(options)

Возвращает обещание, которое выполняется при открытии окна «Картинка в картинке». Промис отклоняется, если он вызывается без жестов пользователя. Словарь options содержит следующие необязательные элементы:

width

Устанавливает начальную ширину окна «Картинка в картинке».

height

Устанавливает начальную высоту окна «Картинка в картинке».

disallowReturnToOpener

Скрывает кнопку «Назад на вкладку» в окне «Картинка в картинке», если установлено значение true. По умолчанию это ложь.

preferInitialWindowPlacement

Откройте окно «Картинка в картинке» в положении и размере по умолчанию, если это правда. По умолчанию это ложь.

События

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

Примечание. Параметр disallowReturnToOpener доступен только в Chrome 124 и более поздних версиях.

Откройте окно «Картинка в картинке» в положении и размере по умолчанию.

Чтобы не использовать повторно положение или размер предыдущего окна «Картинка в картинке», установите для параметра 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,
  });
});

Примечание. Параметр preferInitialWindowPlacement доступен только в Chrome 130 и более поздних версиях.

Копирование таблиц стилей в окно «Картинка в картинке»

Чтобы скопировать все таблицы стилей 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() чтобы изменить размер окна «картинка в картинке». Оба метода требуют жеста пользователя.

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

Примечание. Изменение размера окна «Картинка в картинке» доступно только в Chrome 121 и более поздних версиях.

Фокус открывающегося окна

Используйте метод focus() Window, чтобы сфокусировать окно открытия из окна «Картинка в картинке». Этот метод требует жеста пользователя.

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

Примечание. Фокусировка окна открытия доступна только в Chrome 123 и более поздних версиях.

Режим отображения CSS «картинка в картинке»

Используйте режим отображения CSS picture-in-picture для написания определенных правил CSS, которые применяются только тогда, когда веб-приложение (часть) отображается в режиме «картинка в картинке».

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

Примечание. Режим отображения CSS «картинка в картинке» доступен только в Chrome 123 и более поздних версиях.

Обнаружение функций

Чтобы проверить, поддерживается ли API «Картинка в картинке» документа, используйте:

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

Демо

ВидеоJS-плеер

Вы можете поиграть с демо-версией проигрывателя VideoJS Document Picture-in-Picture API. Обязательно ознакомьтесь с исходным кодом .

Помидоро

Tomodoro , веб-приложение pomodoro, также использует API Document Picture-in-Picture, когда он доступен (см. запрос на извлечение GitHub ).

Окно «картинка в картинке» в Tomodoro.

Обратная связь

Пожалуйста, сообщайте о проблемах на GitHub с предложениями и вопросами.

Полезные ссылки

• Публичный объяснитель
• Спецификация WICG
• Ошибка отслеживания в Chrome
• Запись ChromeStatus.com
• Компонент Blink: Blink>Media>PictureInPicture
• Обзор тегов
• Намерение экспериментировать
• Намерение отправить

Благодарности

Изображение героя Джейкоба Оуэнса .