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 Document Picture-in-picture est semblable à une fenêtre vide de même origine ouverte via window.open(), à quelques différences près:

• 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.
• Le site Web ne peut pas définir la position de la fenêtre Picture-in-picture.

État actuel

Cas d'utilisation

Lecteur vidéo personnalisé

Un site Web peut fournir une expérience vidéo 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 études ont montré que les utilisateurs ont besoin de moyens supplémentaires pour ê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. Éditeur de texte, prise de notes, listes de tâches, messagerie et chat, outils de conception et de développement... Le contenu des applications Web reste 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 refusé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". 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 avec 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 depuis la fenêtre d'origine, faites une boucle dans les styleSheets explicitement liées au document ou intégrées dans celui-ci, 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 idéal pour extraire 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 par programmation à 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 sont appliquées que lorsque (en partie) 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 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 du format Web Ink Canvas
• Bug de suivi Chromium
• Enregistrement sur ChromeStatus.com
• Composant clignotement : Blink>Media>PictureInPicture
• Examen du TAG
• Intention de test
• Intent to Ship