Signatur
Beschreibung
Die Eigenschaft useMap des Interfaces HTMLObjectElement spiegelt das HTML-Attribut usemap wider. Liest du sie aus, bekommst du den aktuellen Attributwert als String. Weist du ihr einen Wert zu, wird das Attribut im DOM entsprechend gesetzt. Der Wert ist normalerweise ein Verweis auf den Namen einer Image-Map mit vorangestelltem Rautezeichen, zum Beispiel "#weltkarte". Er bezieht sich auf das name-Attribut eines <map>-Elements.
Mit einer Image-Map lassen sich Bereiche einer Grafik (über <area>-Elemente) als klickbare Links festlegen. Ursprünglich konnte man eine solche Map auch mit einem <object> verbinden, das eine Grafik einbettet. Im aktuellen HTML Living Standard gilt das Attribut usemap auf <object> jedoch als veraltet. Die Eigenschaft steht nur noch aus Gründen der Abwärtskompatibilität im Abschnitt „Obsolete features“.
Praktisch brauchst du useMap heute vor allem, um Altbestand auszulesen, zu analysieren oder zu migrieren. Für neue Projekte nimmst du <img usemap="#…"> mit der Eigenschaft HTMLImageElement.useMap, eine Inline-SVG mit Links oder frei positionierte Links über einer Grafik.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $wert | string | "" | Nur beim Schreiben: Der neue Wert für das Attribut usemap, üblicherweise "#name" einer <map>. Jeder Wert wird in einen String umgewandelt. |
Rückgabewert
usemap. Fehlt das Attribut, ist das Ergebnis ein leerer String "", nicht null.Beispiele
usemap-Wert eines object-Elements auslesen
// HTML:
// <object id="karte" data="karte.png" type="image/png" usemap="#regionen"></object>
// <map name="regionen">
// <area shape="rect" coords="0,0,100,100" href="/nord" alt="Nord">
// </map>
const obj = document.getElementById('karte');
console.log(obj.useMap);
// Passende <map> anhand des Namens finden
const mapName = obj.useMap.replace(/^#/, '');
const map = document.querySelector(`map[name="${CSS.escape(mapName)}"]`);
console.log(map ? map.areas.length : 'keine Map gefunden');Wert setzen und Attribut-Spiegelung prüfen
const obj = document.createElement('object');
obj.data = 'grafik.png';
obj.type = 'image/png';
console.log(JSON.stringify(obj.useMap)); // Attribut fehlt noch
obj.useMap = '#navigation';
console.log(obj.getAttribute('usemap'));
obj.removeAttribute('usemap');
console.log(JSON.stringify(obj.useMap));Altbestand migrieren: object mit usemap durch img ersetzen
// Alle <object>-Elemente mit Image-Map durch <img> ersetzen,
// weil usemap auf <object> veraltet ist
const migriereImageMaps = () => {
const kandidaten = [...document.querySelectorAll('object[usemap]')];
for (const obj of kandidaten) {
const img = document.createElement('img');
img.src = obj.data;
img.useMap = obj.useMap; // Verweis übernehmen
img.alt = obj.getAttribute('aria-label') ?? obj.textContent.trim();
if (obj.width) img.width = Number(obj.width);
if (obj.height) img.height = Number(obj.height);
obj.replaceWith(img);
}
return kandidaten.length;
};
console.log(`${migriereImageMaps()} Element(e) migriert`);// Wichtig · Fallstricke
- Veraltet: Der HTML Living Standard führt
usemapauf<object>und die EigenschaftHTMLObjectElement.useMapnur noch unter „Obsolete features“. Nutze sie in neuem Code nicht. Die Browser stellen die Eigenschaft zwar weiterhin bereit, aber ob die Image-Map bei eingebetteten Objekten tatsächlich funktioniert, ist uneinheitlich und schlecht getestet. - Kein automatisches
#: Die Eigenschaft gibt den Attributwert unverändert zurück, ob mit oder ohne Raute. Beim Suchen der passenden<map>entfernst du die Raute selbst und maskierst den Namen am besten mitCSS.escape(). - Leerer String statt
null: Ohne Attribut liefertuseMapden Wert"". Willst du prüfen, ob das Attribut überhaupt vorhanden ist, nimmhasAttribute('usemap'). - Barrierefreiheit: Image-Maps brauchen für jede
<area>ein aussagekräftigesalt. Außerdem passen sie sich nicht an die Bildgröße an, weil diecoordsin Pixeln angegeben sind. Für flexible Layouts ist Inline-SVG meist die bessere Wahl.