API «Окно с картинкой в картинке» документа

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

Часто бывает полезно иметь для веб-приложения дополнительное окно помимо основного окна, в котором оно выполняется. Возможно, вы захотите просматривать другие окна, сохраняя при этом конкретный контент приложения в поле зрения, или вы захотите предоставить этому контенту собственное пространство, сохраняя основное окно приложения свободным для отображения другого контента. Вы можете справиться с этим, просто открыв обычное новое окно браузера, но это связано с двумя основными проблемами:

1. Вам нужно обрабатывать совместное использование информации о состоянии между двумя окнами.
2. Дополнительное окно приложения не всегда остается поверх других окон и, следовательно, может быть скрыто другими окнами.

Для решения этих проблем веб-браузеры представили API, позволяющие приложениям создавать окно, всегда находящееся поверх других, которое является частью одной сессии. Первый признанный случай использования — сохранение воспроизведения видео в отдельном окне, чтобы пользователь мог продолжать его просмотр, одновременно рассматривая другой контент. Это обрабатывается с помощью API «Картинка в картинке» для <video>, который напрямую используется на элементе <video> для размещения его в отдельном окне.

Однако этот API оказался несколько ограниченным — вы можете поместить только один <video> элемент в окно, всегда находящееся поверх других, с минимальными управляющими элементами, создаваемыми браузером. Для большей гибкости был представлен API «Картинка в картинке» документа. Это позволяет помещать любой контент в окно, всегда находящееся поверх других, для широкого спектра случаев использования, включая:

• Игровой видеоплеер, всегда находящийся поверх других, показывающий один или несколько видео с пользовательскими элементами управления и стилями.
• Система видеоконференций, которая позволяет пользователю всегда видеть потоки других участников, а также элементы управления для презентации контента, отключения звука, завершения звонков и т. д.
• Всегда видимые инструменты повышения производительности, такие как таймеры, заметки, списки задач, инструменты мгновенного обмена сообщениями и т. д.
• Отдельное окно для сохранения дополнительного контента, при этом основное окно приложения остается свободным от элементов управления. Например, у вас может быть игра в жанре ролевой игры, в которой вы хотите отобразить элементы управления игрой, инструкции или сведения о мире в дополнительном окне, сохранив основное окно свободным для отображения игровых локаций и карты.

Новый объект DocumentPictureInPicture, представляющий окно «Картинка в картинке», всегда находящееся поверх других, для текущего контекста документа, доступен через Window.documentPictureInPicture. Окно «Картинка в картинке» открывается путем вызова метода DocumentPictureInPicture.requestWindow(), который возвращает Promise, который выполняется с собственным объектом окна Window.

Окно «Картинка в картинке» похоже на пустое окно с одним источником, открытое через Window.open(), но с некоторыми отличиями:

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

Помимо этого, вы можете манипулировать экземпляром окна «Картинка в картинке» Window как вам угодно, например, добавляя в него отображаемый контент в DOM и копируя стили в него, чтобы добавленный контент отображался так же, как и в основном окне. Вы также можете закрыть окно «Картинка в картинке» (нажав предоставленный браузером элемент управления или выполнив Window.close() на нем), а затем отреагировать на его закрытие, используя стандартное событие pagehide. При закрытии вы захотите вернуть отображаемый контент в основное окно приложения.

Подробное руководство по использованию см. в разделе Использование API «Картинка в картинке» документа.

DocumentPictureInPicture

Точка входа для создания и обработки окон документа «Картинка в картинке».

DocumentPictureInPictureEvent

Объект события для события enter, которое срабатывает при открытии окна «Картинка в картинке».

Window.documentPictureInPicture

Возвращает ссылку на объект DocumentPictureInPicture для текущего контекста документа.

display-mode, значение picture-in-picture

Значение @media media feature, которое позволяет разработчикам применять CSS к документу в зависимости от того, отображается ли он в режиме «Картинка в картинке».

См. Пример API «Картинка в картинке» документа для полной демонстрации (см. также полный исходный код).