HTMLElement.dataset

La propriété en lecture seule dataset, rattachée à l'interface HTMLElement, fournit un accès en lecture/écriture aux attributs de données (data-*) de l'élément. Elle expose un objet DOMStringMap (en-US) avec un élément pour chaque attribut data-*.

Note : La propriété dataset elle-même peut être lue mais pas modifiée directement. Pour appliquer des modifications, il faudra les appliquer sur chaque propriété contenue dans dataset, qui représente chacune un attribut de données.

Un attribut HTML data-* et la propriété du DOM dataset.propriete ont des différences de nom selon le contexte où on les manipule :

En HTML

Le nom de l'attribut commence par data-. Il ne peut contenir que des lettres, des nombres, des tirets (-), des points (.), des doubles-points (:), et des tirets bas (_). Les lettres majuscules ASCII (A à Z) sont converties en minuscules.

En JavaScript

Le nom de la propriété est le même que celui de l'attribut auquel on a retiré le préfixe data-, et on retire les tirets (-) en mettant les lettres qui suivent en majuscules afin d'obtenir une camelCase.

En plus des informations présentées ci-après, vous pourrez trouver un guide sur l'utilisation des attributs de données HTML dans l'article Utiliser les attributs de données.

Conversion des noms

Conversion du format HTML avec les tirets au format JavaScript camelCase

Le nom d'un attribut de données est transformé en clé d'un élément DOMStringMap (en-US) en suivant l'algorithme suivant :

  1. Toutes les lettres ASCII majuscules (A à Z) sont converties en minuscules ;
  2. Le préfixe data- est retiré (tiret complet) ;
  3. Pour tout tiret (U+002D) suivi d'une lettre ASCII minuscule (a à z), on retire le tiret et on convertit la lettre en majuscule ;
  4. Les autres caractères (y compris les autres tirets) sont laissés inchangés.
Conversion du format JavaScript camelCase au format HTML avec les tirets

La transformation symétrique, permettant de passer d'une clé de propriété à un nom d'attribut, se fait avec l'algorithme suivant :

  1. Vérification : Avant toute transformation, un tiret ne doit pas être immédiatement suivi d'une lettre ASCII en minuscule (a à z) ;
  2. Le préfixe data- est ajouté ;
  3. On ajoute un tiret devant chaque lettre ASCII majuscule (A à Z), et on convertit la lettre en minuscule ;
  4. Les autres caractères sont laissés inchangés.

Ainsi, l'attribut HTML data-abc-def correspondra à la propriété JavaScript dataset.abcDef.

Accéder aux valeurs

  • Il est possible d'accéder aux valeurs d'un attribut et de le modifier en utilisant le nom de la clé comme propriété de l'objet : element.dataset.nomcle
  • Il est aussi possible de lire et d'écrire les attributs avec la notation entre crochets : element.dataset['nomcle']
  • L'opérateur in permet de vérifier si un attribut donné existe : 'nomcle' in element.dataset

Définir des valeurs

  • Lorsqu'on définit l'attribut, sa valeur est convertie en une chaîne de caractères. Par exemple : element.dataset.exemple = null sera converti en data-exemple="null".
  • Pour retirer un attribut, on utilisera l'opérateur delete : delete element.dataset.nomCle

Valeur

Un objet DOMStringMap (en-US).

Exemples

<div id="user" data-id="1234567890" data-user="johndoe" data-date-of-birth>John Doe</div>

const el = document.querySelector('#user');

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

// on définit un attribut de données
el.dataset.dateOfBirth = '1960-10-03';
// Résultat en JavaScript : el.dataset.dateOfBirth === '1960-10-03'
// Résultat en HTML : <div id="user" data-id="1234567890" data-user="johndoe" data-date-of-birth="1960-10-03">John Doe</div>

delete el.dataset.dateOfBirth;
// Résultat en JavaScript : el.dataset.dateOfBirth === undefined
// Résultat en HTML : <div id="user" data-id="1234567890" data-user="johndoe">John Doe</div>

if ('unAttrDonnee' in el.dataset === false) {
  el.dataset.unAttrDonnee = 'mesdonnees';
  // Résultat en JS : 'unAttrDonnee' in el.dataset === true
  // Résultat en HTML : <div id="user" data-id="1234567890" data-user="johndoe" data-un-attr-donnee = "mesdonnees">John Doe</div>
}

Spécifications

Specification
HTML Standard
# dom-dataset-dev

Compatibilité des navigateurs

BCD tables only load in the browser

Voir aussi