Picture-in-picture para qualquer elemento, não apenas <video>

François Beaufort

A API Document Picture-in-Picture permite abrir uma janela sempre visível que pode ser preenchida com conteúdo HTML arbitrário. Ela estende a API Picture-in-Picture para <video>, que permite apenas que um elemento HTML <video> seja colocado em uma janela picture-in-picture.

A janela picture-in-picture na API Document Picture-in-Picture é semelhante a uma janela em branco de mesma origem aberta por window.open(), com algumas diferenças:

• A janela picture-in-picture flutua sobre outras janelas.
• A janela picture-in-picture nunca sobrevive à janela de abertura.
• Não é possível navegar pela janela picture-in-picture.
• A posição da janela Picture-in-Picture não pode ser definida pelo site.

Status atual

Casos de uso

Player de vídeo personalizado

Um site pode oferecer uma experiência de vídeo Picture-in-Picture com a API Picture-in-Picture para <video>, mas ela é muito limitada. A janela Picture-in-Picture atual aceita poucas entradas e tem capacidade limitada para estilizar. Com um documento completo em picture-in-picture, o site pode oferecer controles e entradas personalizados (por exemplo, legendas, playlists, controle de tempo, curtidas e não curtidas de vídeos) para melhorar a experiência do usuário com o vídeo picture-in-picture.

Videoconferências

É comum que os usuários saiam da guia do navegador durante uma sessão de videoconferência por vários motivos (por exemplo, apresentar outra guia para a chamada ou realizar multitarefas) enquanto ainda querem ver a chamada. Portanto, esse é um caso de uso principal para o picture-in-picture. Mais uma vez, a experiência atual que um site de videoconferência pode oferecer pela API Picture-in-Picture para <video> é limitada em estilo e entrada. Com um documento completo em picture-in-picture, o site pode combinar facilmente vários streams de vídeo em uma única janela de PiP sem precisar de hacks de tela e oferecer controles personalizados, como enviar uma mensagem, silenciar outro usuário ou levantar a mão.

Produtividade

Pesquisas demonstram que os usuários precisam de mais formas de serem produtivos na web. O modo picture-in-picture para documentos oferece aos apps da Web a flexibilidade para fazer mais. Seja para edição de texto, anotações, listas de tarefas, mensagens e bate-papo ou ferramentas de design e desenvolvimento, os apps da Web agora podem manter o conteúdo sempre acessível.

Interface

Propriedades

documentPictureInPicture.window

Retorna a janela picture-in-picture atual, se houver. Caso contrário, retorna null.

Métodos

documentPictureInPicture.requestWindow(options)

Retorna uma promessa que é resolvida quando uma janela picture-in-picture é aberta. A promessa será rejeitada se for chamada sem um gesto do usuário. O dicionário options contém os seguintes membros opcionais:

width

Define a largura inicial da janela picture-in-picture.

height

Define a altura inicial da janela picture-in-picture.

disallowReturnToOpener

Oculta o botão "Voltar para a guia" na janela Picture-in-Picture se for verdadeiro. Esse valor é falso por padrão.

preferInitialWindowPlacement

Abre a janela picture-in-picture na posição e no tamanho padrão, se verdadeiro. O padrão é "falso".

Eventos

documentPictureInPicture.onenter

É acionado em documentPictureInPicture quando uma janela picture-in-picture é aberta.

Exemplos

O HTML a seguir configura um player de vídeo personalizado e um elemento de botão para abrir o player de vídeo em uma janela picture-in-picture.

<div id="playerContainer">
  <div id="player">
    <video id="video"></video>
  </div>
</div>
<button id="pipButton">Open Picture-in-Picture window</button>

Abrir uma janela picture-in-picture

O JavaScript a seguir chama documentPictureInPicture.requestWindow() quando o usuário clica no botão para abrir uma janela de Picture-in-Picture em branco. A promessa retornada é resolvida com um objeto JavaScript de janela Picture-in-Picture. O player de vídeo é movido para essa janela usando 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);
});

Definir o tamanho da janela picture-in-picture

Para definir o tamanho da janela picture-in-picture, defina as opções width e height de documentPictureInPicture.requestWindow() como o tamanho desejado da janela. O Chrome pode limitar os valores de opção se eles forem muito grandes ou pequenos para caber em um tamanho de janela 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 o botão "voltar para a guia" da janela picture-in-picture

Para ocultar o botão na janela Picture-in-Picture que permite que o usuário volte para a guia de abertura, defina a opção disallowReturnToOpener de documentPictureInPicture.requestWindow() como 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,
  });
});

Abrir a janela picture-in-picture na posição e no tamanho padrão

Para não reutilizar a posição ou o tamanho da janela picture-in-picture anterior, defina a opção preferInitialWindowPlacement de documentPictureInPicture.requestWindow() como true.

pipButton.addEventListener("click", async () => {
  // Open a Picture-in-Picture window in its default position / size.
  const pipWindow = await documentPictureInPicture.requestWindow({
    preferInitialWindowPlacement: true,
  });
});

Copiar folhas de estilo para a janela picture-in-picture

Para copiar todas as folhas de estilo CSS da janela de origem, percorra as styleSheets vinculadas ou incorporadas explicitamente ao documento e anexe-as à janela Picture-in-Picture. Essa é uma cópia ú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);
});

Processar quando a janela picture-in-picture é fechada

Ouça o evento "pagehide" da janela para saber quando a janela picture-in-picture é fechada (porque o site a iniciou ou porque o usuário a fechou manualmente). O gerenciador de eventos é um bom lugar para retirar os elementos da janela Picture-in-Picture, conforme mostrado aqui.

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

Feche a janela Picture-in-Picture usando o método close().

// Close the Picture-in-Picture window programmatically. 
// The "pagehide" event will fire normally.
pipWindow.close();

Detectar quando o site entra no modo picture-in-picture

Detecte o evento "enter" em documentPictureInPicture para saber quando uma janela de imagem em imagem é aberta. O evento contém um objeto window para acessar a janela picture-in-picture.

documentPictureInPicture.addEventListener("enter", (event) => {
  const pipWindow = event.window;
});

Acessar elementos na janela picture-in-picture

Acesse elementos na janela picture-in-picture usando o objeto retornado por documentPictureInPicture.requestWindow() ou com documentPictureInPicture.window, conforme mostrado abaixo.

const pipWindow = documentPictureInPicture.window;
if (pipWindow) {
  // Mute video playing in the Picture-in-Picture window.
  const pipVideo = pipWindow.document.querySelector("#video");
  pipVideo.muted = true;
}

Processar eventos da janela picture-in-picture

Crie botões e controles e responda aos eventos de entrada do usuário, como "click", como faria normalmente no 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);

Redimensionar a janela picture-in-picture

Use os métodos de janela resizeBy() e resizeTo() para redimensionar a janela Picture-in-Picture. Ambos os métodos exigem um gesto do usuário.

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

Focar a janela de abertura

Use o método focus() para focar a janela de abertura na janela picture-in-picture. Esse método exige um gesto do usuário.

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

Modo de exibição picture-in-picture do CSS

Use o modo de exibição picture-in-picture do CSS para escrever regras CSS específicas que só são aplicadas quando (parte do) app da Web é mostrada no modo picture-in-picture.

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

Detecção de recursos

Para verificar se a API Document Picture-in-Picture é compatível, use:

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

Demonstrações

Player VideoJS

Você pode testar a demonstração do player VideoJS da API Picture-in-Picture do Document. Confira o código-fonte.

Pomodoro

O Tomodoro, um app da Web pomodoro, também está usando a API Document Picture-in-Picture, quando disponível. Confira a solicitação de envio do GitHub.

Envie feedback

Registre problemas no GitHub com sugestões e perguntas.

Links úteis

• Explicação para o público
• Especificação do WICG
• Bug de rastreamento do Chromium
• Entrada do ChromeStatus.com
• Componente Blink: Blink>Media>PictureInPicture
• Revisão do TAG
• Intent to Experiment
• Intenção de envio