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 der HTMLElement-Schnittstelle ist nur lesbar und bietet Lese- und Schreibzugriff auf benutzerdefinierte Datenattribute (data-*) an Elementen. Sie gibt eine Zeichenkette-Karte (DOMStringMap) mit einem Eintrag für jedes data-*-Attribut zurück.

Hinweis: Die dataset-Eigenschaft selbst kann gelesen, aber nicht direkt beschrieben werden. Stattdessen müssen alle Schreibvorgänge an den einzelnen Eigenschaften innerhalb des dataset erfolgen, die wiederum die Datenattribute darstellen.

Ein HTML-data-*-Attribut und das entsprechende DOM dataset.property ändern ihren gemeinsamen Namen entsprechend dem Ort, an dem sie gelesen oder beschrieben 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 Eigenschaftsname eines benutzerdefinierten Datenattributs entspricht dem HTML-Attribut ohne das data--Präfix und entfernt einfache Bindestriche (-) für das CamelCase-Schreiben des Eigenschaftsnamens.

Zusätzlich zu den untenstehenden Informationen finden Sie eine Anleitung zur Verwendung von HTML-Datenattributen in unserem Artikel Verwendung von Datenattributen.

Namensumwandlung

Umwandlung von dash-style zu camelCase

Ein benutzerdefinierter Datenattributname wird durch folgendes 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. Für jeden Bindestrich (U+002D), dem ein ASCII-Kleinbuchstabe a bis z folgt, den Bindestrich entfernen und den Buchstaben großschreiben;
  4. Andere Zeichen (einschließlich weiterer Bindestriche) bleiben unverändert.
Umwandlung von camelCase zu dash-style

Die gegenteilige Transformation, die einen Schlüssel in einen Attributnamen umwandelt, verwendet das Folgende:

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

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

Zugriff auf Werte

  • Attribute können durch den camelCase-Namen/Schlüssel als Objekteigenschaft des datasets gesetzt und gelesen werden: element.dataset.keyname.
  • Attribute können auch mit der Klammernschreibweise gesetzt und gelesen werden: element.dataset['keyname'].
  • Der in-Operator kann prüfen, ob ein gegebenes Attribut existiert: 'keyname' in element.dataset. Beachten Sie, dass dies die Prototypenkette des dataset durchlaufen wird und unsicher sein kann, wenn Sie externen Code haben, der die Prototypenkette beeinflussen könnte. Mehrere Alternativen existieren, wie z.B. Object.hasOwn(element.dataset, 'keyname'), oder einfach zu prüfen, ob element.dataset.keyname !== undefined.

Setzen von Werten

  • Wenn das Attribut gesetzt wird, wird sein Wert immer in eine Zeichenkette konvertiert. Zum Beispiel: element.dataset.example = null wird in data-example="null" konvertiert.

  • 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 Standard
# dom-dataset-dev

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch