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-Schreibgeschützte Eigenschaft der HTMLElement-Schnittstelle ermöglicht Lese-/Schreibzugriff auf benutzerdefinierte Datenattribute (data-*) von Elementen. Sie stellt eine Zeichenfolgenkarte (DOMStringMap) mit einem Eintrag für jedes data-*-Attribut zur Verfügung.

Hinweis: Die dataset-Eigenschaft selbst kann gelesen, aber nicht direkt beschrieben werden. Stattdessen müssen alle Schreibvorgänge für 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, ob sie gelesen oder geschrieben werden:

In HTML

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

In JavaScript

Der Name der Eigenschaft eines benutzerdefinierten Datenattributs ist derselbe wie der HTML-Attributname ohne das Präfix data-. 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.

Neben den folgenden Informationen finden Sie eine Anleitung zur Verwendung von HTML-Datenattributen in unserem Artikel Using data attributes.

Namenskonvertierung

Umwandlung von dash-style zu camelCase

Ein benutzerdefinierter Datenattributname wird zu einem Schlüssel für den DOMStringMap-Eintrag folgendermaßen umgewandelt:

  1. Alle ASCII-Großbuchstaben (A bis Z) werden kleingeschrieben;
  2. Entfernen Sie das Präfix data- (einschließlich des Bindestrichs);
  3. Für jeden Bindestrich (U+002D), gefolgt von einem ASCII-Kleinbuchstaben a bis z, entfernen Sie den Bindestrich und schreiben Sie den Buchstaben groß;
  4. Andere Zeichen (einschließlich weiterer Bindestriche) bleiben unverändert.
Umwandlung von camelCase zu dash-style

Die gegenteilige Umwandlung, bei der ein Schlüssel in einen Attributnamen umgewandelt wird, erfolgt folgendermaßen:

  1. Einschränkung: Vor der Umwandlung darf ein Bindestrich nicht direkt auf einen ASCII-Kleinbuchstaben a bis z folgen;
  2. Fügen Sie das Präfix data- hinzu;
  3. Fügen Sie einen Bindestrich vor jedem ASCII-Großbuchstaben A bis Z hinzu, und schreiben Sie den Buchstaben klein;
  4. Andere Zeichen bleiben unverändert.

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

Zugriff auf Werte

  • Attribute können mit dem camelCase-Namen/Schlüssel als Objekteigenschaft des dataset festgelegt und ausgelesen werden: element.dataset.keyname.
  • Attribute können auch mit der Klammer-Syntax festgelegt und ausgelesen werden: element.dataset['keyname'].
  • Mit dem in-Operator kann überprüft werden, ob ein bestimmtes Attribut existiert: 'keyname' in element.dataset. Beachten Sie, dass dies die Prototypenkette von dataset durchlaufen kann und möglicherweise unsicher ist, wenn Sie externen Code haben, der die Prototypenkette verunreinigen könnte. Es gibt mehrere Alternativen, wie z. B. Object.hasOwn(element.dataset, 'keyname'), oder einfach zu überprüfen, ob element.dataset.keyname !== undefined.

Werte festlegen

  • Beim Festlegen des Attributs wird sein Wert immer in eine Zeichenfolge 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

Eine 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