Signatur
Beschreibung
Die Eigenschaft poster spiegelt das HTML-Attribut poster eines <video>-Elements wider. Sie enthält die URL eines Bildes, das der Browser anzeigt, solange noch kein Videobild zur Verfügung steht, also vor dem Laden, vor dem ersten Abspielen oder wenn das Video nicht geladen werden kann.
Beim Lesen liefert die Eigenschaft die aufgelöste, absolute URL, auch wenn im Attribut ein relativer Pfad steht. Ist kein Attribut gesetzt, bekommt man einen leeren String "". Beim Schreiben wird das Attribut poster aktualisiert, und der Browser lädt das neue Bild.
Typische Einsatzfälle sind dynamische Videoplayer, Playlists mit eigenem Vorschaubild pro Clip, Lazy-Loading (erst Poster zeigen, dann bei Bedarf das Video laden) sowie Platzhalter bei preload="none", damit keine schwarze Fläche zu sehen ist.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $value | string | "" | Beim Setzen: URL (relativ oder absolut) des Bildes, das als Vorschaubild dienen soll. Ein leerer String entfernt praktisch das Poster, das Attribut selbst bleibt aber bestehen. |
Rückgabewert
"", wenn kein poster-Attribut gesetzt ist.Beispiele
Poster auslesen (relative URL wird aufgelöst)
// HTML: <video id="clip" src="intro.mp4" poster="img/intro.jpg" controls></video>
const video = document.querySelector('#clip');
console.log(video.poster); // absolute URL
console.log(video.getAttribute('poster')); // Originalwert aus dem AttributPlaylist: Video und Poster gemeinsam wechseln
const playlist = [
{ src: 'videos/teil1.mp4', poster: 'posters/teil1.jpg' },
{ src: 'videos/teil2.mp4', poster: 'posters/teil2.jpg' }
];
const video = document.querySelector('video');
const loadClip = (index) => {
const { src, poster } = playlist[index];
video.poster = poster; // zuerst das Vorschaubild setzen
video.src = src;
video.load(); // Poster wird angezeigt, bis Daten da sind
};
loadClip(1);
console.log(video.poster.endsWith('posters/teil2.jpg'));Lazy-Video mit Poster erzeugen und Poster entfernen
const video = document.createElement('video');
video.preload = 'none'; // keine Videodaten vorab laden
video.poster = '/img/vorschau.webp';
video.controls = true;
video.src = '/media/film.mp4';
document.body.append(video);
console.log(video.hasAttribute('poster')); // true
// Poster später vollständig entfernen:
video.removeAttribute('poster');
console.log(JSON.stringify(video.poster));// Wichtig · Fallstricke
- Absolute URL beim Lesen:
video.posterliefert immer die aufgelöste URL. Wer den Originalwert aus dem Markup braucht, nimmtgetAttribute('poster'). Vergleiche mit relativen Pfaden schlagen deshalb fehl. - Entfernen:
video.poster = ''lässt das Attribut leer stehen. Um es ganz zu entfernen, nutzt manremoveAttribute('poster'). - Anzeigedauer: Das Poster verschwindet, sobald das erste Videobild gezeigt wird, spätestens bei der Wiedergabe. Ohne Poster zeigen viele Browser bei
preload="metadata"oder"auto"das erste Frame, beipreload="none"dagegen nur eine leere Fläche. Nach dem Abspielen erscheint das Poster erst wieder, wennload()aufgerufen wird. - Seitenverhältnis: Das Poster wird im Seitenverhältnis des Videoelements eingepasst (wie
object-fit: contain). Wenn die Maße abweichen, entstehen Balken. Deshalb sollte das Posterbild dieselben Proportionen wie das Video haben. - Sicherheit/CSP: Das Posterbild wird wie ein Bild geladen und unterliegt der CSP-Direktive
img-src, nichtmedia-src. URLs aus Benutzereingaben sollte man prüfen, damit keine Tracking-Pixel oder unerwünschten Fremdquellen eingebunden werden. - Kompatibilität: Wird von allen modernen Browsern unterstützt. Auf manchen mobilen Geräten kann der Browser das Poster durch eigene Steuerelemente überlagern oder im Vollbild ausblenden.