Document.pictureInPictureEnabled — Eigenschaft · JavaScript-Referenz

Signatur

Document.pictureInPictureEnabled

Beschreibung

Die Eigenschaft document.pictureInPictureEnabled gehört zur Picture-in-Picture-API und liefert true, wenn das Dokument Videos per HTMLVideoElement.requestPictureInPicture() in ein schwebendes, immer im Vordergrund liegendes Fenster auslagern darf. Andernfalls ist der Wert false.

Der Wert kann aus mehreren Gründen false sein: Der Nutzer hat die Funktion in den Browsereinstellungen abgeschaltet, eine Permissions Policy (picture-in-picture) verbietet sie – etwa in einem <iframe> ohne passendes allow-Attribut – oder die Plattform unterstützt den Modus grundsätzlich nicht.

Typischer Einsatz: Vor dem Anzeigen eines eigenen „Bild-in-Bild“-Buttons in einem Videoplayer prüfen, ob die Funktion verfügbar ist, und den Button sonst ausblenden oder deaktivieren. Zusätzlich sollte man das Attribut disablePictureInPicture des jeweiligen Videos berücksichtigen.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn der Bild-in-Bild-Modus im Dokument verfügbar ist, sonst false. In Browsern ohne Unterstützung der API ist die Eigenschaft undefined.

Beispiele

Einfache Verfügbarkeitsprüfung

// Prüft Unterstützung und Freigabe in einem Schritt
const pipAvailable = 'pictureInPictureEnabled' in document && document.pictureInPictureEnabled;
console.log(`Bild-in-Bild verfügbar: ${pipAvailable}`);

Bild-in-Bild verfügbar: true

PiP-Button nur bei Verfügbarkeit anzeigen

const video = document.querySelector('#player');
const pipButton = document.querySelector('#pip-button');

const canUsePip = () =>
  document.pictureInPictureEnabled === true && !video.disablePictureInPicture;

pipButton.hidden = !canUsePip();

pipButton.addEventListener('click', async () => {
  try {
    if (document.pictureInPictureElement) {
      await document.exitPictureInPicture();
    } else {
      await video.requestPictureInPicture();
    }
  } catch (err) {
    console.error('Bild-in-Bild fehlgeschlagen:', err.name, err.message);
  }
});

Button-Zustand an Metadaten des Videos koppeln

const video = document.querySelector('video');
const button = document.querySelector('#pip-button');

const updateButton = () => {
  // Ohne geladene Metadaten schlägt requestPictureInPicture() fehl
  button.disabled = !document.pictureInPictureEnabled || video.readyState === 0;
};

video.addEventListener('loadedmetadata', updateButton);
video.addEventListener('emptied', updateButton);
updateButton();
console.log('Button deaktiviert:', button.disabled);

Button deaktiviert: true

// Wichtig · Fallstricke

Browser-Kompatibilität: Unterstützt in Chromium-Browsern (Chrome, Edge, Opera) und Safari. Firefox bietet zwar eine eigene Bild-in-Bild-Schaltfläche im Browser, implementiert die API aber nicht – dort ist document.pictureInPictureEnabled undefined. Daher immer per 'pictureInPictureEnabled' in document oder strengem Vergleich auf true prüfen.
iframes: In eingebetteten Frames ist der Wert false, wenn die Permissions Policy picture-in-picture nicht erlaubt ist. Lösung: <iframe allow="picture-in-picture">.
true garantiert keinen Erfolg: requestPictureInPicture() erfordert zusätzlich eine Nutzerinteraktion (transiente Aktivierung), geladene Metadaten und kein gesetztes disablePictureInPicture; sonst wird das Promise mit NotAllowedError bzw. InvalidStateError abgelehnt.
Die Eigenschaft ist schreibgeschützt; Zuweisungen werden ignoriert (im Strict Mode ggf. TypeError).
Für beliebige HTML-Inhalte statt Videos gibt es die neuere Document Picture-in-Picture API (window.documentPictureInPicture, nur Chromium).

Siehe auch

DocumentPictureInPictureEvent.window Document.pictureInPictureElement Document.fullscreenEnabled Document.documentElement Document.documentURI