HTMLImageElement.name — Eigenschaft · JavaScript-Referenz

Signatur

HTMLImageElement.name

Beschreibung

Die Eigenschaft HTMLImageElement.name spiegelt das HTML-Attribut name eines <img>-Elements wider. Früher, vor allem in HTML 4 und zu Zeiten von DOM Level 0, gab man Bildern damit einen Namen. Über diesen Namen ließ sich das Bild dann per document.images["logo"] oder direkt als document.logo ansprechen, zum Beispiel für die klassischen Rollover-Effekte.

In der aktuellen HTML-Spezifikation gilt das Attribut als veraltet. Stattdessen sollte man das Attribut id nutzen und das Element mit document.getElementById() oder document.querySelector() abrufen. Die Eigenschaft funktioniert aber weiterhin in allen Browsern, damit alte Seiten nicht kaputtgehen.

Der Wert ist immer ein String. Fehlt das Attribut, liefert die Eigenschaft einen leeren String "". Wenn man der Eigenschaft einen Wert zuweist, wird das Attribut name im Markup geändert oder neu angelegt.

Rückgabewert

Typ

string

Beschreibung

Der Wert des Attributs name. Ist das Attribut nicht gesetzt, ist das Ergebnis ein leerer String "". Die Eigenschaft ist les- und schreibbar.

Beispiele

Namen eines Bildes auslesen

// HTML: <img id="logo" name="firmenlogo" src="logo.png" alt="Logo">
const img = document.getElementById('logo');
console.log(img.name);
console.log(img.getAttribute('name'));

firmenlogo firmenlogo

Namen setzen und Standardwert prüfen

const img = new Image();
console.log(JSON.stringify(img.name)); // Attribut fehlt

img.name = 'vorschau';
console.log(img.outerHTML);

"" <img name="vorschau">

Alten Zugriff über document.images modernisieren

// Legacy-Code: document.images['firmenlogo'].src = 'logo-hover.png';

// Modern: Zugriff über den Attribut-Selektor (oder besser über eine id)
const legacyImg = document.querySelector('img[name="firmenlogo"]');
if (legacyImg) {
  legacyImg.addEventListener('mouseenter', () => {
    legacyImg.src = 'logo-hover.png';
  });
  legacyImg.addEventListener('mouseleave', () => {
    legacyImg.src = 'logo.png';
  });
}

// Wichtig · Fallstricke

Veraltet: In neuem Code solltest du name bei <img> nicht mehr verwenden. Nimm stattdessen id oder data-*-Attribute. HTML-Validatoren melden das Attribut als nicht konform.
Verschmutzung des globalen Namensraums: Bilder mit name werden als benannte Eigenschaften von document sichtbar, etwa document.firmenlogo. Das kann echte Eigenschaften von document überdecken (DOM Clobbering). Das führt zu schwer auffindbaren Fehlern und ist ein bekannter Angriffsweg, wenn eingeschleustes HTML mit frei wählbaren name-Werten erlaubt ist. Beim Bereinigen (Sanitizing) von HTML sollte name daher entfernt werden.
Die Eigenschaft ist nicht dasselbe wie alt oder title. Sie hat keine Wirkung auf die Barrierefreiheit und wird nicht angezeigt.
Kompatibilität: Wird von allen Browsern unterstützt (Chrome, Firefox, Safari, Edge) und bleibt aus Gründen der Abwärtskompatibilität erhalten.

Siehe auch

Element.id Document.images HTMLFormElement.name HTMLImageElement.alt HTMLImageElement.hspace