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 pouvant être remplie de contenu HTML arbitraire. Elle étend l'API Picture-in-picture pour <video> existante, qui ne permet de placer qu'un élément <video> HTML dans une fenêtre Picture-in-picture.

La fenêtre Picture-in-picture de l'API Picture-in-picture de document est semblable à une fenêtre vierge 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 n'est jamais plus longue que la fenêtre d'ouverture.
• 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 en mode Picture-in-Picture avec l'API Picture-in-Picture pour <video> existante, mais elle est très limitée. La fenêtre Picture-in-picture existante n'accepte que peu d'entrées et ne permet pas de les styliser de manière très poussée. 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 curseur de défilement, des "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 session de visioconférence pour diverses raisons (par exemple, présenter un autre onglet à l'appel ou effectuer plusieurs tâches à la fois) tout en souhaitant continuer à voir l'appel. Il s'agit donc d'un cas d'utilisation idéal pour Picture-in-picture. Encore une fois, l'expérience actuelle qu'un site Web de visioconférence peut fournir 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 à utiliser des hacks de canevas et fournir des commandes personnalisées telles que l'envoi d'un message, la mise en sourdine d'un autre utilisateur ou le fait de lever la main.

Productivité

Des recherches ont montré que les utilisateurs ont besoin de plus de moyens d'être productifs sur le Web. Le mode Picture-in-picture pour les documents offre aux applications Web plus de flexibilité pour accomplir plus de tâches. Qu'il s'agisse de la modification de texte, de la 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 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". Par défaut, il est défini sur "false".

preferInitialWindowPlacement

Ouvre la fenêtre Picture-in-picture dans sa position et sa taille par défaut si la valeur est "true". Par défaut, il est défini sur "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 pour 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

Le code JavaScript suivant appelle 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 de fenêtre Picture-in-picture 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 dans 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 à partir de la fenêtre d'origine, parcourez les styleSheets explicitement liés ou intégrés 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 déclenchée, soit parce que l'utilisateur l'a fermée manuellement). Le gestionnaire d'événements est un bon endroit pour faire sortir les éléments de la fenêtre Picture-in-picture, comme illustré 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 lorsque 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 de l'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 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 Window focus() 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 Picture-in-picture CSS

Utilisez le mode d'affichage CSS picture-in-picture pour écrire des règles CSS spécifiques qui ne s'appliquent que lorsque (une partie) de l'application Web s'affiche en mode Picture-in-Picture.

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

Détection de fonctionnalités

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

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

Démonstrations

Lecteur VideoJS

Vous pouvez tester la démonstration du lecteur VideoJS avec l'API Picture-in-Picture de Document. N'oubliez pas de consulter le code source.

Pomodoro

Tomodoro, une application Web de pomodoro, utilise également l'API Picture-in-Picture pour les documents lorsqu'elle est disponible. Consultez sa demande d'extraction GitHub.

Envoyer des commentaires

Signalez des problèmes sur GitHub en indiquant vos suggestions et vos questions.

Liens utiles

• Explication publique
• Spécification WICG
• Bug de suivi Chromium
• Enregistrement sur ChromeStatus.com
• Composant clignotement: Blink>Media>PictureInPicture
• Examen du TAG
• Intent to Experiment
• Intent to Ship