HTMLMapElement.name — Eigenschaft · JavaScript-Referenz

Signatur

HTMLMapElement.name

Beschreibung

Die Eigenschaft name von HTMLMapElement spiegelt das HTML-Attribut name des <map>-Elements wider. Über diesen Namen verknüpft ein <img>-Element die Image-Map: Das Attribut usemap des Bildes enthält den Namen mit vorangestelltem Rautezeichen, also z. B. usemap="#weltkarte".

Laut HTML-Spezifikation muss der Name nicht leer sein, darf keine Leerzeichen enthalten und muss unter allen <map>-Elementen des Dokuments eindeutig sein. Ist zusätzlich ein id-Attribut gesetzt, muss es denselben Wert wie name haben.

Die Eigenschaft ist lesbar und schreibbar. Wenn man sie per Skript ändert, wird das Attribut im DOM sofort aktualisiert. Bilder, deren usemap noch auf den alten Namen zeigt, verlieren dadurch ihre Verknüpfung zur Map. Das ist nützlich, wenn man Image-Maps dynamisch erzeugt, austauscht oder zwischen mehreren Maps umschaltet.

Rückgabewert

Typ

string

Beschreibung

Der aktuelle Wert des name-Attributs. Fehlt das Attribut, ist der Wert ein leerer String "".

Beispiele

Namen einer vorhandenen Image-Map auslesen

// HTML:
// <img src="karte.png" usemap="#weltkarte" alt="Weltkarte">
// <map name="weltkarte">
//   <area shape="rect" coords="0,0,100,100" href="/europa" alt="Europa">
// </map>

const map = document.querySelector('map');
console.log(map.name);

weltkarte

Image-Map dynamisch erzeugen und mit einem Bild verknüpfen

const img = document.createElement('img');
img.src = 'grundriss.png';
img.alt = 'Grundriss';

const map = document.createElement('map');
map.name = 'grundriss-map';

const area = document.createElement('area');
area.shape = 'circle';
area.coords = '120,80,40';
area.href = '/kueche';
area.alt = 'Küche';
map.append(area);

// usemap braucht das führende '#'
img.useMap = `#${map.name}`;
document.body.append(img, map);

console.log(img.useMap, map.getAttribute('name'));

#grundriss-map grundriss-map

Zwischen zwei Image-Maps umschalten

const img = document.querySelector('#plan');
const maps = [...document.querySelectorAll('map')];

const aktiviereMap = (name) => {
  const ziel = maps.find((m) => m.name === name);
  if (!ziel) {
    console.warn(`Keine Map mit dem Namen "${name}" gefunden`);
    return;
  }
  img.useMap = `#${ziel.name}`;
  console.log(`Aktive Map: ${ziel.name}`);
};

aktiviereMap('erdgeschoss');

Aktive Map: erdgeschoss

// Wichtig · Fallstricke

Rautezeichen nicht vergessen: map.name enthält den Namen ohne #, img.useMap dagegen verlangt es ("#name"). Das ist die häufigste Fehlerquelle.
Eindeutigkeit: Gibt es mehrere <map>-Elemente mit gleichem Namen, verwendet der Browser in der Regel das erste im Dokument. Der Browser prüft die Eindeutigkeit nicht und meldet auch keinen Fehler.
Leerzeichen: Namen mit Leerzeichen sind ungültig und führen in manchen Browsern dazu, dass die Verknüpfung nicht funktioniert.
id und name: Sind beide gesetzt, müssen sie laut Spezifikation übereinstimmen. Ändert man name per Skript, wird id nicht automatisch angepasst.
Kompatibilität: Die Eigenschaft wird seit jeher von allen Browsern unterstützt. Image-Maps passen sich allerdings nicht an responsive Bildgrößen an, denn die Koordinaten beziehen sich immer auf die ursprünglichen Pixelmaße.

Siehe auch

HTMLMapElement.areas CSSLayerBlockRule.name HTMLDataElement.value HTMLImageElement.name HTMLMetaElement.name