HTMLPictureElement — Schnittstelle · JavaScript-Referenz

Signatur

interface HTMLPictureElement extends HTMLElement

Beschreibung

HTMLPictureElement ist die DOM-Schnittstelle des <picture>-Elements. Das Element enthält kein eigenes Bild. Es ist ein Container für null oder mehr <source>-Elemente und genau ein <img>-Element. Der Browser prüft die <source>-Elemente der Reihe nach und nimmt die erste Quelle, deren media- und type-Bedingung passt. Die gewählte URL lädt und zeigt am Ende immer das <img>-Element an.

Die Schnittstelle erbt alle Eigenschaften und Methoden von HTMLElement, fügt aber keine eigenen hinzu. In der Praxis arbeitest du deshalb fast immer mit den Kindelementen: mit HTMLSourceElement (srcset, media, type, sizes) und mit HTMLImageElement (currentSrc, alt, load-Ereignis).

Typische Einsätze:

Art Direction: Je nach Bildschirmbreite wird ein anderer Bildausschnitt gezeigt, z. B. Hochformat auf dem Handy und Querformat auf dem Desktop.
Formatauswahl: Moderne Formate wie AVIF oder WebP werden bevorzugt. Browser ohne Unterstützung bekommen JPEG oder PNG als Ersatz.
Dynamische Erzeugung: Responsive Bilder werden per JavaScript gebaut, etwa in Galerien oder beim nachträglichen Laden.

Rückgabewert

Typ

HTMLPictureElement

Beschreibung

document.createElement('picture') liefert eine Instanz. Einen eigenen Konstruktor, den man mit new aufrufen kann, gibt es nicht. new HTMLPictureElement() wirft einen TypeError.

Beispiele

picture-Element per JavaScript erzeugen (Formatauswahl)

const createPicture = (basis, alt) => {
  const picture = document.createElement('picture');

  const avif = document.createElement('source');
  avif.type = 'image/avif';
  avif.srcset = `${basis}.avif`;

  const webp = document.createElement('source');
  webp.type = 'image/webp';
  webp.srcset = `${basis}.webp`;

  const img = document.createElement('img');
  img.src = `${basis}.jpg`; // Ersatzbild für alle Browser
  img.alt = alt;
  img.loading = 'lazy';

  picture.append(avif, webp, img); // img MUSS als letztes Kind stehen
  return picture;
};

const pic = createPicture('/bilder/berg', 'Bergpanorama bei Sonnenaufgang');
document.body.append(pic);
console.log(pic instanceof HTMLPictureElement);

true

Tatsächlich gewählte Quelle ermitteln

// HTML: <picture id="hero">
//   <source media="(max-width: 600px)" srcset="hero-mobil.jpg">
//   <img src="hero-desktop.jpg" alt="Titelbild">
// </picture>
const picture = document.querySelector('#hero');
const img = picture.querySelector('img');

const logSource = () => console.log('Geladen:', img.currentSrc);

if (img.complete) {
  logSource();
} else {
  img.addEventListener('load', logSource, { once: true });
}

Geladen: https://example.com/hero-desktop.jpg

Art Direction: Quelle für ein Medium nachträglich hinzufügen

const picture = document.querySelector('picture');
const img = picture.querySelector('img');

const hochformat = document.createElement('source');
hochformat.media = '(orientation: portrait)';
hochformat.srcset = 'produkt-hoch.jpg 1x, produkt-hoch@2x.jpg 2x';

// source muss VOR dem img eingefügt werden
picture.insertBefore(hochformat, img);

console.log(picture.querySelectorAll('source').length, 'Quelle(n)');

1 Quelle(n)

// Wichtig · Fallstricke

Kein Bild ohne <img>: Fehlt das <img>-Kind, zeigt das Element nichts an. <source>-Elemente, die nach dem <img> stehen, werden ignoriert.
Keine eigenen Eigenschaften: Größe, alt, loading, decoding und die Ereignisse load/error gehören zum <img>, nicht zum <picture>. Auch CSS wie width oder object-fit setzt du am besten auf das img.
Welche Quelle gewählt wurde, verrät nur img.currentSrc. img.src enthält immer den Wert aus dem Attribut, also das Ersatzbild.
Ändert sich media oder srcset einer <source> zur Laufzeit, wählt der Browser die Quelle neu aus und lädt eventuell ein anderes Bild.
Im srcset einer <source> innerhalb von <picture> ist srcset Pflicht. Das Attribut src wird dort ignoriert, es gilt nur bei <audio>/<video>.
Kompatibilität: Wird in allen aktuellen Browsern unterstützt (Chrome 38+, Firefox 38+, Safari 9.1+, Edge 13+). Der Internet Explorer kennt das Element nicht und zeigt einfach das <img>-Ersatzbild an. Das Element ist also von selbst abwärtskompatibel.

Siehe auch

HTMLPreElement HTMLTitleElement HTMLAnchorElement HTMLIFrameElement HTMLImageElement