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 Document Picture-in-Picture (API Document PiP) permite que os aplicativos da Web abram uma janela flutuante sempre visível (uma janela picture-in-picture) que pode exibir qualquer conteúdo HTML arbitrário.

Essa API é baseada na API Picture-in-Picture para <video>, que permite continuar assistindo vídeos 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.

Suporte a navegadores e melhoria progressiva

Browser Support

• 116
• 116
• x
• x

Source

No momento da escrita, a API Document Picture-in-Picture tem disponibilidade limitada.

No entanto, isso não impede o uso 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 suave.

Como melhorar a experiência do usuário do aluno com a API Document PiP

LearnHTMLCSS.online é uma plataforma de aprendizagem 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 conferir as instruções do desafio e clicar na guia Navegador para ver uma prévia ao vivo.

Como estudante, às vezes você pode querer maximizar a janela de visualização do navegador. Essa é a oportunidade perfeita para adicionar suporte à API Document Picture-in-Picture.

Para implementar isso, comece verificando o suporte do navegador:

const isPipSupported = "documentPictureInPicture" in window;

Agora é possível usar essa variável para agrupar todas as chamadas documentPictureInPicture ou retornar antecipadamente de uma função que depende do PiP de documentos. O código a seguir verifica se há suporte para o PiP de documento e, em seguida, abre uma janela de PiP de documento.

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 preencher o conteúdo.

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

Para desafios com código CSS, você também precisa sincronizar o CSS.

Pronto! Agora você tem um botão de maximização 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 app da Web principal e a guia de visualização do navegador em um layout de coluna.

Fallback

Essa API tem disponibilidade limitada. Em navegadores e dispositivos sem suporte a essa API, é necessário fornecer um comportamento de fallback (degradação suave).

Em vez de fazer com que o botão de maximização abra toda a guia de visualização do navegador, podemos fazer com que ele ocupe todo o espaço restante do app da Web 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 maximizar/minimizar alterna entre Ativar picture-in-picture e Sair do picture-in-picture. Por outro lado, quando isPipSupported é false, o comportamento padrão é descrito com Maximizar e Minimizar.

---

Como você pode ver, a API Document Picture-in-Picture pode desbloquear novos casos de uso interessantes para seu app da Web quando combinada com o aprimoramento progressivo ou a degradação suave.

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

Confira a documentação da PiP de documentos para conferir vários exemplos e casos de uso dessa API.