Document.images — Eigenschaft · JavaScript-Referenz

Signatur

get Document.images

Beschreibung

Die schreibgeschützte Eigenschaft document.images gibt eine HTMLCollection mit allen <img>-Elementen des Dokuments zurück, in Dokumentreihenfolge. Sie ist ein bequemer Kurzweg für document.getElementsByTagName("img") und stammt noch aus der Frühzeit des DOM.

Die Sammlung ist live: Werden Bilder per JavaScript hinzugefügt oder entfernt, spiegelt die Collection das sofort wider. Einzelne Elemente erreicht man per Index (images[0]), mit item() oder über namedItem() bzw. direkt über den id- oder name-Wert (images.logo).

Typische Einsatzfälle sind das Prüfen fehlender alt-Texte, das Nachladen oder Austauschen von Bildquellen, das Warten auf vollständig geladene Bilder oder schnelle Analysen in der Entwicklerkonsole. Beachte: Nur echte <img>-Elemente werden erfasst – <picture>-Container, <svg>, <input type="image"> oder CSS-Hintergrundbilder nicht.

Rückgabewert

Typ

HTMLCollection<HTMLImageElement>

Beschreibung

Eine live aktualisierte HTMLCollection aller <img>-Elemente des Dokuments. Ist kein Bild vorhanden, ist die Sammlung leer (length === 0), niemals null.

Beispiele

Bilder ohne alt-Text finden (Barrierefreiheit)

// HTMLCollection in ein Array umwandeln, um filter() zu nutzen
const ohneAlt = Array.from(document.images)
  .filter((img) => !img.hasAttribute("alt"));

console.log(`${ohneAlt.length} von ${document.images.length} Bildern ohne alt-Attribut`);
ohneAlt.forEach((img) => console.warn("Fehlender alt-Text:", img.src));

2 von 5 Bildern ohne alt-Attribut Fehlender alt-Text: https://example.com/banner.jpg Fehlender alt-Text: https://example.com/icon.png

Warten, bis alle Bilder geladen sind

const warteAufBilder = () =>
  Promise.all(
    [...document.images].map((img) =>
      img.complete
        ? Promise.resolve(img)
        : new Promise((resolve) => {
            img.addEventListener("load", () => resolve(img), { once: true });
            img.addEventListener("error", () => resolve(img), { once: true });
          })
    )
  );

const bilder = await warteAufBilder();
const kaputt = bilder.filter((img) => img.naturalWidth === 0);
console.log(`Geladen: ${bilder.length}, fehlerhaft: ${kaputt.length}`);

Geladen: 5, fehlerhaft: 1

Live-Verhalten und Zugriff per id

// <img id="logo" src="logo.svg" alt="Logo"> sei im Dokument vorhanden
const bilder = document.images;
console.log(bilder.length);           // z. B. 1
console.log(bilder.logo.alt);         // Zugriff über id
console.log(bilder.namedItem("logo") === bilder[0]);

const neu = new Image(100, 100);
neu.src = "platzhalter.png";
document.body.append(neu);

// Die Collection aktualisiert sich automatisch
console.log(bilder.length);

1 Logo true 2

// Wichtig · Fallstricke

Live-Collection: Wer in einer Schleife Bilder entfernt, während er über document.images iteriert, überspringt Elemente, weil sich Indizes verschieben. Vorher mit Array.from() oder Spread-Syntax eine statische Kopie anlegen.
Kein Array: HTMLCollection hat kein map(), filter() oder forEach(). for...of funktioniert in allen modernen Browsern.
Schreibgeschützt: Eine Zuweisung an document.images wird ignoriert (im Strict Mode ohne Fehler, da es nur einen Getter gibt).
Umfang: Nur <img>-Elemente im Hauptdokument werden erfasst – keine Bilder in iframes, Shadow-DOM-Bäumen, SVG-<image> oder CSS-Hintergründen. Für flexiblere Auswahl document.querySelectorAll("img") (statische NodeList) verwenden.
Lazy Loading: Bilder mit loading="lazy" sind in der Sammlung enthalten, auch wenn sie noch nicht geladen sind; complete und naturalWidth spiegeln dann den Ladezustand wider.
Kompatibilität: In allen Browsern seit jeher unterstützt; nur in HTML-Dokumenten sinnvoll verfügbar.

Siehe auch

Document.links Document.forms Request.keepalive Document.embeds Document.all