Questa pagina è stata tradotta dall'API Cloud Translation.

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

François Beaufort

Supporto dei browser

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

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

La finestra Picture in picture viene visualizzata sopra le altre finestre.
La finestra Picture in picture non sopravvive mai alla finestra di apertura.
Non è possibile navigare nella finestra Picture in picture.
La posizione della finestra Picture in picture non può essere impostata dal sito web.

Una finestra Picture in picture che riproduce il video del trailer di Sintel. — Una finestra Picture-in-Picture creata con l'API Document Picture-in-Picture (demo).

Stato attuale

Passaggio	Stato
1. Creare un video esplicativo	Completato
2. Creare una bozza iniziale della specifica	In corso
3. Raccogli feedback e esegui l'iterazione sul design	In corso
4. Prova dell'origine	Completato
5. Avvia	Completato (computer)

Casi d'uso

Video player personalizzato

Un sito web può offrire un'esperienza video Picture-in-Picture con l'API Picture-in-Picture esistente per <video>, ma è molto limitata. La finestra Picture in picture esistente accetta pochi input e ha una capacità limitata di personalizzarli. Con un documento completo in Picture in Picture, il sito web può fornire controlli e input personalizzati (ad esempio sottotitoli codificati, playlist, cursore del tempo, Mi piace e Non mi piace) per migliorare l'esperienza video in Picture in Picture dell'utente.

Videoconferenze

È normale che gli utenti escano dalla scheda del browser durante una sessione di videoconferenza per vari motivi (ad esempio, per presentare un'altra scheda alla chiamata o per il multitasking) pur volendo continuare a vedere la chiamata. Pertanto, si tratta di un caso d'uso principale per la funzionalità Picture in picture. Ancora una volta, l'esperienza attuale che un sito web di videoconferenze può offrire tramite l'API Picture in Picture per <video> è limitata in termini di stile e input. Con un documento completo in modalità Picture in picture, il sito web può combinare facilmente più stream video in un'unica finestra PiP senza dover fare affidamento su hack di canvas e fornire controlli personalizzati come l'invio di un messaggio, la disattivazione dell'audio di un altro utente o il rialzo della mano.

Produttività

Da una ricerca è emerso che gli utenti hanno bisogno di più modi per essere produttivi sul web. La modalità Picture in picture dei documenti offre alle app web la flessibilità per fare di più. Che si tratti di modifica di testo, presa di appunti, elenchi di attività, messaggistica e chat o strumenti di progettazione e sviluppo, ora le app web possono mantenere i propri contenuti sempre accessibili.

Interfaccia

Proprietà

documentPictureInPicture.window: Restituisce la finestra Picture in picture corrente, se esistente. In caso contrario, restituisce null.

Metodi

documentPictureInPicture.requestWindow(options)

Restituisce una promessa che si risolve quando viene aperta 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: Nasconde il pulsante "Torna alla scheda" nella finestra Picture in picture se il valore è true. Il valore predefinito è false.
preferInitialWindowPlacement: Apri la finestra Picture in picture nelle dimensioni e nella posizione predefinite se true. Per impostazione predefinita è false.

Eventi

documentPictureInPicture.onenter: Evento attivato su documentPictureInPicture quando viene aperta una finestra Picture in picture.

Esempi

Il seguente codice HTML configura un video player personalizzato e un elemento di 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 della 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() sulle dimensioni della finestra Picture in picture che preferisci. Chrome potrebbe limitare i valori delle opzioni se sono troppo grandi o troppo piccoli per adattarsi a dimensioni della finestra 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);
});

Nascondere il pulsante "Torna alla scheda" 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,
  });
});

Aprire la finestra Picture in picture nelle dimensioni e nella posizione predefinite

Per non riutilizzare la posizione o le dimensioni della finestra Picture in picture precedente, imposta l'opzione preferInitialWindowPlacement di documentPictureInPicture.requestWindow() su true.

pipButton.addEventListener("click", async () => {
  // Open a Picture-in-Picture window in its default position / size.
  const pipWindow = await documentPictureInPicture.requestWindow({
    preferInitialWindowPlacement: true,
  });
});

Copiare i fogli di stile nella finestra Picture in picture

Per copiare tutti gli stili CSS dalla finestra di origine, esegui un ciclo per gli styleSheets collegati esplicitamente o incorporati nel documento e aggiungili alla finestra Picture-in-Picture. Tieni presente che si tratta di 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);
});

Gestire la chiusura della finestra Picture in picture

Ascolta l'evento "pagehide" window per sapere quando la finestra Picture in picture viene chiusa (perché è stata avviata dal sito web o perché l'utente l'ha chiusa manualmente). Il gestore eventi è un buon punto per rimuovere gli elementi dalla finestra Picture-in-Picture, come mostrato qui.

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 tramite programmazione utilizzando il metodo close().

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

Ascoltare quando il sito web attiva la modalità Picture in picture

Ascolta l'evento "enter" su 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, come "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 Window 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);

Impostare lo stato attivo sulla finestra di apertura

Utilizza il metodo Window focus() per impostare lo stato attivo sulla 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 CSS picture-in-picture per scrivere regole CSS specifiche che vengono applicate solo quando (parte della) l'app web viene visualizzata in modalità Picture-in-Picture.

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

Rilevamento di funzionalità

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

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

Demo

VideoJS player

Puoi provare l'demo del player VideoJS con l'API Document Picture-in-Picture. Assicurati di controllare il codice sorgente.

Pomodoro

Tomodoro, un'app web per la tecnica pomodoro, sfrutta anche l'API Picture-in-Picture di Document, se disponibile. Consulta la richiesta di pull di GitHub.

Condividi il tuo feedback

Segnala i problemi su GitHub con suggerimenti e domande.