L'API Document Picture-in-picture permet d'ouvrir une fenêtre toujours affichée en haut à droite de celle-ci, qui peut contenir du contenu HTML arbitraire. Elle étend l'API Picture-in-picture pour <video>, qui permet uniquement d'insérer 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 ne survit jamais à la fenêtre d'ouverture.
- Il n'est pas possible 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
| Step | État |
|---|---|
| 1. Créer une vidéo explicative | Fin |
| 2. Créer un brouillon initial de la spécification | En cours |
| 3. Recueillir des commentaires et itérer sur la conception | En cours |
| 4. Phase d'évaluation | Fin |
| 5. Lancement | Terminé (ordinateur) |
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>, mais cette fonctionnalité est très limitée. La fenêtre Picture-in-picture existante accepte peu d'entrées et sa capacité à les styliser est limitée. Avec un document complet en mode Picture-in-picture, le site Web peut fournir des commandes et des informations personnalisées (par exemple, les sous-titres, les playlists, la barre de lecture temporelle et les mentions "J'aime" et "Je n'aime pas") afin d'améliorer l'expérience vidéo 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, pour présenter un autre onglet lors d'un appel ou pour effectuer plusieurs tâches en même temps), tout en souhaitant quand même voir l'appel. Il s'agit donc d'un cas d'utilisation privilégié pour la fonctionnalité Picture-in-picture. Là encore, l'expérience 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ées. Avec la fonctionnalité Document en Picture-in-picture complète, le site Web peut facilement combiner plusieurs flux vidéo dans une seule fenêtre PIP sans avoir à recourir au piratage de canevas, et fournir des commandes personnalisées telles que l'envoi d'un message, la coupure du son d'un autre utilisateur ou la lever la main.
Productivité
Des études ont montré que les utilisateurs avaient besoin de moyens supplémentaires pour être productifs sur le Web. Document en Picture-in-picture permet aux applications Web d'en faire toujours plus. Qu'il s'agisse d'édition de texte, de prise de notes, de listes de tâches, de messagerie et de chat, ou encore d'outils de conception et de développement, les applications Web peuvent désormais maintenir 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 résolue 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
optionscontient 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 définie sur "true". Par défaut, cette valeur est "false".
Événements
documentPictureInPicture.onenter- Déclenché le
documentPictureInPicturelorsqu'une fenêtre Picture-in-picture est ouverte.
Exemples
Le code HTML ci-dessous permet de configurer un lecteur vidéo personnalisé et un élément 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 se résout avec un objet JavaScript de fenêtre Picture-in-picture. Le lecteur vidéo est déplacé dans 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 permettant à l'utilisateur de revenir à l'onglet de l'application dans la fenêtre Picture-in-picture, 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,
});
});
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, effectuez une lecture en boucle de styleSheets qui est explicitement liée ou intégrée dans le 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 se ferme (soit parce que le site Web l'a à l'origine, soit parce que l'utilisateur l'a fermée manuellement). Le gestionnaire d'événements est idéal pour récupérer les éléments de la fenêtre Picture-in-picture, comme illustré ci-dessous.
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 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 permettant d'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 à partir 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 resizeBy() et resizeTo() Window 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 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 Document Picture-in-picture est compatible, utilisez:
if ('documentPictureInPicture' in window) {
// The Document Picture-in-Picture API is supported.
}
Démonstrations
Lecteur VideoJS
Vous pouvez utiliser la démo du lecteur VideoJS de l'API Document Picture-in-picture. Pensez à vérifier le code source.
Pomodoro
Tomodoro, une application Web pomodoro, exploite également l'API Document Picture-in-picture lorsqu'elle est disponible (voir la requête d'extraction GitHub).
Commentaires
Veuillez signaler des problèmes sur GitHub en nous envoyant des suggestions et des questions.
Liens utiles
- Explication publique
- Spécification WiCG
- Bug de suivi Chromium
- Entrée ChromeStatus.com
- Composant Blink:
Blink>Media>PictureInPicture - Examen de la balise
- Intention de test
- Intention d'expédition
Remerciements
Image principale de Jakob Owens.