Enter
    Расширенный поиск
    Клавиша / esc

    JavaScript

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

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

    • DOM

      На чём стоят три слона, на которых держится веб?

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

      Браузер даёт кучу инструментов, чтобы хранить данные. Какой выбрать, чтобы в итоге не забивать гвозди микроскопом?

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

      Что такое события в браузере и почему без них не написать ни одного приложения.