HTMLElement: свойство dataset

Базовая Широко доступна

Эта функция хорошо зарекомендовала себя и работает на многих устройствах и версиях браузеров. Она доступна в браузерах с июля 2015 года.

dataset чтение свойство интерфейса HTMLElement предоставляет чтение/запись доступа к настраиваемым атрибутам данных (data-*) элементов. Оно экспонирует карту строк (DOMStringMap) с записью для каждого data-* атрибута.

Примечание: Само свойство dataset может быть прочитано, но не может быть напрямую записано. Вместо этого все записи должны выполняться в отдельных свойствах внутри dataset, которые, в свою очередь, представляют атрибуты данных.

HTML data-* атрибут и его соответствующий DOM dataset.property изменяют свое общее имя в зависимости от того, где они читаются или записываются:

В HTML: Имя атрибута начинается с data-. Оно может содержать только буквы, цифры, дефисы (-), точки (.), двоеточия (:) и подчеркивания (_). Любые символы ASCII с заглавными буквами (A по Z ) преобразуются в нижний регистр.
В JavaScript: Имя свойства настраиваемого атрибута данных такое же, как у HTML-атрибута без префикса data- . Одиночные дефисы (- ) удаляются, а следующий символ ASCII после удаленного дефиса приводится к верхнему регистру, образуя именованное свойство по правилам camelCase.

Подробное описание и примеры преобразования между форматами HTML и JavaScript представлены в следующем разделе.

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

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

Преобразование dash-style в camelCase

Имя настраиваемого атрибута данных преобразуется в ключ для записи в DOMStringMap следующим образом:

Все заглавные буквы ASCII (A по Z ) переводятся в нижний регистр;
Удаляется префикс data- (включая дефис);
Для любого дефиса (U+002D) за которым следует строчная буква ASCII (a по z) удаляется дефис и буква приводится к верхнему регистру;
Другие символы (включая другие дефисы) остаются неизменными.

Преобразование camelCase в dash-style

Обратное преобразование, которое сопоставляет ключ с именем атрибута, использует следующее:

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

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

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

Атрибуты можно установить и прочитать по имени camelCase/ключу как свойство объекта dataset: element.dataset.keyname.
Атрибуты также можно установить и прочитать с помощью синтаксиса с квадратными скобками: element.dataset['keyname'].
Оператор in может проверить, существует ли данный атрибут: 'keyname' in element.dataset. Обратите внимание, что это пройдёт по цепочке прототипов dataset и может быть небезопасно, если у вас есть внешний код, который может загрязнять цепочку прототипов. Существуют альтернативы, такие как Object.hasOwn(element.dataset, 'keyname'), или просто проверить, существует ли element.dataset.keyname !== undefined.

Установка значений

При установке атрибута его значение всегда преобразуется в строку. Например: element.dataset.example = null преобразуется в data-example="null".
Чтобы удалить атрибут, можно использовать оператор delete: delete element.dataset.keyname.

Значение

A DOMStringMap.

Примеры

<div id="user" data-id="1234567890" data-user="carinaanand" data-date-of-birth>
  Carina Anand
</div>

const el = document.querySelector("#user");

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

// set a data attribute
el.dataset.dateOfBirth = "1960-10-03";
// Result on JS: el.dataset.dateOfBirth === '1960-10-03'
// Result on HTML: <div id="user" data-id="1234567890" data-user="carinaanand" data-date-of-birth="1960-10-03">Carina Anand</div>

delete el.dataset.dateOfBirth;
// Result on JS: el.dataset.dateOfBirth === undefined
// Result on HTML: <div id="user" data-id="1234567890" data-user="carinaanand">Carina Anand</div>

if (el.dataset.someDataAttr === undefined) {
  el.dataset.someDataAttr = "mydata";
  // Result on JS: 'someDataAttr' in el.dataset === true
  // Result on HTML: <div id="user" data-id="1234567890" data-user="carinaanand" data-some-data-attr="mydata">Carina Anand</div>
}

Спецификации

Спецификация
HTML # dom-dataset-dev

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

	Рабочие столы					Мобильные устройства
	Chrome	Edge	Firefox	Opera	Safari	Chrome Android	Firefox for Android	Opera Android	Safari на IOS	Samsung Internet	WebView Android
`dataset`	7	12	6	11	5.1	18	6	11	5	1.0	3

См. также

Класс HTML-атрибутов data-*
Использование атрибутов данных
Element.getAttribute() и Element.setAttribute()

© 2005–2024 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset