Acesse casos de uso incríveis com a API Picture-in-Picture de documentos

Jad Joubran

Publicado em: 4 de março de 2025

A API Picture-in-Picture de documentos (API Document PiP) permite que aplicativos da Web abram uma janela flutuante sempre no topo (uma janela picture-in-picture) que pode mostrar qualquer conteúdo HTML arbitrário.

Essa API é criada com base na API Picture-in-Picture para <video>, que permite continuar consumindo vídeo em uma janela PiP.

Como a API Document PiP pode mostrar qualquer conteúdo HTML arbitrário, você pode usá-la para desbloquear novos casos de uso interessantes.

Suporte a navegadores e melhoria progressiva

No momento da redação deste artigo, a API Picture-in-Picture de documentos tem disponibilidade limitada.

No entanto, isso não impede que você o use com aprimoramento progressivo ou degradação suave.

Ao planejar seu caso de uso, trate-o como um aprimoramento progressivo, e não como um recurso padrão. Neste artigo, você vai conferir um exemplo de degradação gradual.

Como melhorar a experiência do usuário do estudante com a API Picture-in-Picture de documentos

LearnHTMLCSS.online (em inglês) é uma plataforma de aprendizado interativa que ensina HTML e CSS semânticos e acessíveis. Ele oferece um editor de texto interativo e uma janela de visualização do navegador.

O screencast a seguir mostra o layout do app. A tela é dividida em duas colunas. A primeira coluna contém o editor de código. A segunda coluna contém um layout com guias. Por padrão, o usuário pode ver as instruções do desafio e clicar na guia Navegador para conferir uma prévia dinâmica.

Como estudante, talvez você queira maximizar a janela de visualização do navegador. Essa é uma ótima oportunidade para adicionar suporte à API Picture-in-Picture de documentos.

Para implementar isso, comece verificando o suporte do navegador:

const isPipSupported = "documentPictureInPicture" in window;

Agora você pode usar essa variável para encapsular qualquer chamada documentPictureInPicture ou para retornar antecipadamente de uma função que depende do Picture-in-Picture de documentos. O código a seguir verifica se há suporte para o PiP de documentos e abre uma janela desse recurso.

async function initDocumentPip() {
  if (!isPipSupported) {
    return false;
  }

  const pipWindow = await documentPictureInPicture.requestWindow({
    width: window.innerWidth,
    height: window.innerHeight,
  });
}

Dependendo do caso de uso, é possível especificar qualquer largura e altura para a janela. Você pode tentar corresponder a um elemento específico, ao documento atual ou até mesmo fornecer valores fixos.

Até agora, você tem um documento vazio. Agora, você precisa preenchê-lo com conteúdo.

// htmlCode is the HTML code of the challenge
pipWindow.document.documentElement.innerHTML = htmlCode;

Para desafios com código CSS, também é necessário sincronizar o CSS.

Pronto! Agora, há um botão de maximizar que abre em uma janela PiP separada.Além de maximizar a guia de visualização do navegador, você também pode movê-la para uma tela separada se tiver um monitor externo ou até mesmo reorganizar o web app principal e a guia de visualização do navegador em um layout de coluna.

Fallback

Lembre-se de que essa API tem disponibilidade limitada. Em navegadores e dispositivos sem suporte para essa API, você precisa fornecer um comportamento de substituição (degradação gradual).

Em vez de fazer com que o botão de maximizar puxe toda a guia de visualização do navegador, podemos fazer com que ele ocupe todo o espaço restante do web app atual.

Teste esse comportamento em diferentes navegadores: https://learnhtmlcss.online/app.html?id=2096

Não se esqueça de prestar atenção aos pequenos detalhes nas dicas. Quando isPipSupported é true, a dica do botão de maximizar/minimizar alterna entre Entrar no picture-in-picture e Sair do picture-in-picture. Por outro lado, quando isPipSupported é false, o comportamento de substituição é descrito com Maximizar e Minimizar.

Como você pode ver, a API Picture-in-Picture de documentos pode desbloquear novos casos de uso interessantes para seu web app quando combinada com melhoria progressiva ou degradação gradual.

Não deixe que o suporte limitado do navegador limite você e não se esqueça de ter um caso de uso de substituição adequado.

Confira a documentação do Picture-in-Picture de documentos para conhecer vários exemplos e casos de uso dessa API.