HTMLElement.dataset
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.
io error: No such file or directory (os error 2) (/home/runner/work/yari/yari/mdn/translated-content/files/fr/web/api/html_dom_api/index.md)
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
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 suivant l'algorithme suivant :- Toutes les lettres ASCII majuscules (
A
àZ
) sont converties en minuscules ; - Le préfixe
data-
est retiré (tiret complet) ; - Pour tout tiret (
U+002D
) suivi d'une lettre ASCII minuscule (a
àz
), on retire le tiret et on convertit la lettre en majuscule ; - Les autres caractères (y compris les autres tirets) sont laissés inchangés.
- Toutes les lettres ASCII majuscules (
- 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 :
- Vérification : Avant toute transformation, un tiret ne doit pas être immédiatement suivi d'une lettre ASCII en minuscule (
a
àz
) ; - Le préfixe
data-
est ajouté ; - On ajoute un tiret devant chaque lettre ASCII majuscule (
A
àZ
), et on convertit la lettre en minuscule ; - Les autres caractères sont laissés inchangés.
- Vérification : Avant toute transformation, un tiret ne doit pas être immédiatement suivi d'une lettre ASCII en minuscule (
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 endata-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
Specification |
---|
HTML Standard # dom-dataset-dev |
Compatibilité des navigateurs
BCD tables only load in the browser
Voir aussi
- L'ensemble d'attributs globaux HTML
data-*
. - Utiliser les attributs de données
Element.getAttribute()
etElement.setAttribute()