/ ↲
    Расширенный поиск

    JavaScript

    .dataset

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

    1. Кратко
    2. Как пишется
      1. Использование camelCase и kebab-case
      2. Удаление дата-атрибута
    3. Как понять
    4. На практике
      1. windrushfarer

    Кратко

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

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

    Как пишется

    Обращение к Element.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]// Вернёт { id: '1541', episode: '1' }firstItem.dataset
          const items = document.querySelectorAll('li')

const firstItem = items[0]

// Вернёт { id: '1541', episode: '1' }
firstItem.dataset

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

            
          
          const heading = document.querySelector('h1')// Вернёт пустой объект {}, так как нет дата-атрибутовheading.dataset
          const heading = document.querySelector('h1')

// Вернёт пустой объект {}, так как нет дата-атрибутов
heading.dataset

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

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

            
          
          // Используем тот же HTML из примера вышеconst items = document.querySelectorAll('li')const secondItem = items[1]// Объекты тоже приводятся в строкеsecondItem.dataset.side = 'evil'secondItem.dataset.age = 46secondItem.dataset.lightsaber = { color: 'red' }
          // Используем тот же HTML из примера выше
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>

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

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

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

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

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

        
        
          
        
      
            
          
          const item = document.querySelector('li')// Создаст дата-атрибут data-years-of-experience="1"item.dataset.yearsOfExperience = 2// Создаст дата-атрибут data-candidate-role="junior"item.dataset.candidateRole = 'junior'
          const item = document.querySelector('li')

// Создаст дата-атрибут data-years-of-experience="1"
item.dataset.yearsOfExperience = 2

// Создаст дата-атрибут data-candidate-role="junior"
item.dataset.candidateRole = 'junior'

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

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

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

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

        
        
          
        
      
            
          
          const item = document.querySelector('li')// Вернёт { candidateRole: 'junior' }item.dataset
          const item = document.querySelector('li')

// Вернёт { candidateRole: 'junior' }
item.dataset

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

    Удалить дата-атрибут можно только с помощью оператора 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>

    Element.dataset защищён от перезаписи. Это значит что попытка присвоить в Element.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 Element.dataset.

    На практике

    windrushfarer

    🛠 Дата-атрибут можно использовать в качестве CSS-селектора

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

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

        
        
          
        
      
            
          
          const element = document.querySelector('[data-id="123"]') // Найти элемент с data-id="123"
          const element = document.querySelector('[data-id="123"]') // Найти элемент с data-id="123"

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

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