DOMStringMap — Schnittstelle · JavaScript-Referenz

Signatur

interface DOMStringMap

Beschreibung

DOMStringMap ist die Schnittstelle hinter der Eigenschaft dataset von HTML-, SVG- und MathML-Elementen. Jedes benutzerdefinierte Attribut der Form data-* erscheint dort als Eigenschaft. Aus dem Attributnamen wird dabei ein camelCase-Name: data-user-id wird zu dataset.userId. Das funktioniert auch umgekehrt: Wer dataset.userId = "42" setzt, erzeugt das Attribut data-user-id="42".

Das Objekt ist live. Änderungen am dataset schreiben sofort in die DOM-Attribute, und Änderungen per setAttribute() sind sofort im dataset sichtbar. Löschen geht mit dem delete-Operator. Eigene Methoden hat die Schnittstelle nicht. Sie verhält sich wie ein einfaches Objekt: Man kann sie mit for...in, Object.keys(), Object.entries() oder dem in-Operator verwenden.

Typische Einsätze sind Konfiguration direkt im Markup (z. B. data-autoplay), Kennungen für Event-Delegation (data-action, data-id) und Zustandswerte, die man in CSS über Attributselektoren wie [data-state="open"] auswerten kann.

Alle Werte sind immer Strings. Zahlen, Wahrheitswerte oder Objekte müssen Sie beim Lesen selbst umwandeln, z. B. mit Number() oder JSON.parse().

Rückgabewert

Typ

DOMStringMap

Beschreibung

Die Eigenschaft element.dataset ist schreibgeschützt und liefert ein live mit dem Element verbundenes DOMStringMap-Objekt. Seine Eigenschaften sind vom Typ string; Schlüssel ohne passendes Attribut ergeben undefined.

Beispiele

data-Attribute lesen, setzen und löschen

// <article id="post" data-post-id="1337" data-author="anna"></article>
const post = document.getElementById('post');

console.log(post.dataset.postId);   // aus data-post-id
console.log(post.dataset.author);

// Setzen erzeugt das Attribut data-reading-time
post.dataset.readingTime = 5;       // wird zu "5" umgewandelt
console.log(post.getAttribute('data-reading-time'));

// Löschen entfernt das Attribut
delete post.dataset.author;
console.log(post.hasAttribute('data-author'));

1337 anna 5 false

Event-Delegation mit data-action

// <ul id="todos">
//   <li>Einkaufen <button data-action="done" data-id="1">✓</button></li>
//   <li>Sport <button data-action="delete" data-id="2">✗</button></li>
// </ul>
const handlers = {
  done: (id) => console.log(`Aufgabe ${id} erledigt`),
  delete: (id) => console.log(`Aufgabe ${id} gelöscht`),
};

document.getElementById('todos').addEventListener('click', (event) => {
  const button = event.target.closest('[data-action]');
  if (!button) return;
  const { action, id } = button.dataset;
  handlers[action]?.(Number(id));
});

Aufgabe 1 erledigt // nach Klick auf ✓

Konfiguration aus dem Markup mit Typumwandlung

// <div class="slider" data-autoplay="true" data-interval="3000" data-options='{"loop":false}'></div>
const el = document.querySelector('.slider');
const { autoplay, interval = '5000', options = '{}' } = el.dataset;

const config = {
  autoplay: autoplay === 'true',
  interval: Number(interval),
  ...JSON.parse(options),
};

console.log(config);
console.log(Object.keys(el.dataset));
console.log('autoplay' in el.dataset);

{ autoplay: true, interval: 3000, loop: false } ["autoplay", "interval", "options"] true

// Wichtig · Fallstricke

Namensumwandlung: Ein Bindestrich gefolgt von einem Kleinbuchstaben wird zu einem Großbuchstaben (data-foo-bar → fooBar). Wenn Sie einen Namen wie dataset.fooBar setzen, wird jeder Großbuchstabe zu - plus Kleinbuchstabe. Ein Schlüssel, der einen Bindestrich direkt vor einem Kleinbuchstaben enthält (z. B. dataset['foo-bar'] = 1), löst einen SyntaxError aus.
Alles ist ein String: dataset.count = 1 speichert "1". Auch dataset.flag = false speichert "false", und dieser String ist in einer Bedingung wahr. Leere Attribute wie <div data-open> ergeben "", was falsy ist. Prüfen Sie deshalb lieber mit 'open' in el.dataset.
Sicherheit: Werte aus data-* können von Nutzern oder aus fremdem HTML stammen. Setzen Sie sie nie ungeprüft per innerHTML ein und übergeben Sie sie nicht an eval(). Nutzen Sie stattdessen textContent. JSON.parse() sollten Sie in try/catch kapseln.
Nicht für große Datenmengen: Die Werte werden im DOM serialisiert. Größere Daten oder Objektverweise speichern Sie besser in einer WeakMap, deren Schlüssel das Element ist.
Kompatibilität: HTMLElement.dataset funktioniert in allen modernen Browsern. SVGElement.dataset fehlte in älteren Versionen von Safari und Edge (vor Chromium). Für diese Fälle ist getAttribute('data-…') die Ausweichlösung. Wenn Sie Änderungen am dataset überwachen wollen, nutzen Sie einen MutationObserver mit attributes: true.

Siehe auch

HTMLElement.dataset Element.getAttribute() Element.setAttribute() Element.removeAttribute() MutationObserver DOMStringList delete