HTMLImageElement.useMap — Eigenschaft · JavaScript-Referenz

Signatur

HTMLImageElement.useMap

Beschreibung

Die Eigenschaft useMap spiegelt das HTML-Attribut usemap des <img>-Elements wider. Ihr Wert ist eine hash-name reference: ein # und direkt danach der Wert des name-Attributs eines <map>-Elements, z. B. "#weltkarte". Ist die Referenz gültig, werden die <area>-Elemente dieser Karte zu klickbaren Bereichen auf dem Bild.

Clientseitige Bildkarten sind nützlich, wenn verschiedene Bereiche einer Grafik zu unterschiedlichen Zielen führen sollen, etwa Regionen einer Landkarte, Teile eines Gebäudeplans oder Bauteile in einer Explosionszeichnung. Über useMap kannst du die Karte zur Laufzeit wechseln, entfernen oder erst nachträglich zuweisen, zum Beispiel abhängig von Zoomstufe oder Sprache.

Der Wert ist ein einfacher String. Der Browser prüft beim Setzen nicht, ob die Karte existiert. Findet er keine passende <map>, bleibt das Bild ein ganz normales Bild. Ein leerer String bedeutet: keine Bildkarte. Mit einem leeren String bleibt das Attribut aber als usemap="" im DOM stehen; wer es ganz loswerden will, nimmt removeAttribute("usemap").

Parameter

Name	Typ	Default	Beschreibung
$value	string	""	Beim Setzen: die Referenz auf die Karte im Format `#kartenname`. Ein leerer String hebt die Verknüpfung auf.

Rückgabewert

Typ

string

Beschreibung

Der aktuelle Wert des usemap-Attributs, z. B. "#grundriss", oder ein leerer String, wenn das Attribut fehlt.

Beispiele

Bildkarte auslesen

// HTML:
// <img id="plan" src="grundriss.png" usemap="#grundriss" alt="Grundriss">
// <map name="grundriss">
//   <area shape="rect" coords="0,0,200,150" href="/kueche" alt="Küche">
// </map>
const img = document.getElementById('plan');
console.log(img.useMap);

#grundriss

Zugehöriges map-Element und seine Bereiche finden

const img = document.getElementById('plan');
const name = img.useMap.replace(/^#/, '');
const map = name ? document.querySelector(`map[name="${CSS.escape(name)}"]`) : null;

if (map) {
  const ziele = [...map.areas].map(area => `${area.alt}: ${area.href}`);
  console.log(ziele);
} else {
  console.log('Keine gültige Bildkarte verknüpft');
}

["Küche: https://example.com/kueche"]

Karte zur Laufzeit wechseln

const img = document.querySelector('img.stockwerk');
const karten = { eg: '#erdgeschoss', og: '#obergeschoss' };

const zeigeStockwerk = (stockwerk) => {
  img.src = `/plaene/${stockwerk}.png`;
  img.useMap = karten[stockwerk] ?? '';
};

zeigeStockwerk('og');
console.log(img.useMap);

// Verknüpfung ganz entfernen:
img.removeAttribute('usemap');
console.log(JSON.stringify(img.useMap));

#obergeschoss ""

// Wichtig · Fallstricke

Das # ist Pflicht: img.useMap = "grundriss" ohne Raute ist nach der HTML-Spezifikation ungültig und wird nicht zuverlässig mit der Karte verknüpft. Schreib immer "#grundriss".
Abgleich über name: Die Referenz wird mit dem name-Attribut der <map> verglichen. Nutzt du zusätzlich id, sollten beide denselben Wert haben. Die Groß- und Kleinschreibung muss exakt stimmen.
Responsive Bilder: Die coords der <area>-Elemente sind feste Pixelwerte im Originalmaßstab. Wird das Bild per CSS skaliert, passen die Bereiche nicht mehr. Dann musst du die Koordinaten per Skript umrechnen oder SVG mit Links verwenden.
Barrierefreiheit: Jede <area> mit href braucht ein aussagekräftiges alt. Auf Touch-Geräten sind kleine Bereiche schwer zu treffen.
Kompatibilität: Die Eigenschaft wird von allen modernen Browsern unterstützt. Serverseitige Bildkarten (ismap) sind ein anderes Konzept und laufen über HTMLImageElement.isMap.

Siehe auch

HTMLImageElement.isMap HTMLImageElement.hspace HTMLImageElement.name HTMLImageElement.sizes HTMLImageElement.src