La API de pantalla en pantalla del documento permite abrir una ventana siempre activa que se puede propagar con contenido HTML arbitrario. Extiende la API de pantalla en pantalla existente para <video>
, que solo permite que se coloque un elemento <video>
de HTML en una ventana de pantalla en pantalla.
La ventana de pantalla en pantalla de la API de pantalla en pantalla del documento es similar a una ventana en blanco del mismo origen que se abre a través de window.open()
, pero con algunas diferencias:
- La ventana de Pantalla en pantalla flota sobre otras ventanas.
- La ventana de Pantalla en pantalla nunca dura más tiempo que la ventana de apertura.
- No se puede navegar por la ventana de Pantalla en pantalla.
- El sitio web no puede establecer la posición de la ventana de Pantalla en pantalla.
![Una ventana de pantalla en pantalla que reproduce un video de avance de Sintel.](https://developer.chrome.google.cn/static/docs/web-platform/document-picture-in-picture/image/a-picture-picture-window-a75f117724132.png?authuser=0000&hl=es)
Estado actual
Paso | Estado |
---|---|
1. Crear explicación | Completo |
2. Crea el borrador inicial de la especificación | En curso |
3. Recopila comentarios y iterar en el diseño | En curso |
4. Prueba de origen | Completo |
5. Lanzamiento | Completo (computadoras de escritorio) |
Casos de uso
Reproductor de video personalizado
Un sitio web puede proporcionar una experiencia de video de pantalla en pantalla con la API de pantalla en pantalla para <video>
existente. Sin embargo, es muy limitada. La ventana de pantalla en pantalla existente acepta pocas entradas y tiene una capacidad limitada para ajustar su estilo. Con un documento en pantalla completa, el sitio web puede proporcionar entradas y controles personalizados (por ejemplo, subtítulos, playlists, punto de arrastre de tiempo, indicar que te gusta o que no te gusta videos) para mejorar la experiencia de pantalla en pantalla del usuario.
Videoconferencias
Es común que los usuarios salgan de la pestaña del navegador durante una sesión de videoconferencia por varias razones (por ejemplo, cuando presentan otra pestaña a la llamada o realizan varias tareas a la vez) mientras aún desean ver la llamada, por lo que es un caso de uso primordial para la función pantalla en pantalla. Una vez más, la experiencia actual que un sitio web de videoconferencias puede proporcionar a través de la API de pantalla en pantalla para <video>
tiene un estilo y una entrada limitados. Con un Documento en pantalla en pantalla completo, el sitio web puede combinar fácilmente varias transmisiones de video por Internet en una sola ventana de PIP sin tener que depender de hackeos de lienzo y proporcionar controles personalizados, como enviar un mensaje, silenciar a otro usuario o levantar la mano.
Productividad
Las investigaciones han demostrado que los usuarios necesitan más formas de ser productivos en la Web. La función Documento en pantalla en pantalla les brinda a las aplicaciones web la flexibilidad para lograr más. Ya sea para editar texto, tomar notas, listas de tareas, mensajería y chat, o herramientas de diseño y desarrollo, las aplicaciones web ahora pueden mantener su contenido siempre accesible.
Interfaz
Propiedades
documentPictureInPicture.window
- Muestra la ventana de Pantalla en pantalla actual, si existe. De lo contrario, muestra
null
.
Métodos
documentPictureInPicture.requestWindow(options)
Muestra una promesa que se resuelve cuando se abre una ventana de Pantalla en pantalla. La promesa se rechaza si se llama sin un gesto del usuario. El diccionario
options
contiene los siguientes miembros opcionales:width
- Establece el ancho inicial de la ventana de pantalla en pantalla.
height
- Establece la altura inicial de la ventana de pantalla en pantalla.
disallowReturnToOpener
- Oculta la opción "Volver a la pestaña" de la ventana Pantalla en pantalla si esta opción está establecida. Es falso de forma predeterminada.
Eventos
documentPictureInPicture.onenter
- Se activa el
documentPictureInPicture
cuando se abre una ventana de pantalla en pantalla.
Ejemplos
El siguiente código HTML configura un reproductor de video personalizado y un elemento de botón para abrirlo en una ventana de pantalla en pantalla.
<div id="playerContainer">
<div id="player">
<video id="video"></video>
</div>
</div>
<button id="pipButton">Open Picture-in-Picture window</button>
Abre una ventana de Pantalla en pantalla.
El siguiente JavaScript llama a documentPictureInPicture.requestWindow()
cuando el usuario hace clic en el botón para abrir una ventana en blanco de Pantalla en pantalla. La promesa que se muestra se resuelve con un objeto de JavaScript de ventana de pantalla en pantalla. El reproductor de video se moverá a esa ventana mediante 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);
});
Configura el tamaño de la ventana de Pantalla en pantalla
Para establecer el tamaño de la ventana de pantalla en pantalla, configura las opciones width
y height
de documentPictureInPicture.requestWindow()
con el tamaño deseado de pantalla en pantalla. Es posible que Chrome fije los valores de las opciones si son demasiado grandes o demasiado pequeños para adaptarse a un tamaño de ventana fácil de usar.
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);
});
Ocultar la opción "Volver a la pestaña" botón de la ventana Pantalla en pantalla
Para ocultar el botón en la ventana de pantalla en pantalla que le permite al usuario volver a la pestaña de apertura, establece la opción disallowReturnToOpener
de documentPictureInPicture.requestWindow()
en 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,
});
});
Copiar hojas de estilo en la ventana Pantalla en pantalla
Para copiar todas las hojas de estilo CSS de la ventana de origen, realiza un bucle a lo largo de styleSheets
explícitamente vinculadas o incorporadas en el documento y agrégalas a la ventana de pantalla en pantalla. Ten en cuenta que esta es una copia única.
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);
});
Cómo controlar cuándo se cierra la ventana de Pantalla en pantalla
Escucha el evento "pagehide"
de la ventana para saber cuándo se cierra la ventana de Pantalla en pantalla (ya sea porque el sitio web la inició o el usuario la cerró manualmente). El controlador de eventos es un buen lugar para recuperar los elementos de la ventana de pantalla en pantalla, como se muestra a continuación.
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);
});
});
Cierra la ventana de Pantalla en pantalla de manera programática con el método close()
.
// Close the Picture-in-Picture window programmatically.
// The "pagehide" event will fire normally.
pipWindow.close();
Escuchar cuando el sitio web ingresa al modo de pantalla en pantalla
Escucha el evento "enter"
en documentPictureInPicture
para saber cuándo se abre la ventana de pantalla en pantalla. El evento contiene un objeto window
para acceder a la ventana de pantalla en pantalla.
documentPictureInPicture.addEventListener("enter", (event) => {
const pipWindow = event.window;
});
Accede a los elementos en la ventana Pantalla en pantalla
Accede a los elementos en la ventana Pantalla en pantalla desde el objeto que muestra documentPictureInPicture.requestWindow()
, o bien con documentPictureInPicture.window
, como se muestra a continuación.
const pipWindow = documentPictureInPicture.window;
if (pipWindow) {
// Mute video playing in the Picture-in-Picture window.
const pipVideo = pipWindow.document.querySelector("#video");
pipVideo.muted = true;
}
Controla eventos desde la ventana de pantalla en pantalla
Crea botones y controles, y responde a los eventos de entrada del usuario, como "click"
, como lo harías normalmente en 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);
Cambia el tamaño de la ventana de Pantalla en pantalla
Usa los métodos de ventana resizeBy()
y resizeTo()
para cambiar el tamaño de la ventana de pantalla en pantalla. Ambos métodos requieren un gesto del usuario.
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);
Enfocar la ventana de apertura
Usa el método de ventana focus()
para enfocar la ventana de apertura de la ventana de Pantalla en pantalla. Este método requiere un gesto del usuario.
const returnToTabButton = pipWindow.document.createElement("button");
returnToTabButton.textContent = "Return to opener tab";
returnToTabButton.addEventListener("click", () => {
window.focus();
});
pipWindow.document.body.append(returnToTabButton);
Modo de visualización de pantalla en pantalla de CSS
Usa el modo de visualización picture-in-picture
de CSS para escribir reglas de CSS específicas que solo se aplican cuando la app web se muestra en el modo de pantalla en pantalla (una parte de ella).
@media all and (display-mode: picture-in-picture) {
body {
margin: 0;
}
h1 {
font-size: 0.8em;
}
}
Detección de funciones
Para comprobar si se admite la API de pantalla en pantalla del documento, usa lo siguiente:
if ('documentPictureInPicture' in window) {
// The Document Picture-in-Picture API is supported.
}
Demostraciones
Reproductor de VideoJS
Puedes jugar con la demostración del reproductor de videoJS de la API de pantalla en pantalla del documento. Asegúrate de consultar el código fuente.
Pomodoro
Tomodoro, una app web de pomodoro, también aprovecha la API de pantalla en pantalla del documento cuando está disponible (consulta Solicitud de extracción de GitHub).
![Captura de pantalla de Tomodoro, una app web de Pomodoro](https://developer.chrome.google.cn/static/docs/web-platform/document-picture-in-picture/image/screenshot-tomodoro-po-6e0b39f6f0b17.png?authuser=0000&hl=es)
Comentarios
Informa los problemas en GitHub con sugerencias y preguntas.
Vínculos útiles
- Explicación pública
- Especificación de WICG
- Error de seguimiento de Chromium
- Entrada de ChromeStatus.com
- Componente de parpadeo:
Blink>Media>PictureInPicture
- Revisión del TAG
- Intención de experimentar
- Intención de enviar
Agradecimientos
Hero image de Jakob Owens.