Picture-in-picture pour tous les éléments, pas uniquement les <vidéos>

François Beaufort

L'API Document Picture-in-Picture permet d'ouvrir une fenêtre toujours au premier plan, qui peut être remplie avec du contenu HTML arbitraire. Elle étend l'API Picture-in-Picture existante pour <video>, qui ne permet de placer qu'un élément HTML <video> dans une fenêtre Picture-in-Picture.

La fenêtre Picture-in-picture de l'API Document Picture-in-picture est semblable à une fenêtre vide de même origine ouverte via window.open(), avec quelques différences :

• La fenêtre Picture-in-picture flotte au-dessus des autres fenêtres.
• La fenêtre Picture-in-picture ne survit jamais à la fenêtre d'origine.
• Il est impossible de naviguer dans la fenêtre Picture-in-picture.
• La position de la fenêtre Picture-in-picture ne peut pas être définie par le site Web.

État actuel

Cas d'utilisation

Lecteur vidéo personnalisé

Un site Web peut proposer une expérience vidéo Picture-in-Picture avec l'API Picture-in-Picture existante pour <video>, mais elle est très limitée. La fenêtre Picture-in-picture existante accepte peu d'entrées et offre des possibilités de style limitées. Avec un document complet en Picture-in-picture, le site Web peut fournir des commandes et des entrées personnalisées (par exemple, des sous-titres, des playlists, un sélecteur de temps, des boutons "J'aime" et "Je n'aime pas") pour améliorer l'expérience vidéo Picture-in-picture de l'utilisateur.

Visioconférence

Il est courant que les utilisateurs quittent l'onglet du navigateur pendant une visioconférence pour diverses raisons (par exemple, pour présenter un autre onglet à l'appel ou pour effectuer plusieurs tâches à la fois) tout en souhaitant continuer à voir l'appel. C'est donc un cas d'utilisation idéal pour le mode Picture-in-picture. Une fois de plus, l'expérience actuelle qu'un site Web de visioconférence peut offrir via l'API Picture-in-picture pour <video> est limitée en termes de style et d'entrée. Avec un document complet en mode Picture-in-picture, le site Web peut facilement combiner plusieurs flux vidéo dans une seule fenêtre PIP sans avoir à recourir à des hacks de canevas et fournir des commandes personnalisées telles que l'envoi d'un message, la désactivation du son d'un autre utilisateur ou la levée de la main.

Productivité

Des études ont montré que les utilisateurs ont besoin de plus de moyens pour être productifs sur le Web. Le mode Picture-in-picture pour les documents permet aux applications Web d'être plus flexibles et d'en faire plus. Qu'il s'agisse d'édition de texte, de prise de notes, de listes de tâches, de messagerie et de chat, ou d'outils de conception et de développement, les applications Web peuvent désormais rendre leur contenu toujours accessible.

Interface

Propriétés

documentPictureInPicture.window

Renvoie la fenêtre Picture-in-picture actuelle, le cas échéant. Sinon, renvoie null.

Méthodes

documentPictureInPicture.requestWindow(options)

Renvoie une promesse qui se résout lorsqu'une fenêtre Picture-in-picture est ouverte. La promesse est rejetée si elle est appelée sans geste de l'utilisateur. Le dictionnaire options contient les membres facultatifs suivants :

width

Définit la largeur initiale de la fenêtre Picture-in-picture.

height

Définit la hauteur initiale de la fenêtre Picture-in-picture.

disallowReturnToOpener

Masque le bouton "Retour à l'onglet" dans la fenêtre Picture-in-picture si la valeur est "true". La valeur par défaut est "false".

preferInitialWindowPlacement

Ouvre la fenêtre Picture-in-picture dans sa position et sa taille par défaut si la valeur est "true". La valeur par défaut est "false".

Événements

documentPictureInPicture.onenter

Déclenché sur documentPictureInPicture lorsqu'une fenêtre Picture-in-picture est ouverte.

Exemples

Le code HTML suivant configure un lecteur vidéo personnalisé et un élément de bouton permettant d'ouvrir le lecteur vidéo dans une fenêtre Picture-in-picture.

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

Ouvrir une fenêtre Picture-in-picture

Les appels JavaScript suivants documentPictureInPicture.requestWindow() lorsque l'utilisateur clique sur le bouton pour ouvrir une fenêtre Picture-in-Picture vide. La promesse renvoyée est résolue avec un objet JavaScript de fenêtre Picture-in-Picture. Le lecteur vidéo est déplacé vers cette fenêtre à l'aide de 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);
});

Définir la taille de la fenêtre Picture-in-picture

Pour définir la taille de la fenêtre Picture-in-picture, définissez les options width et height de documentPictureInPicture.requestWindow() sur la taille souhaitée. Chrome peut limiter les valeurs des options si elles sont trop grandes ou trop petites pour s'adapter à une taille de fenêtre conviviale.

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

Masquer le bouton "Retour à l'onglet" de la fenêtre Picture-in-picture

Pour masquer le bouton de la fenêtre Picture-in-Picture qui permet à l'utilisateur de revenir à l'onglet d'ouverture, définissez l'option disallowReturnToOpener de documentPictureInPicture.requestWindow() sur 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,
  });
});

Ouvrir la fenêtre Picture-in-picture dans sa position et sa taille par défaut

Pour ne pas réutiliser la position ni la taille de la fenêtre Picture-in-picture précédente, définissez l'option preferInitialWindowPlacement de documentPictureInPicture.requestWindow() sur true.

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

Copier des feuilles de style dans la fenêtre Picture-in-picture

Pour copier toutes les feuilles de style CSS de la fenêtre d'origine, parcourez styleSheets explicitement lié ou intégré au document, puis ajoutez-les à la fenêtre Picture-in-picture. Notez qu'il s'agit d'une copie unique.

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

Gérer la fermeture de la fenêtre Picture-in-picture

Écoutez l'événement "pagehide" de la fenêtre pour savoir quand la fenêtre Picture-in-picture est fermée (soit parce que le site Web l'a initiée, soit parce que l'utilisateur l'a fermée manuellement). Le gestionnaire d'événements est un bon endroit pour récupérer les éléments de la fenêtre Picture-in-picture, comme indiqué ici.

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

Fermez la fenêtre Picture-in-picture de manière programmatique à l'aide de la méthode close().

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

Écouter quand le site Web passe en mode Picture-in-picture

Écoutez l'événement "enter" sur documentPictureInPicture pour savoir quand une fenêtre Picture-in-picture est ouverte. L'événement contient un objet window pour accéder à la fenêtre Picture-in-picture.

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

Accéder aux éléments de la fenêtre Picture-in-picture

Accédez aux éléments de la fenêtre Picture-in-picture à partir de l'objet renvoyé par documentPictureInPicture.requestWindow() ou avec documentPictureInPicture.window, comme indiqué ci-dessous.

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

Gérer les événements de la fenêtre Picture-in-picture

Créez des boutons et des commandes, et répondez aux événements d'entrée utilisateur tels que "click" comme vous le feriez normalement en 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);

Redimensionner la fenêtre Picture-in-picture

Utilisez les méthodes Window resizeBy() et resizeTo() pour redimensionner la fenêtre Picture-in-picture. Les deux méthodes nécessitent un geste de l'utilisateur.

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

Sélectionner la fenêtre d'ouverture

Utilisez la méthode focus() Window pour sélectionner la fenêtre d'ouverture à partir de la fenêtre Picture-in-picture. Cette méthode nécessite un geste de l'utilisateur.

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

Mode Picture-in-picture CSS

Utilisez le mode d'affichage CSS picture-in-picture pour écrire des règles CSS spécifiques qui ne sont appliquées que lorsqu'une partie ou l'intégralité de l'application Web est affichée en mode Picture-in-picture.

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

Détection de caractéristiques

Pour vérifier si l'API Picture-in-Picture de documents est prise en charge, utilisez :

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

Démonstrations

Lecteur VideoJS

Vous pouvez tester l'API Picture-in-Picture de document avec la démonstration du lecteur VideoJS.

Pomodoro

Tomodoro, une application Web Pomodoro, utilise également l'API Document Picture-in-Picture lorsqu'elle est disponible. Consultez sa demande d'extraction GitHub.

Envoyer des commentaires

Créez des demandes sur GitHub pour nous faire part de vos suggestions et poser vos questions.

Liens utiles

• Explication publique
• Spécification WICG
• Bug de suivi Chromium
• Entrée ChromeStatus.com
• Composant Blink : Blink>Media>PictureInPicture
• Examen du TAG
• Intention de tester
• Intention d'expédier