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

François Beaufort

Compatibilidade com navegadores

• 116
• 116
• x
• x

Origem

Com a API Document Picture-in-Picture, é possível abrir uma janela sempre ativada que pode ser preenchida com conteúdo HTML arbitrário. Ele 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 usando window.open(), com algumas diferenças:

• A janela picture-in-picture flutua sobre as outras janelas.
• A janela picture-in-picture nunca passa da 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.

.

Uma janela picture-in-picture criada com a API Document Picture-in-Picture (demonstração).

Status atual

Etapa	Status
1. Criar explicação	Concluído
2. Criar um rascunho inicial da especificação	Em andamento
3. Colete feedback e iterar no design	Em andamento
4. Teste de origem	Concluído
5. lançamento	Concluído (computador)

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 isso é muito limitado. A janela picture-in-picture atual aceita poucas entradas e tem capacidade limitada de estilização. Com um Documento em picture-in-picture completo, o site pode fornecer controles e entradas personalizadas (por exemplo, legendas, playlists, barra de progressão de tempo, marcar como "Gostei" e "Não gostei" em vídeos) para melhorar a experiência de vídeo picture-in-picture do usuário.

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, apresentando outra guia para a chamada ou realizando várias tarefas) enquanto ainda querem ver a chamada. Por isso, esse é um dos principais casos de uso do picture-in-picture. Mais uma vez, a experiência atual que um site de videoconferência pode oferecer com a API picture-in-picture para <video> tem limitações de estilo e entrada. Com um documento em picture-in-picture completo, o site pode combinar facilmente vários streams de vídeo em uma única janela picture-in-picture sem precisar de hacks de tela, além de 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 Document in picture-in-picture oferece aos aplicativos da Web a flexibilidade de realizar mais tarefas. Seja edição de texto, anotações, listas de tarefas, mensagens e chat 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 "Voltar à guia" na janela picture-in-picture se for verdadeiro. Ele é falso por padrão.

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 picture-in-picture em branco. A promessa retornada é resolvida com um objeto JavaScript da 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 fixar os valores de opção se eles forem muito grandes ou muito pequenos para se ajustarem a 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 "Voltar à guia" da janela picture-in-picture

Para ocultar o botão na janela picture-in-picture que permite ao usuário voltar à 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,
  });
});

Observação: a opção disallowReturnToOpener está disponível apenas no Chrome 124 e versões mais recentes.

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

Para copiar todas as folhas de estilo CSS da janela de origem, faça um loop por styleSheets explicitamente vinculado ou incorporado ao documento e anexe-as à janela picture-in-picture. Observe que esta é 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);
});

Observação:a opção copyStyleSheets era compatível com uma versão anterior da especificação. Não é mais o caso.

Processar quando a janela picture-in-picture é fechada

Ouça o evento "pagehide" da janela para saber quando a janela picture-in-picture é fechada, seja porque o site a iniciou manualmente ou o usuário a fechou manualmente. O manipulador de eventos é um bom local para recuperar os elementos da janela picture-in-picture, como mostrado abaixo.

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 de forma programática usando o método close().

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

Ouvir quando o site entrar no modo picture-in-picture

Ouça o evento "enter" em documentPictureInPicture para saber quando uma janela picture-in-picture é 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 do 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 a eventos de entrada do usuário, como "click", da mesma forma que você faria normalmente em 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. Os dois 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);

Observação: o redimensionamento da janela picture-in-picture está disponível apenas no Chrome 121 e versões mais recentes.

Focar a janela de abertura

Use o método de janela focus() para focar na janela de abertura usando a 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);

Observação: o foco na janela de abertura está disponível apenas no Chrome 123 e versões mais recentes.

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

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

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

Observação :o modo de exibição picture-in-picture do CSS está disponível apenas no Chrome 123 e versões mais recentes.

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 Document Picture-in-Picture. Verifique 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 (consulte Solicitação de envio do GitHub).

Uma janela picture-in-picture no Tomodoro.

Feedback

Registre os problemas no GitHub com sugestões e perguntas.

Links úteis

• Explicações públicas
• Especificação da WICG
• Bug de rastreamento do Chromium
• Entrada de ChromeStatus.com
• Componente Blink: Blink>Media>PictureInPicture
• Revisão do TAG
• Intenção de fazer experimentos
• Intenção de envio

Agradecimentos

Imagem principal de Jakob Owens.