Se usó la API de Cloud Translation para traducir esta página.

Pantalla en pantalla para cualquier elemento, no solo para <video>

François Beaufort

Navegadores compatibles

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. — Una ventana de pantalla en pantalla creada con la API de pantalla en pantalla del documento (demostración).

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

Nota: La opción copyStyleSheets era compatible con una versión anterior de la especificación. Ya no ocurre.

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

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.