`.dataset`

Простейший способ хранить данные в HTML и читать их из JavaScript.

Время чтения: 5 мин

Кратко

Скопировано

Свойство dataset позволяет считывать или устанавливать любые дата-атрибуты на HTML-элементе.

Дата-атрибут — это пользовательский атрибут на элементе, название которого начинается с data-, например data-testid. Дата атрибуты используются, чтобы хранить значения на элементах в HTML.

Как пишется

Скопировано

Обращение к свойству dataset вернёт объект со всеми дата-атрибутами, которые есть на элементе. Названиями полей в объекте будут имена дата-атрибутов после префикса data-. Например, если атрибут называется data-columns, то поле в объекте для этого атрибута будет называться columns.

        
          
          <h1>Известные ситхи</h1><ul>  <li data-id="1541" data-episode="1">Дарт Мол</li>  <li data-id="9434" data-episode="4">Дарт Вейдер</li>  <li data-id="5549" data-episode="4">Дарт Сидиус</li></ul>
          <h1>Известные ситхи</h1>
<ul>
  <li data-id="1541" data-episode="1">Дарт Мол</li>
  <li data-id="9434" data-episode="4">Дарт Вейдер</li>
  <li data-id="5549" data-episode="4">Дарт Сидиус</li>
</ul>

        
          
          const items = document.querySelectorAll('li')const firstItem = items[0]console.log(firstItem.dataset)// { id: '1541', episode: '1' }
          const items = document.querySelectorAll('li')

const firstItem = items[0]

console.log(firstItem.dataset)
// { id: '1541', episode: '1' }

Если дата-атрибутов на элементе нет, то вернётся пустой объект:

        
          
          const heading = document.querySelector('h1')console.log(heading.dataset)// {}
          const heading = document.querySelector('h1')

console.log(heading.dataset)
// {}

Чтобы добавить дата-атрибут к элементу, нужно добавить новое поле в объект dataset. Название поля так же должно быть без префикса data-, браузер автоматически подставит его. В значениях атрибутов в HTML могут быть только строки, потому любое значение будет автоматически приведено к строке.

Возьмём тот же HTML из примера выше и добавим дата-атрибуты ко второму элементу:

        
          
          const items = document.querySelectorAll('li')const secondItem = items[1]secondItem.dataset.side = 'evil'secondItem.dataset.age = 46secondItem.dataset.lightsaber = { color: 'red' }
          const items = document.querySelectorAll('li')

const secondItem = items[1]

secondItem.dataset.side = 'evil'
secondItem.dataset.age = 46
secondItem.dataset.lightsaber = { color: 'red' }

В результате получим такой элемент:

        
          
          <li  data-id="9434"  data-episode="4"  data-side="evil"  data-age="46"  data-lightsaber="[object Object]">  Дарт Вейдер</li>
          <li
  data-id="9434"
  data-episode="4"
  data-side="evil"
  data-age="46"
  data-lightsaber="[object Object]">
  Дарт Вейдер
</li>

Все нестроковые значения, установленные в dataset, будут приводиться к строке. Поэтому объект превращается в [object Object], а число 46 — в строку "46".

Если в dataset добавить поле с пустым значением, то в HTML будет создан дата-атрибут без значения.

Использование camelCase и kebab-case

Скопировано

В dataset необходимо присваивать поля, названия которых записываются в одно слово. Потому для составных имён используется только camelCase-нотация. При попытке присвоить название в kebab-case будет выброшена ошибка.

        
          
          const body = document.querySelector('body')body.dataset['dark-theme'] = true// Uncaught DOMException: Failed to set// a named property on 'DOMStringMap':// 'dark-theme' is not a valid property name
          const body = document.querySelector('body')

body.dataset['dark-theme'] = true

// Uncaught DOMException: Failed to set
// a named property on 'DOMStringMap':
// 'dark-theme' is not a valid property name

Дата-атрибуты, записанные в dataset с помощью camelCase, в HTML будут иметь названия в kebab-case. Браузер преобразует camelCase в kebab-case:

        
          
          <ul>  <li>Иван Иванов</li></ul>
          <ul>
  <li>Иван Иванов</li>
</ul>

        
          
          const item = document.querySelector('li')item.dataset.yearsOfExperience = 2item.dataset.candidateRole = 'junior'
          const item = document.querySelector('li')

item.dataset.yearsOfExperience = 2
item.dataset.candidateRole = 'junior'

После выполнения кода выше получится следующий HTML:

        
          
          <ul>  <li data-candidate-role="junior" data-years-of-experience="2">    Иван Иванов  </li></ul>
          <ul>
  <li data-candidate-role="junior" data-years-of-experience="2">
    Иван Иванов
  </li>
</ul>

Преобразование названий работает и в обратную сторону – дата-атрибут на HTML-элементе, записанный в kebab-case, будет превращён в dataset в camelCase.

        
          
          <ul>  <li data-candidate-role="junior">Иван Иванов</li></ul>
          <ul>
  <li data-candidate-role="junior">Иван Иванов</li>
</ul>

        
          
          const item = document.querySelector('li')console.log(item.dataset)// { candidateRole: 'junior' }
          const item = document.querySelector('li')

console.log(item.dataset)
// { candidateRole: 'junior' }

Удаление дата-атрибута

Скопировано

Удалить дата-атрибут можно только с помощью оператора delete. Если попытаться присвоить к полю значение undefined или null, то браузер просто присвоит атрибуту строку 'undefined' или 'null'.

Возьмём следующий HTML:

        
          
          <div data-testid="test">Любое содержимое<div>
          <div data-testid="test">Любое содержимое<div>

При установке undefined в значение дата-атрибута, он не удалится с элемента.

        
          
          const element = document.querySelector('div')element.dataset.testid = undefined
          const element = document.querySelector('div')

element.dataset.testid = undefined

В результате получится следующий HTML:

        
          
          <div data-testid="undefined">Любое содержимое<div>
          <div data-testid="undefined">Любое содержимое<div>

Если использовать оператор delete, то получим элемент без дата-атрибута.

        
          
          delete element.dataset.testid
          delete element.dataset.testid

        
          
          <div>Любое содержимое</div>
          <div>Любое содержимое</div>

Свойство dataset защищено от перезаписи. Это значит, что попытка присвоить в dataset новое значение будет проигнорирована.

        
          
          const element = document.querySelector('div')// Ничего не произойдёт, дата-атрибуты// на элементах тоже не изменятсяelement.dataset = {}element.dataset = 'string'
          const element = document.querySelector('div')

// Ничего не произойдёт, дата-атрибуты
// на элементах тоже не изменятся
element.dataset = {}
element.dataset = 'string'

Как понять

Скопировано

Дата-атрибуты появились в HTML5 и добавили возможность разработчикам добавлять свои собственные атрибуты к элементам. Причин для использования таких атрибутов можно придумать множество. Чаще всего в дата-атрибутах хранят нужные значения, которые используют в CSS или JavaScript.

Дата-атрибуты были созданы специально для того, чтобы хранить и работать с данными прямо в HTML. Отсюда и префикс data, что в переводе значит данные. Например, с помощью дата-атрибутов можно хранить значение выбранное в выпадающем списке прямо на элементе.

Хранение данных на HTML-элементах так же полезно для инициализации виджетов в JavaScript. Они могут находить нужные элементы, используя дата-атрибут как селектор, и читать данные из атрибута. Например, в многостраничных приложениях HTML генерируется на сервере, и готовая страница отправляется в ответ на запрос. Во время генерации в HTML можно подставить дата-атрибуты с данными с сервера, и, таким образом, пробросить их в JavaScript.

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

Дата-атрибутов на элементе может быть сколько угодно, потому удобно располагать отдельные кусочки данных в свой атрибут. Такого точно нельзя достичь, используя только идентификатор.

Браузер даёт возможность управлять дата-атрибутами через специальное API dataset.

На практике

Скопировано

Егор Огарков советует

Скопировано

🛠 Дата-атрибут можно использовать для применения стилей. Элементы можно выделять CSS-селектора по атрибуту:

        
          
          [data-id] {  /* Селектор для всех элементов с data-id */}[data-id="123"] {  /* Селектор только для элементов с data-id="123" */}
          [data-id] {
  /* Селектор для всех элементов с data-id */
}

[data-id="123"] {
  /* Селектор только для элементов с data-id="123" */
}

Найти элемент с data-id="123":

        
          
          const element = document.querySelector('[data-id="123"]')
          const element = document.querySelector('[data-id="123"]')

🛠 Некоторые фреймворки во время компиляции самостоятельно генерируют дата-атрибуты и присваивают их к элементам, чтобы делать изоляцию CSS.

🛠 Дата-атрибуты широко используются в автоматизированном тестировании. Для этого на необходимых элементах расставляют дата-атрибуты, и тест обращается к ним. В документациях к различным библиотекам для тестирования часто можно встретить атрибут data-testid.

Кратко

Как пишется

Использование camelCase и kebab-case

Удаление дата-атрибута

Как понять

На практике

Егор Огарков советует

Читайте также

DOM

Хранение данных в браузере

Событийная модель