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

François Beaufort

L'API Picture-in-Picture pour les documents 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 (PIP).

La fenêtre Picture-in-picture de l'API Document Picture-in-picture est semblable à une fenêtre vide de même origine ouverte à l'aide de 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

Cas d'utilisation

Vous pouvez utiliser cette API de différentes manières, y compris pour des lecteurs vidéo personnalisés, des applications de visioconférence et des applications de productivité.

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 PIP existante accepte peu d'entrées et offre des possibilités de style limitées. Avec un document complet en mode 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 temporel, des options "J'aime" et "Je n'aime pas" pour les vidéos) afin d'améliorer l'expérience vidéo PiP de l'utilisateur.

Visioconférence

Les utilisateurs quittent souvent temporairement l'onglet du navigateur pendant une session de visioconférence, par exemple lorsqu'ils présentent un contenu depuis un autre onglet, prennent des notes ou effectuent d'autres activités multitâches. Toutefois, dans la plupart des cas, l'utilisateur souhaite toujours voir l'appel. Il s'agit donc d'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 avec l'API Picture-in-Picture pour <video> est limitée en termes de style et de saisie. 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 recours à des hacks de canevas, et fournir des commandes personnalisées, comme 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 document en Picture-in-picture offre aux applications Web la flexibilité nécessaire pour accomplir davantage de tâches. 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 idéale de la fenêtre PIP. Chrome peut réduire 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" dans la fenêtre PIP

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 le mode PIP à la position et à la 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 les feuilles de style dans le mode PIP

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 PIP

É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 PIP

É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 PIP

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

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 PIP

Créez des boutons et des commandes, et répondez aux événements de saisie de l'utilisateur (comme "click"), comme toujours 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 PIP

Utilisez les méthodes de fenêtre 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 d'affichage PiP 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 des fonctionnalités

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 : testez l'API Document Picture-in-Picture avec la démonstration du lecteur VideoJS.
• Tomodoro, une application Web Pomodoro, tire parti de l'API Document Picture-in-Picture lorsqu'elle est disponible. Consultez leur demande d'extraction GitHub.

Envoyer des commentaires

Créez des demandes sur GitHub pour nous faire part de vos suggestions et de 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