Метод DocumentPictureInPicture: requestWindow()

Ограниченная доступность

Эта функция не относится к Baseline, так как она не работает в некоторых из наиболее широко используемых браузеров.

Экспериментально: Это экспериментальная технология.
Перед использованием в производстве тщательно проверьте таблицу совместимости с браузерами.

Безопасный контекст: Эта функция доступна только в безопасных контекстах (HTTPS) в некоторых или во всех поддерживающих браузерах.

Метод requestWindow() интерфейса DocumentPictureInPicture открывает окно "картинка в картинке" для текущего основного контекста просмотра. Он возвращает Promise, который выполняется с экземпляром Window, представляющим контекст просмотра внутри окна "картинка в картинке".

Метод requestWindow() требует временного активирования, т.е. его необходимо вызывать в ответ на действие пользователя, такое как щелчок мышью или нажатие кнопки.

Синтаксис

requestWindow()
requestWindow(options)

Параметры

options Необязательно

Объект параметров, содержащий следующие свойства:

disallowReturnToOpener Необязательно

Булево значение. При установке в true, этот параметр подсказывает браузеру, что он не должен отображать элемент управления, позволяющий пользователю вернуться к исходной вкладке и закрыть окно "картинка в картинке". По умолчанию false.

Например, в реализации этой функции в Chrome предоставленный элемент управления — это кнопка "Назад к вкладке" в верхней строке окна "картинка в картинке":

browser window containing an embedded video player and multiple control buttons, with a back to tab button in the top bar, highlighted with a red box

height Необязательно

Положительное число, представляющее высоту области просмотра окна "картинка в картинке" в пикселях. По умолчанию 0.

preferInitialWindowPlacement Необязательно

Булево значение, по умолчанию false. При установке в true, окно "картинка в картинке" всегда будет отображаться в позиции и размере, в которых оно было открыто первоначально, после закрытия и повторного открытия. В отличие от этого, если preferInitialWindowPlacement равно false, размер и положение окна "картинка в картинке" будут запоминаться при закрытии и повторном открытии — оно будет открыто в предыдущем положении и размере, например, в соответствии с настройками пользователя.

width Необязательно

Положительное число, представляющее ширину области просмотра окна "картинка в картинке" в пикселях. По умолчанию 0.

Примечание: Если задан один из параметров height или width, должен быть задан и другой, в противном случае будет выброшено исключение. Если оба значения не заданы, заданы как 0 или установлены слишком большими, браузер будет прижимать или игнорировать значения в соответствии с требованиями удобства использования. Прижатый размер будет отличаться в зависимости от реализации, размера экрана и других факторов.

Возвращаемое значение

А Promise, который выполняется с экземпляром объекта Window, представляющим контекст просмотра внутри окна "картинка в картинке".

Исключения

NotSupportedError DOMException

Выбрасывается, если API было явно отключено (например, через настройки браузера).

NotAllowedError DOMException

Выбрасывается, если:

requestWindow() не вызывается из верхнего уровня объекта window.
requestWindow() вызывается из объекта window окна "картинка в картинке" (т.е. DocumentPictureInPicture.window).
requestWindow() вызывается без временного активирования.

RangeError DOMException

Выбрасывается, если задан только один из параметров height и width, или если height и width заданы с отрицательными значениями.

Примеры

const videoPlayer = document.getElementById("player");

// ...

// Open a Picture-in-Picture window with all options set
const pipWindow = await window.documentPictureInPicture.requestWindow({
  width: videoPlayer.clientWidth,
  height: videoPlayer.clientHeight,
  disallowReturnToOpener: true,
  preferInitialWindowPlacement: true,
});

// ...

Спецификации

Спецификация
Спецификация Document Picture-in-Picture # dom-documentpictureinpicture-requestwindow

Совместимость с браузерами

	Рабочие столы					Мобильные устройства
	Chrome	Edge	Firefox	Opera	Safari	Chrome Android	Firefox for Android	Opera Android	Safari на iOS	Samsung Internet	WebView Android
`requestWindow`	116	116	Нет	102	Нет	Нет	Нет	Нет	Нет	Нет	Нет
`option_disallowReturnToOpener`	124	124	Нет	110	Нет	Нет	Нет	Нет	Нет	Нет	Нет
`option_preferInitialWindowPlacement`	130	130	Нет	115	Нет	Нет	Нет	Нет	Нет	Нет	Нет

См. также

© 2005–2024 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/DocumentPictureInPicture/requestWindow