HTMLImageElement.longDesc — Eigenschaft · JavaScript-Referenz

Signatur

HTMLImageElement.longDesc

Beschreibung

Die Eigenschaft longDesc spiegelt das HTML-Attribut longdesc eines <img>-Elements. Sie enthält eine URL auf ein Dokument, meist eine HTML-Seite oder einen Anker innerhalb der aktuellen Seite. Dort wird das Bild ausführlich beschrieben, etwa ein komplexes Diagramm, eine Infografik oder eine Karte. Das Attribut war dafür gedacht, dass Hilfstechnologien wie Screenreader diese Langbeschreibung anbieten können.

Beim Lesen liefert die Eigenschaft die aufgelöste, absolute URL, also relativ zur Basis-URL des Dokuments. Fehlt das Attribut, ist das Ergebnis ein leerer String. Beim Schreiben wird das Attribut longdesc im DOM gesetzt.

In HTML5 gilt longdesc als obsolet. Browser und Screenreader unterstützen es kaum und uneinheitlich. Für neuen Code sollte man die Beschreibung stattdessen sichtbar direkt neben dem Bild anbieten, zum Beispiel mit <figure> und <figcaption>. Sie kann auch per aria-describedby verknüpft werden. Ein normaler Link auf die Beschreibungsseite ist ebenfalls eine gute Lösung. Die Eigenschaft ist heute vor allem nützlich, um Altbestände auszulesen und auf moderne Muster umzustellen.

Parameter

Name	Typ	Default	Beschreibung
$value	string	""	Nur beim Setzen: eine absolute oder relative URL zur Langbeschreibung. Relative Werte werden beim Lesen gegen die Basis-URL des Dokuments aufgelöst.

Rückgabewert

Typ

string

Beschreibung

Die absolute URL aus dem Attribut longdesc. Fehlt das Attribut, ist der Wert ein leerer String "".

Beispiele

Langbeschreibung eines Diagramms auslesen

// HTML: <img id="umsatz" src="umsatz.png" alt="Umsatz 2023" longdesc="beschreibungen/umsatz.html">
const img = document.getElementById('umsatz');

// Liefert die aufgelöste absolute URL
console.log(img.longDesc);
// Rohwert des Attributs zum Vergleich
console.log(img.getAttribute('longdesc'));

https://example.com/beschreibungen/umsatz.html beschreibungen/umsatz.html

longDesc setzen und prüfen

const img = new Image();
img.src = 'karte.png';
img.alt = 'Lageplan des Campus';

// Eigenschaft setzen, dabei wird das Attribut geschrieben
img.longDesc = '#karte-beschreibung';

console.log(img.hasAttribute('longdesc'));
console.log(img.getAttribute('longdesc'));

true #karte-beschreibung

Altbestand auf barrierearmen Link umstellen

// Alle Bilder mit longdesc finden und die Beschreibung als sichtbaren Link anbieten
const migrateLongDesc = () => {
  document.querySelectorAll('img[longdesc]').forEach((img) => {
    // Fallback über getAttribute, falls der Browser die Eigenschaft nicht kennt
    const url = img.longDesc || img.getAttribute('longdesc');
    if (!url) return;

    const link = document.createElement('a');
    link.href = url;
    link.textContent = `Ausführliche Beschreibung: ${img.alt || 'Bild'}`;

    img.insertAdjacentElement('afterend', link);
    img.removeAttribute('longdesc');
  });
};

migrateLongDesc();

// Wichtig · Fallstricke

Veraltet: longdesc ist in HTML5 obsolet. Validatoren melden es als Fehler. In neuem Code sollte es nicht mehr verwendet werden.
Kaum Unterstützung durch Hilfstechnologien: Viele Screenreader und Browser bieten die Langbeschreibung Nutzerinnen und Nutzern gar nicht an. Besser sind sichtbare Beschreibungen, <figcaption> oder aria-describedby.
Eigenschaft und Attribut unterscheiden sich: Die Eigenschaft liefert die aufgelöste absolute URL. getAttribute('longdesc') liefert dagegen den Rohwert. Für Vergleiche sollte man bewusst eine der beiden Varianten wählen.
Kompatibilität: Einige Browser kennen die Eigenschaft nicht oder haben sie entfernt. Dann liefert sie undefined. Für robusten Code sollte man auf getAttribute() zurückgreifen.
Sicherheit: Wird die URL aus dem Attribut in ein href übernommen, sollte man javascript:-URLs aus nicht vertrauenswürdigen Quellen herausfiltern.

Siehe auch

HTMLFormElement.length HTMLImageElement.name HTMLImageElement.border HTMLImageElement.loading HTMLImageElement.complete