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:

  1. Sie müssen den Austausch von Zustandsinformationen zwischen den beiden Fenstern handhaben.
  2. 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, der picture-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