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 schreibgeschützte dataset Eigenschaft des HTMLElement-Interfaces bietet Lese-/Schreibzugriff auf benutzerdefinierte Datenattribute (data-*) von Elementen. Es stellt eine Zeichenfolgenzuordnung (DOMStringMap) mit einem Eintrag für jedes data-*-Attribut bereit.

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

Ein HTML-data-*-Attribut und das entsprechende DOM dataset.property passen ihren gemeinsamen Namen an, abhängig davon, ob sie gelesen oder geschrieben werden:

In HTML

Der Attributname beginnt mit data-. Es 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 einzelne Bindestriche (-), um den "camel-cased" Namen der Eigenschaft zu kapitalisieren.

Zusätzlich zu den unten stehenden Informationen finden Sie eine Anleitung zur Verwendung von HTML-Daten attributen in unserem Artikel Using data attributes.

Namenskonvertierung

Umwandlung von dash-style in camelCase

Ein benutzerdefinierter Datenattributname wird wie folgt in einen Schlüssel für den DOMStringMap-Eintrag transformiert:

  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), dem ein ASCII-Kleinbuchstabe a bis z folgt, den Bindestrich entfernen und den Buchstaben groß schreiben;
  4. Andere Zeichen (einschließlich anderer Bindestriche) bleiben unverändert.
Umwandlung von camelCase in dash-style

Die entgegengesetzte Transformation, die einen Schlüssel in einen Attributnamen umwandelt, verwendet die folgenden Schritte:

  1. Einschränkung: Vor der Umwandlung darf ein Bindestrich nicht unmittelbar von einem ASCII-Kleinbuchstaben a bis z gefolgt werden;
  2. Das Präfix data- hinzufügen;
  3. Vor jedem ASCII-Großbuchstaben A bis Z einen Bindestrich 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 über den camelCase-Namen/Schlüssel als Objekteigenschaft des Datasets gesetzt und gelesen werden: element.dataset.keyname.
  • Attribute können auch mit der Klammernsyntax 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 Prototype-Kette von dataset durchläuft und unsicher sein kann, wenn Sie externen Code haben, der die Prototype-Kette verschmutzen könnte. Mehrere Alternativen existieren, wie Object.hasOwn(element.dataset, 'keyname'), oder einfach zu prüfen, ob element.dataset.keyname !== undefined.

Werte setzen

  • Wenn das Attribut gesetzt wird, wird sein Wert immer in eine Zeichenfolge 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