Signatur
Beschreibung
Die Eigenschaft disablePictureInPicture eines <video>-Elements gibt an, ob der Browser das Video im Bild-im-Bild-Modus (engl. Picture-in-Picture, kurz PiP) anzeigen darf. Sie spiegelt das boolesche HTML-Attribut disablepictureinpicture wider. Wenn Sie die Eigenschaft auf true setzen, wird das Attribut gesetzt. Bei false wird es entfernt.
Ist die Eigenschaft true, blendet der Browser seine eigenen PiP-Bedienelemente aus, etwa den Eintrag im Kontextmenü oder die Schaltfläche in den Standard-Steuerelementen. Außerdem schlägt ein Aufruf von HTMLVideoElement.requestPictureInPicture() fehl: Das zurückgegebene Promise wird mit einer DOMException vom Typ InvalidStateError zurückgewiesen.
Typische Einsatzfälle:
- Hintergrund- oder Deko-Videos: Stumme Videos, die automatisch in einer Schleife laufen, ergeben in einem schwebenden Fenster keinen Sinn.
- Werbung: Werbe-Clips sollen nicht aus der Seite herausgelöst werden.
- Eigene Player-Logik: Die App will selbst steuern, wann PiP verfügbar ist, zum Beispiel erst nach dem Login oder nur für bestimmte Inhalte.
Die Eigenschaft ist ein Hinweis an den Browser, aber kein Kopierschutz. Browser-Erweiterungen oder eigene Browser-Funktionen können sie umgehen.
Rückgabewert
true, wenn das Attribut disablepictureinpicture gesetzt ist und PiP damit deaktiviert ist, sonst false (Standardwert). Die Eigenschaft ist les- und schreibbar.Beispiele
PiP für ein Hintergrundvideo abschalten
// HTML: <video id="hero" autoplay muted loop src="hero.mp4"></video>
const hero = document.querySelector('#hero');
hero.disablePictureInPicture = true;
console.log(hero.disablePictureInPicture);
console.log(hero.hasAttribute('disablepictureinpicture'));Wirkung auf requestPictureInPicture() prüfen
const video = document.querySelector('video');
video.disablePictureInPicture = true;
try {
await video.requestPictureInPicture();
} catch (err) {
console.log(err.name); // PiP ist gesperrt
}Eigene PiP-Schaltfläche passend ein- und ausblenden
const video = document.querySelector('#player');
const pipButton = document.querySelector('#pip-button');
const updatePipButton = () => {
const supported = 'pictureInPictureEnabled' in document && document.pictureInPictureEnabled;
pipButton.hidden = !supported || video.disablePictureInPicture;
};
// Beispiel: PiP erst nach dem Login freigeben
const onLogin = () => {
video.disablePictureInPicture = false;
updatePipButton();
};
pipButton.addEventListener('click', async () => {
if (document.pictureInPictureElement) {
await document.exitPictureInPicture();
} else {
await video.requestPictureInPicture();
}
});
video.disablePictureInPicture = true;
updatePipButton();Laufenden PiP-Modus beim Sperren sauber beenden
const lockPip = async (video) => {
video.disablePictureInPicture = true;
// Nicht darauf verlassen, dass der Browser das Fenster selbst schließt
if (document.pictureInPictureElement === video) {
await document.exitPictureInPicture();
}
};
await lockPip(document.querySelector('video'));
console.log(document.pictureInPictureElement);// Wichtig · Fallstricke
Browser-Kompatibilität: Chromium-basierte Browser (Chrome, Edge, Opera) unterstützen die Eigenschaft seit Version 76 bzw. 79. Firefox unterstützt die Standard-PiP-API nicht und ignoriert das Attribut. Die eigene PiP-Schaltfläche von Firefox lässt sich damit also nicht zuverlässig ausblenden. Safari hat eine eigene, abweichende Umsetzung (webkitSetPresentationMode()). Prüfen Sie die Unterstützung vorher per Feature-Erkennung, z. B. mit 'disablePictureInPicture' in HTMLVideoElement.prototype.
- Laufendes PiP-Fenster: Setzen Sie die Eigenschaft auf
true, während das Video schon im PiP-Modus läuft, ist nicht garantiert, dass der Browser das Fenster schließt. Rufen Sie in diesem Fall selbstdocument.exitPictureInPicture()auf. - Boolesches Attribut: Im HTML zählt nur, ob das Attribut vorhanden ist. Auch
disablepictureinpicture="false"deaktiviert PiP. Zum Aktivieren entfernen Sie das Attribut oder setzen die Eigenschaft auffalse. - Kein Schutzmechanismus: Die Eigenschaft verhindert nicht zuverlässig, dass Inhalte herausgelöst oder mitgeschnitten werden. Für geschützte Inhalte brauchen Sie DRM (Encrypted Media Extensions).
- Die Eigenschaft wirkt nur auf
<video>-Elemente, nicht auf<audio>.