Verwendung der Document Picture-in-Picture API
Dieser Leitfaden bietet eine schrittweise Anleitung zur typischen Nutzung der Document Picture-in-Picture API.
Hinweis: Sie können das vorgestellte Demo in Aktion unter Document Picture-in-Picture API Example sehen (siehe auch den vollständigen Quellcode).
Beispiel-HTML
Das folgende HTML richtet einen einfachen Videoplayer ein.
<div id="container">
<p class="in-pip-message">
Video player is currently in the separate Picture-in-Picture window.
</p>
<div id="player">
<video
src="assets/bigbuckbunny.mp4"
id="video"
controls
width="320"></video>
<div id="credits">
<a href="https://peach.blender.org/download/" target="_blank">
Video by Blender </a
>;
<a href="https://peach.blender.org/about/" target="_blank">
licensed CC-BY 3.0
</a>
</div>
<div id="control-bar">
<p class="no-picture-in-picture">
Document Picture-in-Picture API not available
</p>
<p></p>
</div>
</div>
</div>
Funktionsprüfung
Um zu überprüfen, ob die Document Picture-in-Picture API unterstützt wird, kann getestet werden, ob documentPictureInPicture
auf window
verfügbar ist:
if ("documentPictureInPicture" in window) {
document.querySelector(".no-picture-in-picture").remove();
const togglePipButton = document.createElement("button");
togglePipButton.textContent = "Toggle Picture-in-Picture";
togglePipButton.addEventListener("click", togglePictureInPicture);
document.getElementById("control-bar").appendChild(togglePipButton);
}
Wenn es verfügbar ist, entfernen wir die Nachricht "Document Picture-in-Picture API nicht verfügbar" und fügen stattdessen ein <button>
-Element hinzu, um den Videoplayer in einem Document Picture-in-Picture-Fenster zu öffnen.
Öffnen eines Picture-in-Picture-Fensters
Das folgende JavaScript ruft window.documentPictureInPicture.requestWindow()
auf, um ein leeres Picture-in-Picture-Fenster zu öffnen. Das zurückgegebene Promise
wird mit einem Picture-in-Picture Window
-Objekt erfüllt. Der Videoplayer wird mit Element.append()
in dieses Fenster verschoben, und wir zeigen die Nachricht an, die den Nutzer darüber informiert, dass es verschoben wurde.
Die width
- und height
-Optionen von requestWindow()
setzen das Picture-in-Picture-Fenster auf die gewünschte Größe. Browser können die Optionswerte einschränken, wenn sie zu groß oder zu klein sind, um eine benutzerfreundliche Fenstergröße zu gewährleisten.
async function togglePictureInPicture() {
// Early return if there's already a Picture-in-Picture window open
if (window.documentPictureInPicture.window) {
return;
}
// Open a Picture-in-Picture window.
const pipWindow = await window.documentPictureInPicture.requestWindow({
width: videoPlayer.clientWidth,
height: videoPlayer.clientHeight,
});
// …
// Move the player to the Picture-in-Picture window.
pipWindow.document.body.append(videoPlayer);
// Display a message to say it has been moved
inPipMessage.style.display = "block";
}
Kopieren von Stylesheets in das Picture-in-Picture-Fenster
Um alle CSS-Stylesheets vom auslösenden Fenster zu kopieren, durchlaufen Sie alle Stylesheets, die explizit in das Dokument eingebunden oder eingebettet sind (über Document.styleSheets
), und fügen Sie sie dem Picture-in-Picture-Fenster hinzu. Beachten Sie, dass dies ein einmaliger Kopiervorgang ist.
// …
// 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);
}
});
// …
Zielstile im Picture-in-Picture-Modus
Der picture-in-picture
-Wert der display-mode
Medienfunktion ermöglicht es Entwicklern, CSS auf ein Dokument anzuwenden, basierend darauf, ob es im Picture-in-Picture-Modus angezeigt wird. Die grundlegende Nutzung sieht folgendermaßen aus:
@media (display-mode: picture-in-picture) {
body {
background: red;
}
}
Dies wird den Hintergrund des Dokuments <body>
nur dann rot färben, wenn es im Picture-in-Picture-Modus angezeigt wird.
In unserem Demo kombinieren wir den display-mode: picture-in-picture
-Wert mit der prefers-color-scheme
Medienfunktion, um helle und dunkle Farbschemata zu erstellen, die basierend auf der Farbschema-Präferenz des Nutzers angewendet werden, nur wenn die App im Picture-in-Picture-Modus angezeigt wird.
@media (display-mode: picture-in-picture) and (prefers-color-scheme: light) {
body {
background: antiquewhite;
}
}
@media (display-mode: picture-in-picture) and (prefers-color-scheme: dark) {
body {
background: #333333;
}
a {
color: antiquewhite;
}
}
Umgang mit dem Schließen des Picture-in-Picture-Fensters
Der Code zum erneuten Schließen des Picture-in-Picture-Fensters, wenn die Schaltfläche ein zweites Mal gedrückt wird, sieht folgendermaßen aus:
inPipMessage.style.display = "none";
playerContainer.append(videoPlayer);
window.documentPictureInPicture.window.close();
Hier kehren wir die DOM-Änderungen um – wir blenden die Nachricht aus und setzen den Videoplayer wieder in den Player-Container im Hauptanwendungsfenster zurück. Wir schließen das Picture-in-Picture-Fenster auch programmatisch mit der Methode Window.close()
.
Sie müssen jedoch auch den Fall berücksichtigen, dass der Benutzer das Picture-in-Picture-Fenster durch Drücken des vom Browser bereitgestellten UI-Schließbefehls im Fenster selbst schließt. Dies kann gehandhabt werden, indem erkannt wird, wann das Fenster mithilfe des pagehide
-Ereignisses geschlossen wird:
pipWindow.addEventListener("pagehide", (event) => {
inPipMessage.style.display = "none";
playerContainer.append(videoPlayer);
});
Hinweis:
Der vom Browser bereitgestellte UI-Schließbefehl kann verborgen werden, indem der disallowReturnToOpener
-Hinweis auf true
gesetzt wird, wenn die DocumentPictureInPicture.requestWindow()
-Methode zum ersten Öffnen des Picture-in-Picture-Fensters aufgerufen wird.
Hören, wenn die Website den Picture-in-Picture-Modus betritt
Hören Sie auf das enter
-Ereignis auf der DocumentPictureInPicture
-Instanz, um zu wissen, wann ein Picture-in-Picture-Fenster geöffnet wird.
In unserem Demo verwenden wir das enter
-Ereignis, um eine Stummschalttaste zum Picture-in-Picture-Fenster hinzuzufügen:
documentPictureInPicture.addEventListener("enter", (event) => {
const pipWindow = event.window;
console.log("Video player has entered the pip window");
const pipMuteButton = pipWindow.document.createElement("button");
pipMuteButton.textContent = "Mute";
pipMuteButton.addEventListener("click", () => {
const pipVideo = pipWindow.document.querySelector("#video");
if (!pipVideo.muted) {
pipVideo.muted = true;
pipMuteButton.textContent = "Unmute";
} else {
pipVideo.muted = false;
pipMuteButton.textContent = "Mute";
}
});
pipWindow.document.body.append(pipMuteButton);
});
Hinweis:
Das DocumentPictureInPictureEvent
-Ereignisobjekt enthält eine window
-Eigenschaft, um auf das Picture-in-Picture-Fenster zuzugreifen.
Zugriff auf Elemente und Ereignisse behandeln
Sie können auf Elemente im Picture-in-Picture-Fenster auf verschiedene Weise zugreifen:
- Die
Window
-Instanz, die von der MethodeDocumentPictureInPicture.requestWindow()
zurückgegeben wird, wie oben gezeigt. - Über die
window
-Eigenschaft desDocumentPictureInPictureEvent
-Ereignisobjekts (auf dementer
-Ereignis), wie oben gezeigt. - Über die
DocumentPictureInPicture.window
-Eigenschaft:
const pipWindow = window.documentPictureInPicture.window;
if (pipWindow) {
// Mute video playing in the Picture-in-Picture window.
const pipVideo = pipWindow.document.querySelector("#video");
pipVideo.muted = true;
}
Sobald Sie eine Referenz auf die Picture-in-Picture-window
-Instanz haben, können Sie das DOM manipulieren (zum Beispiel Schaltflächen erstellen) und auf Benutzereingabeereignisse (wie click
) wie gewohnt im regulären Browserfensterkontext reagieren.