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 может быть использован для проверки существования атрибута.

Syntax

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

Examples

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

Browser compatibility

We're converting our compatibility data into a machine-readable JSON format. This compatibility table still uses the old format, because we haven't yet converted the data it contains. Find out how you can help!
Feature Chrome Edge Firefox (Gecko) Internet Explorer Opera Safari
Basic support 8 (Да) 6.0 (6.0) 11 11.10 6
Feature Android Edge Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support (Да) (Да) 6.0 (6) (Да) (Да) (Да)

See also