HTMLElement.dataset

La propriété HTMLElement.dataset en lecture seule permet l'accès, à la fois en mode lecture et écriture, à tous les attributs de données sur mesure (data-*) définis sur l'élément. C'est un tableau associatif de DOMString (map of DOMString), une entrée pour chaque attribut de données sur mesure.

Le nom d'un attribut de données sur mesure commence par data-. Il ne doit contenir que des lettres, des nombres et les caractères suivants : tiret (-), point (.), deux-points (:), tiret bas (_). De plus, il ne doit pas contenir des lettres majuscules ASCII (A à Z).

Un nom d'attribut de données sur mesure est transformé en clef pour l'entrée de la DOMStringMap avec les règles suivantes :

  • le préfixe data- est enlevé (y compris le tiret) ;
  • pour tout tiret (U+002D) suivi par une  lettre minuscule ASCII a à z, le tiret est enlevé et la lettre est transformée en la majuscule correspondante ;
  • les autres caractères (y compris les autres tirets) ne sont pas modifiés.

La transformation opposée, qui associe un nom d'attribut à une clef, utilise les règles suivantes :

  • Restriction : Aucun tiret ne doit être immédiatement suivi d'une lettre minuscule ASCII a à z (avant la transformation) ;
  • un préfixe data- est ajouté ;
  • toute lettre majuscule ASCII A à Z est transformée en un tiret suivi de la minuscule correspondante ;
  • les autres caractères ne sont pas modifiés.

La restriction dans les règles ci-dessus garantit que les deux transformations sont bien l'inverse l'une de l'autre.

Par exemple, l'attribut nommé data-abc-def correspond à la clef abcDef.

Syntaxe

chaîne = element.dataset.nomEnCamelCase;
element.dataset.nomEnCamelCase = chaîne;

Exemples

<div id="utilisateur" data-id="1234567890" data-utilisateur="Monsieur Tartempion" data-date-de-naissance>Monsieur Tartempion
</div>

var el = document.querySelector('#utilisateur');

// el.id == 'utilisateur'
// el.dataset.id === '1234567890'
// el.dataset.utilisateur === 'Monsieur Tartempion'
// el.dataset.dateDeNaissance === ''

el.dataset.dateDeNaissance = '1960-10-03'; // renseigne la date de naissance.

// 'unAttributDeDonnees' in el.dataset === false

el.dataset.unAttributDeDonnees = 'mes données';
// 'unAttributDeDonnees' in el.dataset === true

Spécifications

Spécification Statut Commentaire
WHATWG HTML Living Standard
La définition de 'HTMLElement.dataset' dans cette spécification.
Standard évolutif Pas de changement depuis le dernier instantané (snapshot), HTML5.1
HTML5.1
La définition de 'HTMLElement.dataset' dans cette spécification.
Version de travail Instantané de WHATWG HTML Living Standard, pas de changement depuis HTML5
HTML5
La définition de 'HTMLElement.dataset' dans cette spécification.
Recommendation Instantané de WHATWG HTML Living Standard, définition initiale.

Compatibilité des navigateurs

Fonctionnalité Chrome Firefox (Gecko) Internet Explorer Opera Safari
Support de base 8 6.0 (6.0) 11 11.10 6
Fonctionnalité Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Support de base (Oui) 6.0 (6) (Oui) (Oui) (Oui)

Voir aussi

  • La classe des attributs globaux HTML data-*.

Étiquettes et contributeurs liés au document

 Contributeurs à cette page : Hell_Carlito, Laurent_Lyaudet
 Dernière mise à jour par : Hell_Carlito,