HTMLElement.dataset

This translation is incomplete. Please help translate this article from English

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 minuscula a a la z, el guión es removido y la letra se transforma en su contraparte en mayuscula;
  • otros caracteres (incluyendo otros guines) se mantienen intactos.

camelCasedash-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 la z (antes de la conversión);
  • se agrega el prefijo data-;
  • cualquier caracter ASCII que sea una letra mayuscula de la A a la Z 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

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome para AndroidFirefox para AndroidOpera para AndroidSafari en iOSSamsung Internet
datasetChrome Soporte completo 8Edge Soporte completo 12Firefox Soporte completo 6IE Soporte completo 11Opera Soporte completo 11Safari Soporte completo 5.1WebView Android Soporte completo 4.4Chrome Android Soporte completo 18Firefox Android Soporte completo 6Opera Android Soporte completo 11Safari iOS Soporte completo 5.1Samsung Internet Android Soporte completo 1.0

Leyenda

Soporte completo  
Soporte completo

Ver también