Document Picture-in-Picture API
Limited availability
This feature is not Baseline because it does not work in some of the most widely-used browsers.
Experimentell: Dies ist eine experimentelle Technologie
Überprüfen Sie die Browser-Kompatibilitätstabelle sorgfältig, bevor Sie diese produktiv verwenden.
Sicherer Kontext: Diese Funktion ist nur in sicheren Kontexten (HTTPS) in einigen oder allen unterstützenden Browsern verfügbar.
Die Document Picture-in-Picture API ermöglicht das Öffnen eines immer im Vordergrund befindlichen Fensters, das mit beliebigem HTML-Inhalt gefüllt werden kann — zum Beispiel ein Video mit benutzerdefinierten Steuerelementen oder eine Reihe von Streams, die die Teilnehmer eines Videokonferenzanrufs zeigen. Sie erweitert die frühere Picture-in-Picture API für <video>
, die es speziell ermöglicht, ein HTML <video>
-Element in ein immer im Vordergrund befindliches Fenster zu platzieren.
Konzepte und Nutzung
Es ist oft hilfreich, für eine Web-App ein anderes Fenster zur Verfügung zu haben, zusätzlich zum Hauptfenster, in dem die App läuft. Sie möchten möglicherweise andere Fenster durchsuchen, während Sie bestimmte App-Inhalte im Blick behalten, oder Sie möchten diesen Inhalten ihren eigenen Raum geben, während das Haupt-App-Fenster frei bleibt, um andere Inhalte anzuzeigen. Sie könnten dies einfach durch das Öffnen eines normalen neuen Browserfensters handhaben, aber das hat zwei wesentliche Probleme:
- Sie müssen den Austausch von Zustandsinformationen zwischen den beiden Fenstern handhaben.
- Das zusätzliche App-Fenster bleibt nicht immer im Vordergrund und kann daher von anderen Fenstern verdeckt werden.
Um diese Probleme zu lösen, haben Webbrowser APIs eingeführt, die es Apps ermöglichen, ein immer im Vordergrund befindliches Fenster zu öffnen, das Teil derselben Sitzung ist. Der erste anerkannte Anwendungsfall war, Videoinhalte in einem separaten Fenster weiter abzuspielen, sodass der Benutzer sie konsumieren kann, während er andere Inhalte ansieht. Dies wird mittels der Picture-in-Picture API für <video>
gehandhabt, die direkt auf ein <video>
-Element angewendet wird, um es in das separate Fenster zu platzieren.
Diese API wurde jedoch als etwas einschränkend empfunden — Sie können nur ein einzelnes <video>
-Element in das immer im Vordergrund befindliche Fenster setzen, mit minimalen browsergenerierten Steuerelementen. Um mehr Flexibilität zu bieten, wurde die Document Picture-in-Picture API eingeführt. Dies ermöglicht es, beliebige Inhalte in das immer im Vordergrund befindliche Fenster zu platzieren, für eine breite Palette von Anwendungsfällen, einschließlich:
- Ein immer im Vordergrund befindlicher benutzerdefinierter Videoplayer, der ein oder mehrere Videos mit benutzerdefinierten Steuerelementen und Styling zeigt.
- Ein Videokonferenzsystem, das dem Benutzer ermöglicht, die Streams des anderen Teilnehmers immer zu sehen, sowie Steuerelemente zum Präsentieren von Inhalten, Stummschalten, Beenden von Anrufen usw.
- Immer sichtbare Produktivitätstools wie Timer, Notizen, To-Do-Listen, Messenger-Tools usw.
- Ein separates Fenster, in dem zusätzliche Inhalte gehalten werden, während das Haupt-App-Fenster von Unordnung frei bleibt. Zum Beispiel könnten Sie ein Aktions- oder Rollenspiel laufen haben, bei dem Sie die Spielsteuerung, Anleitungen oder Überlieferungen in einem zusätzlichen Fenster anzeigen möchten, während das Hauptfenster für die Darstellung der Spielorte und -karten frei bleibt.
Wie funktioniert es?
Eine neue Instanz des DocumentPictureInPicture
-Objekts, das das immer im Vordergrund befindliche Picture-in-Picture-Fenster für den aktuellen Dokumentkontext darstellt, ist über Window.documentPictureInPicture
verfügbar. Das Picture-in-Picture-Fenster wird durch Aufrufen der Methode DocumentPictureInPicture.requestWindow()
geöffnet, die ein Promise
zurückgibt, das mit dem eigenen Window
-Objekt des Fensters erfüllt wird.
Das Picture-in-Picture-Fenster ähnelt einem leeren gleich-origin-Fenster, das über Window.open()
geöffnet wurde, mit einigen Unterschieden:
- Das Picture-in-Picture-Fenster schwebt über anderen Fenstern.
- Das Picture-in-Picture-Fenster lebt nie länger als das eröffnende Fenster.
- Das Picture-in-Picture-Fenster kann nicht navigiert werden.
- Die Position des Picture-in-Picture-Fensters kann nicht von der Website festgelegt werden.
- Das Picture-in-Picture-Fenster ist auf eines pro Browser-Tab zu einem Zeitpunkt beschränkt, wobei der Benutzeragent möglicherweise die globale Anzahl der geöffneten Picture-in-Picture-Fenster weiter einschränkt.
Abgesehen davon können Sie die Window
-Instanz des Picture-in-Picture-Fensters beliebig manipulieren, indem Sie beispielsweise die dort anzuzeigenden Inhalte an sein DOM anhängen und Stylesheets darauf kopieren, sodass der angehängte Inhalt genauso gestylt wird, wie wenn er im Hauptfenster ist. Sie können das Picture-in-Picture-Fenster auch schließen (durch Klicken auf das vom Browser bereitgestellte Steuerelement oder durch Ausführen von Window.close()
darauf) und dann darauf reagieren, dass es mit dem Standard-Event pagehide
geschlossen wird. Wenn es geschlossen wird, möchten Sie den von ihm gezeigten Inhalt in das Haupt-App-Fenster zurücklegen.
Siehe Using the Document Picture-in-Picture API für einen detaillierten Nutzungsleitfaden.
Schnittstellen
DocumentPictureInPicture
-
Der Einstiegspunkt zum Erstellen und Handhaben von Dokument-Picture-in-Picture-Fenstern.
DocumentPictureInPictureEvent
-
Event-Objekt für das
enter
-Event, das ausgelöst wird, wenn das Picture-in-Picture-Fenster geöffnet wird.
Erweiterungen zu anderen Schnittstellen
Window.documentPictureInPicture
-
Gibt eine Referenz auf das
DocumentPictureInPicture
-Objekt für den aktuellen Dokumentkontext zurück.
Zusätze zu CSS
display-mode
, derpicture-in-picture
-Wert-
Ein CSS Media-Feature-Wert, der es Entwicklern ermöglicht, CSS auf ein Dokument anzuwenden, basierend darauf, ob es im Picture-in-Picture-Modus angezeigt wird.
Beispiele
Siehe Document Picture-in-Picture API Beispiel für eine vollständige funktionierende Demo (sehen Sie sich auch den vollständigen Quellcode an).
Spezifikationen
Specification |
---|
Document Picture-in-Picture # dom-window-documentpictureinpicture |
Browser-Kompatibilität
BCD tables only load in the browser