HTMLElement：dataset 属性

dataset 是 HTMLElement 接口的只读属性，提供对元素上的 自定义数据属性 (data-*) 的读写访问。它公开了一个字符串映射 (DOMStringMap)，其中每个 data-* 属性对应一个条目。

注意：dataset 属性本身可以读取，但不能直接写入。相反，所有写入都必须针对 dataset 中的各个属性，而这些属性又代表数据属性。

HTML data-* 属性及其对应的 DOM dataset.property 会根据读取或写入的位置修改其共享名称。

在 HTML 中

属性名称以 data- 开头。它只能包含字母、数字、连字符 (-)、句点 (.)、冒号 (:) 和下划线 (_)。任何 ASCII 大写字母 (A 到 Z) 都将转换为小写。

在 JavaScript 中

自定义数据属性的属性名称与 HTML 属性相同，只是去掉了 data- 前缀，并且在属性的“驼峰式命名法”名称中移除单个连字符 (-) 以进行大写转换。

除了以下信息外，您还可以在我们的文章 使用数据属性 中找到有关如何使用 HTML 数据属性的指南。

名称转换

dash-style 到 camelCase 转换

自定义数据属性名称通过以下方式转换为 DOMStringMap 条目的键：

  1. 将所有 ASCII 大写字母 (A 到 Z) 转换为小写；
  2. 移除前缀 data-（包括连字符）；
  3. 对于任何后跟 ASCII 小写字母 a 到 z 的连字符 (U+002D)，移除连字符并将字母转换为大写；
  4. 其他字符（包括其他连字符）保持不变。
camelCase 到 dash-style 转换

相反的转换，即从键映射到属性名称，使用以下方法：

  1. 限制：转换前，连字符不能紧跟 ASCII 小写字母 a 到 z；
  2. 添加 data- 前缀；
  3. 在任何 ASCII 大写字母 A 到 Z 之前添加连字符，然后将字母转换为小写；
  4. 其他字符保持不变。

例如，data-abc-def 属性对应于 dataset.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 = null 将转换为 data-example="null"。
  • 要移除属性，可以使用 delete 运算符：delete element.dataset.keyname。

值

一个 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 === ''

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

浏览器兼容性

BCD 表格仅在启用了 JavaScript 的浏览器中加载。

另请参阅