CKTIS / JavaScript
HTMLElement.dataset — acesso aos atributos data-*
HTMLElement.dataset expõe os atributos data-* de um elemento como um DOMStringMap. Permite ler, escrever e eliminar dados de texto, associando, por exemplo, data-user-id a userId.
Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Sintaxe
element.dataset.key
element.dataset.key = value;
element.dataset[key] = value;
delete element.dataset.key;HTMLElement.dataset devolve um DOMStringMap associado ao elemento, e não uma cópia independente dos dados. As alterações às propriedades atualizam os atributos data-*, e vice-versa. A propriedade dataset em si é apenas de leitura; são as suas propriedades que se alteram.
O mapeamento dos nomes remove o prefixo data-; um hífen antes de uma letra ASCII minúscula é removido e essa letra passa a maiúscula: data-user-id → userId. Os restantes caracteres mantêm-se inalterados. Ao escrever, as letras ASCII maiúsculas passam a um hífen seguido da letra minúscula. Escrever uma chave que contenha um hífen antes de uma letra ASCII minúscula, como dataset['user-id'], lança SyntaxError.
Os valores são cadeias de caracteres: converta os números explicitamente. Atribuir null guarda o texto "null", em vez de remover o atributo. Use delete element.dataset.userId para o remover. Se a chave userId não existir, o resultado é undefined.
Esta é uma interface do HTML Living Standard, não uma funcionalidade de uma edição específica do ECMAScript. Os motores de navegador atuais suportam-na; a presença de Node 24 num repositório não demonstra que o DOM esteja disponível.
Exemplos
const element = document.createElement('div');
element.setAttribute('data-user-id', '42');
console.log(element.dataset.userId);
element.dataset.userId = Number(element.dataset.userId) + 1;
console.log(element.getAttribute('data-user-id'));
console.log(typeof element.dataset.userId);
delete element.dataset.userId;
console.log(element.hasAttribute('data-user-id'));Resultado
42 43 string false
O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.