HTMLElement: dataset-Eigenschaft

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

Die dataset-Eigenschaft, die schreibgeschützt ist, des HTMLElement-Interfaces bietet Lese- und Schreibzugriff auf benutzerdefinierte Datenattribute (data-*) von Elementen. Sie stellt eine Map von Strings (DOMStringMap) mit einem Eintrag für jedes data-*-Attribut bereit.

Hinweis: Die dataset-Eigenschaft selbst kann gelesen, aber nicht direkt geschrieben werden. Stattdessen müssen alle Schreiboperationen auf die einzelnen Eigenschaften innerhalb des dataset erfolgen, die wiederum die Datenattribute repräsentieren.

Ein HTML-data-*-Attribut und sein entsprechendes DOM dataset.property ändern ihren gemeinsamen Namen je nachdem, wo sie gelesen oder geschrieben werden:

In HTML

Der Attributname beginnt mit data-. Er darf nur Buchstaben, Zahlen, Bindestriche (-), Punkte (.), Doppelpunkte (:), und Unterstriche (_) enthalten. Alle ASCII-Großbuchstaben (A bis Z) werden in Kleinbuchstaben umgewandelt.

In JavaScript

Der Eigenname eines benutzerdefinierten Datenattributs entspricht dem HTML-Attribut ohne das data--Präfix. Einzelne Bindestriche (-) werden entfernt und das nächste ASCII- Zeichen nach einem entfernten Bindestrich wird großgeschrieben, um den camelCase-Namen der Eigenschaft zu bilden.

Details und Beispiele zur Umwandlung zwischen den HTML- und JavaScript-Formen werden im nächsten Abschnitt ausführlicher beschrieben.

Zusätzlich zu den folgenden Informationen finden Sie einen Leitfaden zur Verwendung von HTML-Datenattributen in unserem Artikel Using data attributes.

Namensumwandlung

Umwandlung von dash-style zu camelCase

Ein benutzerdefinierter Datenattributname wird durch die folgenden Schritte in einen Schlüssel für den DOMStringMap-Eintrag umgewandelt:

  1. Alle ASCII-Großbuchstaben (A bis Z) in Kleinbuchstaben umwandeln;
  2. Das Präfix data- (einschließlich des Bindestrichs) entfernen;
  3. Bei jedem Bindestrich (U+002D), gefolgt von einem ASCII-Kleinbuchstaben a bis z, den Bindestrich entfernen und den Buchstaben großschreiben;
  4. Andere Zeichen (einschließlich anderer Bindestriche) bleiben unverändert.
Umwandlung von camelCase zu dash-style

Die entgegengesetzte Umwandlung, die einen Schlüssel in einen Attributnamen umwandelt, erfolgt nach den folgenden Schritten:

  1. Einschränkung: Vor der Umwandlung darf ein Bindestrich nicht direkt von einem ASCII-Kleinbuchstaben a bis z gefolgt werden;
  2. Das Präfix data- hinzufügen;
  3. Einen Bindestrich vor jedem ASCII-Großbuchstaben A bis Z einfügen, dann den Buchstaben in Kleinbuchstaben umwandeln;
  4. Andere Zeichen bleiben unverändert.

Zum Beispiel entspricht ein data-abc-def-Attribut dem dataset.abcDef.

Zugriff auf Werte

  • Attribute können über den camelCase-Namen/Schlüssel als Objekteigenschaft des datasets gesetzt und gelesen werden: element.dataset.keyname.
  • Attribute können auch mit der Klammer-Syntax gesetzt und gelesen werden: element.dataset['keyname'].
  • Der in-Operator kann überprüfen, ob ein bestimmtes Attribut existiert: 'keyname' in element.dataset. Beachten Sie, dass dies die Prototypen-Kette des dataset durchläuft und unsicher sein kann, wenn Sie externen Code haben, der die Prototypen-Kette verunreinigen könnte. Mehrere Alternativen existieren, wie z.B. Object.hasOwn(element.dataset, 'keyname'), oder einfach die Überprüfung, ob element.dataset.keyname !== undefined.

Setzen von Werten

  • Wenn das Attribut gesetzt wird, wird der Wert immer in einen String umgewandelt. Zum Beispiel: element.dataset.example = null wird in data-example="null" umgewandelt.

  • Um ein Attribut zu entfernen, können Sie den delete-Operator verwenden: delete element.dataset.keyname.

Wert

Ein DOMStringMap.

Beispiele

html
<div id="user" data-id="1234567890" data-user="carinaanand" data-date-of-birth>
  Carina Anand
</div>
js
const el = document.querySelector("#user");

// el.id === 'user'
// el.dataset.id === '1234567890'
// el.dataset.user === 'carinaanand'
// el.dataset.dateOfBirth === ''

// set a data attribute
el.dataset.dateOfBirth = "1960-10-03";
// Result on JS: el.dataset.dateOfBirth === '1960-10-03'
// Result on HTML: <div id="user" data-id="1234567890" data-user="carinaanand" data-date-of-birth="1960-10-03">Carina Anand</div>

delete el.dataset.dateOfBirth;
// Result on JS: el.dataset.dateOfBirth === undefined
// Result on HTML: <div id="user" data-id="1234567890" data-user="carinaanand">Carina Anand</div>

if (el.dataset.someDataAttr === undefined) {
  el.dataset.someDataAttr = "mydata";
  // Result on JS: 'someDataAttr' in el.dataset === true
  // Result on HTML: <div id="user" data-id="1234567890" data-user="carinaanand" data-some-data-attr="mydata">Carina Anand</div>
}

Spezifikationen

Specification
HTML
# dom-dataset-dev

Browser-Kompatibilität

Siehe auch