HTMLElement.dataset

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 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.

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

Compatibilité des navigateurs

Voir aussi

• L'ensemble d'attributs globaux HTML data-*.
• Utiliser les attributs de données
• Element.getAttribute() et Element.setAttribute()