HTMLAreaElement — Schnittstelle · JavaScript-Referenz

Signatur

interface HTMLAreaElement extends HTMLElement

Beschreibung

Das Interface HTMLAreaElement steht für ein <area>-Element. Solche Elemente legen innerhalb einer <map> klickbare Bereiche auf einem Bild fest, einer sogenannten Image-Map. Das Interface erbt alle Eigenschaften und Methoden von HTMLElement. Dazu kommen Eigenschaften für die Geometrie (shape, coords), das Linkverhalten (href, target, download, rel, relList, referrerPolicy, ping) und den Alternativtext (alt).

Wie HTMLAnchorElement nutzt es das Mixin HTMLHyperlinkElementUtils. Deshalb lassen sich URL-Bestandteile direkt lesen und schreiben: protocol, host, hostname, port, pathname, search, hash, origin (nur lesbar), username und password. Mit toString() erhält man die vollständige URL, also denselben Wert wie href.

Typische Einsätze sind das dynamische Erzeugen oder Anpassen von Image-Maps, etwa bei responsiven Bildern, deren Koordinaten neu berechnet werden müssen. Weitere Anwendungen sind die Auswertung von Klicks auf einzelne Bereiche und das nachträgliche Umschreiben von Linkzielen, zum Beispiel für Tracking-Parameter.

shape: "rect", "circle", "poly" oder "default"
coords: Koordinaten als kommagetrennte Zeichenkette in CSS-Pixeln
alt: Alternativtext. Pflicht, sobald href gesetzt ist

Rückgabewert

Typ

HTMLAreaElement

Beschreibung

Man erhält eine Instanz über document.createElement("area") oder über DOM-Abfragen wie querySelector("area"). Einen öffentlichen Konstruktor gibt es nicht.

Beispiele

Image-Map dynamisch erzeugen

const img = document.querySelector('#grundriss');
const map = document.createElement('map');
map.name = 'raeume';

const kueche = document.createElement('area');
kueche.shape = 'rect';
kueche.coords = '0,0,200,150';
kueche.href = '/raeume/kueche';
kueche.alt = 'Küche';

map.append(kueche);
document.body.append(map);
img.useMap = '#raeume';

console.log(kueche instanceof HTMLAreaElement, kueche.shape);

true rect

URL-Bestandteile lesen und ändern

const area = document.createElement('area');
area.href = 'https://example.com/shop/produkt?id=42#details';

console.log(area.hostname, area.pathname, area.search, area.hash);

// Tracking-Parameter ergänzen
const params = new URLSearchParams(area.search);
params.set('utm_source', 'imagemap');
area.search = params.toString();
console.log(area.toString());

example.com /shop/produkt ?id=42 #details https://example.com/shop/produkt?id=42&utm_source=imagemap#details

Klicks auf Bereiche per Event-Delegation auswerten

const map = document.querySelector('map[name="weltkarte"]');

map.addEventListener('click', (event) => {
  const area = event.target.closest('area');
  if (!area) return;
  event.preventDefault();
  console.log(`Region: ${area.alt} (${area.shape}: ${area.coords})`);
});

Region: Europa (poly: 120,40,180,40,170,90)

Koordinaten bei responsiven Bildern skalieren

const img = document.querySelector('img[usemap="#raeume"]');

const skaliereAreas = () => {
  const faktor = img.clientWidth / img.naturalWidth;
  for (const area of document.querySelectorAll('map[name="raeume"] area')) {
    area.dataset.orig ??= area.coords;
    area.coords = area.dataset.orig
      .split(',')
      .map((wert) => Math.round(Number(wert) * faktor))
      .join(',');
  }
};

img.complete ? skaliereAreas() : img.addEventListener('load', skaliereAreas);
window.addEventListener('resize', skaliereAreas);

// Wichtig · Fallstricke

Barrierefreiheit: Ein <area> mit href braucht immer einen aussagekräftigen alt-Text. Screenreader lesen sonst nur die URL oder gar nichts vor.
Keine automatische Skalierung: coords gelten in CSS-Pixeln relativ zur dargestellten Bildgröße. Wird das Bild per CSS skaliert, verrutschen die Bereiche, wenn man sie nicht per Skript anpasst.
Veraltete Eigenschaften: noHref ist obsolet. Ein Bereich ohne Link entsteht, indem man href einfach weglässt.
Sicherheit: Setzt man href aus Benutzereingaben, muss man javascript:-URLs verhindern, denn sonst droht XSS. Bei target="_blank" öffnen moderne Browser implizit mit noopener. Wer Wert darauf legt, setzt rel="noopener" trotzdem ausdrücklich.
Leeres href: Ohne Attribut liefern die URL-Eigenschaften leere Zeichenketten, origin liefert ebenfalls einen leeren String.
Kompatibilität: Wird von allen modernen Browsern unterstützt. referrerPolicy, download und ping kamen später hinzu. ping ist in Firefox standardmäßig deaktiviert.

Siehe auch

HTMLMarqueeElement HTMLPreElement HTMLBRElement HTMLBaseElement HTMLDataElement