Picture in picture per qualsiasi elemento, non solo per i <video>

François Beaufort

L'API Document Picture-in-Picture consente di aprire una finestra sempre attiva, che può essere completata con contenuti HTML arbitrari. Estende l'API Picture in picture per <video> esistente che consente di inserire solo un elemento HTML <video> in una finestra Picture in picture.

La finestra Picture in picture nell'API Document Picture in picture è simile a una finestra vuota della stessa origine aperta tramite window.open(), con alcune differenze:

• La finestra Picture in picture è visualizzata sopra le altre finestre.
• La finestra Picture in picture non supera mai la finestra di apertura.
• Impossibile esplorare la finestra Picture in picture.
• La posizione della finestra Picture in picture non può essere impostata dal sito web.

Stato attuale

Casi d'uso

Video player personalizzato

Un sito web può fornire un'esperienza video Picture in picture con l'API Picture in picture per <video> esistente, ma è molto limitata. La finestra Picture in picture esistente accetta pochi input e ha una capacità limitata di applicarli. Con la versione completa di Document in Picture in picture, il sito web può fornire controlli e input personalizzati (ad esempio, sottotitoli codificati, playlist, dispositivo di scorrimento temporale, Mi piace e Non mi piace) per migliorare l'esperienza video Picture in picture dell'utente.

Videoconferenze

In genere, gli utenti abbandonano la scheda del browser durante una sessione di videoconferenza per vari motivi (ad esempio per la presentazione di un'altra scheda durante una chiamata o per il multitasking), mentre desiderano ancora vedere la chiamata, quindi si tratta di un caso d'uso primario per Picture in picture. Ancora una volta, l'esperienza attuale che un sito web di videoconferenza può offrire tramite l'API Picture in picture per <video> è limitata nello stile e nell'input. Con un modello completo di Document in Picture in picture, il sito web può facilmente combinare più stream video in un'unica finestra PIP senza dover fare affidamento su hacking su canvas e fornire controlli personalizzati come l'invio di un messaggio, la disattivazione dell'audio di un altro utente o la possibilità di alzare una mano.

Produttività

Gli studi hanno dimostrato che gli utenti hanno bisogno di più modi per essere produttivi sul web. Document in Picture in picture offre alle app web la flessibilità necessaria per fare di più. Che si tratti di modifica del testo, appunti, elenchi di attività, messaggistica e chat o strumenti di progettazione e sviluppo, le app web ora possono mantenere i loro contenuti sempre accessibili.

Interfaccia

Proprietà

documentPictureInPicture.window

Restituisci la finestra Picture in picture attuale, se presente. In caso contrario, restituisce null.

Metodi

documentPictureInPicture.requestWindow(options)

Restituisce una promessa che si risolve all'apertura di una finestra Picture in picture. La promessa viene rifiutata se viene chiamata senza un gesto dell'utente. Il dizionario options contiene i seguenti membri facoltativi:

width

Imposta la larghezza iniziale della finestra Picture in picture.

height

Imposta l'altezza iniziale della finestra Picture in picture.

disallowReturnToOpener

Nascondi il "Torna alla scheda" nella finestra Picture in picture, se il valore è true. Il valore è false per impostazione predefinita.

Eventi

documentPictureInPicture.onenter

Attivato il giorno documentPictureInPicture quando è aperta una finestra Picture in picture.

Esempi

Il seguente codice HTML consente di configurare un video player personalizzato e un elemento pulsante per aprire il video player in una finestra Picture in picture.

<div id="playerContainer">
  <div id="player">
    <video id="video"></video>
  </div>
</div>
<button id="pipButton">Open Picture-in-Picture window</button>

Aprire una finestra Picture in picture

Il seguente codice JavaScript chiama documentPictureInPicture.requestWindow() quando l'utente fa clic sul pulsante per aprire una finestra Picture in picture vuota. La promessa restituita viene risolta con un oggetto JavaScript finestra Picture in picture. Il video player viene spostato in quella finestra utilizzando 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);
});

Impostare le dimensioni della finestra Picture in picture

Per impostare le dimensioni della finestra Picture in picture, imposta le opzioni width e height di documentPictureInPicture.requestWindow() alle dimensioni desiderate della finestra Picture in picture. Chrome potrebbe bloccare i valori delle opzioni se sono troppo grandi o troppo piccoli per adattarsi alle dimensioni delle finestre facili da usare.

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);
});

Nascondi "Torna alla scheda" pulsante della finestra Picture in picture

Per nascondere il pulsante nella finestra Picture in picture che consente all'utente di tornare alla scheda di apertura, imposta l'opzione disallowReturnToOpener di documentPictureInPicture.requestWindow() su 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,
  });
});

Copiare i fogli di stile nella finestra Picture in picture

Per copiare tutti i fogli di stile CSS dalla finestra di origine, esegui il loop di styleSheets esplicitamente collegati o incorporati nel documento e aggiungili alla finestra Picture in picture. Tieni presente che questa è una copia una tantum.

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);
});

Punto di manipolazione alla chiusura della finestra Picture in picture

Ascolta l'evento della finestra "pagehide" per sapere quando la finestra Picture in picture viene chiusa (perché è stata avviata dal sito web o perché è stata chiusa manualmente dall'utente). Il gestore di eventi è un ottimo posto per ripristinare gli elementi dalla finestra Picture in picture, come mostrato di seguito.

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);
  });
});

Chiudi la finestra Picture in picture in modo programmatico mediante il metodo close().

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

Ascolta quando il sito web accede alla modalità Picture in picture

Ascolta l'evento "enter" il giorno documentPictureInPicture per sapere quando viene aperta una finestra Picture in picture. L'evento contiene un oggetto window per accedere alla finestra Picture in picture.

documentPictureInPicture.addEventListener("enter", (event) => {
  const pipWindow = event.window;
});

Accedere agli elementi nella finestra Picture in picture

Accedi agli elementi nella finestra Picture in picture dall'oggetto restituito da documentPictureInPicture.requestWindow() o con documentPictureInPicture.window, come mostrato di seguito.

const pipWindow = documentPictureInPicture.window;
if (pipWindow) {
  // Mute video playing in the Picture-in-Picture window.
  const pipVideo = pipWindow.document.querySelector("#video");
  pipVideo.muted = true;
}

Gestire gli eventi dalla finestra Picture in picture

Crea pulsanti e controlli e rispondi agli eventi di input dell'utente, ad esempio "click", come faresti normalmente in 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);

Ridimensionare la finestra Picture in picture

Utilizza i metodi Finestra resizeBy() e resizeTo() per ridimensionare la finestra Picture in picture. Entrambi i metodi richiedono un gesto dell'utente.

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);

Imposta lo stato attivo sulla finestra di apertura

Utilizza il metodo Finestra focus() per impostare lo stato attivo della finestra di apertura dalla finestra Picture in picture. Questo metodo richiede un gesto dell'utente.

const returnToTabButton = pipWindow.document.createElement("button");
returnToTabButton.textContent = "Return to opener tab";
returnToTabButton.addEventListener("click", () => {
  window.focus();
});
pipWindow.document.body.append(returnToTabButton);

Modalità di visualizzazione Picture in picture CSS

Utilizza la modalità di visualizzazione picture-in-picture del CSS per scrivere regole CSS specifiche che vengono applicate solo quando (parte di) l'app web viene mostrata in modalità Picture in picture.

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

Rilevamento delle caratteristiche

Per verificare se l'API Document Picture in picture è supportata, utilizza:

if ('documentPictureInPicture' in window) {
  // The Document Picture-in-Picture API is supported.
}

Demo

Player VideoJS

Puoi utilizzare la demo del player VideoJS dell'API Document Picture-in-Picture. Assicurati di controllare il codice sorgente.

Pomodoro

Tomodoro, un'app web di pomodoro, sta sfruttando anche l'API Document Picture in picture quando disponibile (vedi Richiesta di pull GitHub).

Feedback

Segnala i problemi su GitHub con suggerimenti e domande.

Link utili

• Spiegazione pubblica
• Specifiche WiCG
• Bug di monitoraggio di Chromium
• Voce ChromeStatus.com
• Componente Blink: Blink>Media>PictureInPicture
• Revisione TAG
• Intenzione di sperimentare
• Intenzione di spedizione

Ringraziamenti

Immagine hero di Jakob Owens.