HTMLElement.dataset

Свойство HTMLElement.dataset предоставляет доступ как для чтения, так и для изменения всех пользовательских дата-атрибутов custom data attributes (data-*) , установленных у элемента. Это map of DOMString, одна запись для каждого пользовательского атрибута данных. Обратите внимание, свойство dataset доступно только для чтения. Для записи должны использоваться  его "свойства", которые представлены data-атрибутами. Также обратите внимание, что HTML data-атрибут и соответствующий ему DOM-dataset.property не имеют одно и то же имя, но они всегда похожи:

  • Имя пользовательского дата атрибута в HTML начинается с "data-". Оно может состоять из букв, цифр и символов: дефис-минус (-, U+002D), точка (.), двоеточие (:), подчёркивание (_). Имя НЕ МОЖЕТ включать в себя заглавные буквы.
  • Имя пользовательского дата-атрибута в Javascript — это имя того же атрибута в HTML, но с использованием нотации camelCase и без дефисов, точек и т.д.

    В дополнение к приведённой ниже информации вы найдёте руководство по использованию HTML data-атрибутов в нашей статье Использование data-атрибутов.

Преобразование имён

dash-style в camelCase: имя пользовательского дата-атрибута преобразуется в ключ для DOMStringMap по следующим правилам:

  • удаляется префикс data- (вместе с дефисом);
  • дефисы (U+002D) со следующими за ними ASCII-символами a-z в нижнем регистре: черта удаляется, а символ преобразуется в верхний регистр;
  • остальные символы (включая дефисы) остаются без изменений.

camelCase в dash-style: обратное преобразование ключа в имя атрибута производится по следующим правилам:

  • Ограничение: сразу после дефиса не может быть ASCII-символа a-z в нижнем регистре (до преобразования);
  • добавляется префикс data-;
  • все ASCII-символы A-Z в верхнем регистре заменяются на дефис с символом в нижнем регистре;
  • остальные символы остаются без изменений.

Ограничение в правилах гарантирует, что эти два преобразования являются обратными друг другу.

Например, атрибуту data-abc-def соответствует ключ abcDef.

Доступ к значениям

  • Атрибуты можно устанавливать и считывать по имени в camelCase (ключ) как свойство объекта dataset, например element.dataset.keyname
  • Атрибуты также можно устанавливать и считывать с использованием доступа к свойствам объекта через квадратные скобки, например element.dataset[keyname]
  • Оператор in может быть использован для проверки существования атрибута.

Синтаксис

  • 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.

Примеры

<div id="user" data-id="1234567890" data-user="johndoe" data-date-of-birth>John Doe</div>

let el = document.querySelector('#user');

// el.id == 'user'
// el.dataset.id === '1234567890'
// el.dataset.user === 'johndoe'
// el.dataset.dateOfBirth === ''

el.dataset.dateOfBirth = '1960-10-03'; // set the DOB.

// 'someDataAttr' in el.dataset === false
el.dataset.someDataAttr = 'mydata';
// 'someDataAttr' in el.dataset === true

Specifications

Specification Status Comment
HTML Living Standard
Определение 'HTMLElement.dataset' в этой спецификации.
Живой стандарт No change from latest snapshot, HTML 5.1
HTML 5.1
Определение 'HTMLElement.dataset' в этой спецификации.
Рекомендация Snapshot of HTML Living Standard, no change from HTML5
HTML5
Определение 'HTMLElement.dataset' в этой спецификации.
Рекомендация Snapshot of  HTML Living Standard, initial definition.

Совместимость с браузерами

BCD tables only load in the browser

Смотрите также