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 que reproduz o vídeo de trailer do Sintel.](https://developer.chrome.com/static/docs/web-platform/document-picture-in-picture/image/a-picture-picture-window-a75f117724132.png?authuser=19&hl=pt)
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,
});
});
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);
});
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);
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);
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;
}
}
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).
![Captura de tela do Tomodoro, um app da Web pomodoro.](https://developer.chrome.com/static/docs/web-platform/document-picture-in-picture/image/screenshot-tomodoro-po-6e0b39f6f0b17.png?authuser=19&hl=pt)
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.