HTMLElement: dataset プロパティ

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

datasetHTMLElement インターフェイスの読み取り専用プロパティで、要素に設定されたすべてのカスタムデータ属性 (data-*) への読み取り/書き込みアクセスを提供します。これは文字列のマップである (DOMStringMap) で、それぞれの data-* 属性の項目です。

メモ: dataset プロパティ自体は読み取ることができますが、直接書き込むことはできません。 すべての書き込みは、個々の data 属性を表す dataset 内の個々のプロパティを表します。

また、 HTML の data-* 属性とそれに対応する DOM の dataset.プロパティ は同じ名前にはなりませんが、次のように常に近いものになります。

HTML では

属性の名前は、 data- で始まります。文字、数字、ダッシュ (-)、ドット (.)、コロン (:)、アンダースコア (_) のみを入れることができます。ASCII 大文字の A から Z は小文字に変換されます。

JavaScript では

カスタムデータ属性のプロパティ名は、同じ HTML 属性の名前から data- の接頭辞を除いたものですが、そのプロパティのキャメルケースの名前であり、単一のダッシュ (-) を除いたものです。

以下の情報に加えて、データ属性の使用の記事に、HTML データ属性の使用方法に関するガイドがあります。

名前の変換

ダッシュスタイルからキャメルケースへの変換

カスタムデータ属性名は、次のルールに従って DOMStringMap 項目のキーに変換されます。

  1. すべての ASCII の大文字 (A から Z まで) を小文字にします。
  2. 接頭辞の data- を(ダッシュを含め)削除します。
  3. ダッシュ (U+002D) に ASCII 小文字の a から z が続く場合、ダッシュを削除し、その文字を対応する大文字に変換します。
  4. 他の文字 (他のダッシュを含む) は変更しません。
キャメルケースからダッシュスタイルへの変換

キーを属性名にマッピングする逆の変換では、以下のように次のルールが使用されます。

  1. 制約事項: 変換前に置いて、ダッシュの直後に ASCII 小文字 a から z を続けてはなりません。
  2. 接頭辞として data- が追加されます。
  3. ASCII 大文字の A から Z は、ダッシュと、その後に対応する小文字が続くものに変換されます。
  4. 他の文字は変更しません。

例えば、data-abc-def という名前の属性は、キー abcDef に対応します。

値へのアクセス

  • 属性は 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 = nulldata-example="null" に変換されます。

  • 属性を削除する場合は、delete 演算子が使用できます。

DOMStringMap です。

html
<div id="user" data-id="1234567890" data-user="carinaanand" data-date-of-birth>
  Carina Anand
</div>
js
const el = document.querySelector("#user");

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

// データ属性の設定
el.dataset.dateOfBirth = "1960-10-03";
// JS での結果: el.dataset.dateOfBirth === '1960-10-03'
// HTML での結果: <div id="user" data-id="1234567890" data-user="carinaanand" data-date-of-birth="1960-10-03">Carina Anand</div>

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

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

仕様書

Specification
HTML
# dom-dataset-dev

ブラウザーの互換性

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
dataset

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support

関連情報