Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

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.

Fontes