La propiedad dataset
en HTMLElement
proporciona una interfaz lectura/escritura para obtener todos los atributos de datos personalizados (data-*
) de cada uno de los elementos. Está disponible el acceso en HTML y en el DOM. Dentro del map of DOMString, aparece una entrada por cada atributo de datos. Hay que tener en cuenta que la propiedad dataset
puede leerse, pero no modificarse directamente. En vez de eso, las escrituras deben ser realizadas a través de cada propiedad individual del dataset
, que representan a cada atributo correspondiente. Además un HTML data-
attribute y su correspondiente DOM dataset.
property no comparten el mismo nombre, pero son siempre similares:
- El nombre de un attributo de datos comienza en HTML con
data-
. Sólo puede estar formado por letras minúsculas, números y los caracteres: guión (-
), punto (.
), dos puntos (:
) y guión bajo (_
) -- NUNCA una letra mayúscula (A a Z). - El nombre del atributo en JavaScript será el del correspondiente atributo HTML pero en camelCase, sin guiones, puntos, etc.
Adicionalmente, encontrarás una guía de como usar los atributos data de HTML en nuestro articulo Using data attributes.
Conversion de nombres
dash-style
a camelCase
: Un atributo de datos personalizado se transforma en una clave para la entrada DOMStringMap
con las siguientes reglas
- el prefijo
data-
es eliminado (incluyendo el guión); - por cada guión (
U+002D
) seguido de un caracter ASCII que sea una letra en minusculaa
a laz
, el guión es removido y la letra se transforma en su contraparte en mayuscula; - otros caracteres (incluyendo otros guines) se mantienen intactos.
camelCase
a dash-style
: La conversión opuesta, mapea una clave en un nombre de atributo, usa las siguientes reglas:
- Restricción: Un guión no debe ser inmediatamente seguido por un un caracter ASCII que sea una letra minuscula de la
a
a laz
(antes de la conversión); - se agrega el prefijo
data-
; - cualquier caracter ASCII que sea una letra mayuscula de la
A
a laZ
se convierte en un guión seguido de se contraparte en minuscula; - otros caracteres se mantienen intactos.
La restricción en las reglas anteriores aseguran que las dos conversiones sean inversas una a la otra.
Por ejemplo, el atributo nombrado data-abc-def
corresponde a la clave abcDef
.
Accediendo valores
- Los atributos pueden ser definidos y obtenidos usando el nombre camelCase (la clave) como la propiedad de un objeto del dataset, como en
element.dataset.keyname
- Los atributos tambien pueden ser definidos y obtenidos usando la sintaxis de corchetes, como en
element.dataset[keyname]
- El operador
in
puede ser usado para checar si un atributo dado existe.
Definiendo valores
- Cuando un atributo es definido, su valor siempre se convierte a string. Por ejemplo,
null
siempre se convierte en el string "null". - Cuando quieras remover un atributo, puedes usar el operador
delete
.
Sintaxis
- string = element.dataset.camelCasedName;
- element.dataset.camelCasedName = string;
- string = element.dataset[camelCasedName];
- element.dataset[camelCasedName] = string;
- Custom data attributes can also be set directly on HTML elements, but attribute names must use the data- syntax above.
Ejemplos
<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 === ''
// set the data attribute
el.dataset.dateOfBirth = '1960-10-03';
// Result: el.dataset.dateOfBirth === 1960-10-03
delete el.dataset.dateOfBirth;
// Result: el.dataset.dateOfBirth === undefined
// 'someDataAttr' in el.dataset === false
el.dataset.someDataAttr = 'mydata';
// Result: 'someDataAttr' in el.dataset === true
Especificaciones
Especificación | Estado | Comentario |
---|---|---|
HTML Living Standard La definición de 'HTMLElement.dataset' en esta especificación. |
Living Standard | No change from latest snapshot, HTML 5.1 |
HTML 5.1 La definición de 'HTMLElement.dataset' en esta especificación. |
Recommendation | Snapshot of HTML Living Standard, no change from HTML5 |
HTML5 La definición de 'HTMLElement.dataset' en esta especificación. |
Recommendation | Snapshot of HTML Living Standard, initial definition. |
Compatibilidad en navegadores
BCD tables only load in the browser
Ver también
- The HTML
data-*
class of global attributes. - Using data attributes
Element.getAttribute()
andElement.setAttribute()