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