HTMLAreaElement.coords — Eigenschaft · JavaScript-Referenz

Signatur

HTMLAreaElement.coords

Beschreibung

Die Eigenschaft coords der Schnittstelle HTMLAreaElement spiegelt das HTML-Attribut coords eines <area>-Elements wider. Sie enthält eine Zeichenkette mit kommagetrennten Zahlen (in CSS-Pixeln, bezogen auf die linke obere Ecke des Bildes). Diese Zahlen legen zusammen mit shape fest, welcher Bereich eines Bildes in einer Image-Map (<map>) klickbar ist.

Wie die Werte zu lesen sind, hängt von shape ab:

rect: x1,y1,x2,y2, also linke obere und rechte untere Ecke
circle: x,y,r, also Mittelpunkt und Radius
poly: x1,y1,x2,y2,…,xn,yn, also die Eckpunkte eines Polygons
default: Das Attribut wird ignoriert, der Bereich deckt das ganze Bild ab.

Nützlich ist die Eigenschaft vor allem, wenn man Image-Maps dynamisch anpassen will: etwa bei responsiven Bildern, deren Anzeigegröße von der Originalgröße abweicht, oder für Hervorhebungen auf einem Canvas-Overlay. Hier werden die Koordinaten ausgelesen, umgerechnet und wieder gesetzt.

Rückgabewert

Typ

string

Beschreibung

Der Wert des Attributs coords als Zeichenkette, z. B. "10,20,110,80". Fehlt das Attribut, ist es ein leerer String "". Beim Setzen wird der Wert unverändert als Attribut übernommen.

Beispiele

Koordinaten auslesen und in Zahlen umwandeln

// HTML:
// <img src="plan.png" usemap="#plan" alt="Grundriss">
// <map name="plan">
//   <area id="kueche" shape="rect" coords="10,20,110,80" href="#kueche" alt="Küche">
// </map>

const area = document.getElementById('kueche');
console.log(area.coords);

const [x1, y1, x2, y2] = area.coords.split(',').map(Number);
console.log(`Breite: ${x2 - x1}px, Höhe: ${y2 - y1}px`);

10,20,110,80 Breite: 100px, Höhe: 60px

Kreisförmigen Bereich per Skript setzen

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

const area = document.createElement('area');
area.shape = 'circle';
area.coords = [200, 150, 40].join(','); // Mittelpunkt (200|150), Radius 40
area.href = '#bad';
area.alt = 'Bad';
map.append(area);

console.log(area.getAttribute('coords'));

200,150,40

Responsive Image-Map: Koordinaten skalieren

const scaleImageMap = (img) => {
  const map = document.querySelector(`map[name="${img.useMap.slice(1)}"]`);
  if (!map) return;
  const factor = img.clientWidth / img.naturalWidth;

  for (const area of map.areas) {
    // Originalwerte einmalig sichern, damit sich Rundungsfehler nicht aufsummieren
    area.dataset.origCoords ??= area.coords;
    area.coords = area.dataset.origCoords
      .split(',')
      .map((n) => Math.round(Number(n) * factor))
      .join(',');
  }
};

const img = document.querySelector('img[usemap]');
img.addEventListener('load', () => scaleImageMap(img));
window.addEventListener('resize', () => scaleImageMap(img));

// Wichtig · Fallstricke

Rückgabetyp ist string, kein Array: Obwohl die Werte fachlich Zahlen sind, muss man sie selbst mit split(',').map(Number) umwandeln. Leerzeichen um die Kommas sind in der Praxis üblich, Number(' 20') kommt damit zurecht.
Keine Prüfung beim Setzen: Ungültige Werte werden ohne Fehler übernommen. Der Browser wertet sie beim Treffertest dann nach eigenen Regeln aus oder lässt den Bereich unwirksam. Die Anzahl der Werte muss zu shape passen: 4 bei rect, 3 bei circle, bei poly eine gerade Anzahl von mindestens 6.
Pixel beziehen sich auf die angezeigte Größe: Wird das Bild per CSS skaliert (z. B. max-width: 100%), passen sich die Koordinaten nicht von selbst an. Man muss sie selbst umrechnen (siehe Beispiel). Prozentangaben sind in HTML5 nicht erlaubt.
Barrierefreiheit: Setze für jedes <area> mit href ein sinnvolles alt-Attribut.
Kompatibilität: Wird seit jeher von allen Browsern unterstützt (Baseline).

Siehe auch

HTMLAreaElement.download HTMLAreaElement.port HTMLAreaElement.host HTMLAreaElement.href HTMLAreaElement.rel