data-*

data-* 全局属性是一类被称为自定义数据属性的属性,可以通过脚本在 HTMLDOM 表示之间进行专有数据的交换。

尝试一下

所有这些自定义数据属性都可以通过所属元素的 HTMLElement 接口来访问。HTMLElement.dataset 属性可以访问它们。* 可以使用遵循 XML 名称生产规则 的任何名称来被替换,并具有以下限制:

  • 该名称不应以 xml 开头(不区分大小写),因为它是为未来的 XML 规范保留的。
  • 该名称不应包含任何冒号字符(:),因为 XML 会赋予此类名称意义。
  • 该名称不应包含任何大写字母,因为 XML 都是小写字母。

这些都是建议。如果不遵循这些命名建议,将不会发生错误。属性仍将使用 CSS 属性选择器进行匹配,属性不区分大小写,任何属性值都区分大小写。不符合这三项建议的属性仍将被 JavaScript HTMLElement.dataset 属性识别,用户代理将把该属性包含在包含 HTMLElement 的所有自定义数据属性的 DOMStringMap 中。

如果计划使用 HTMLElement.dataset,那么属性名中 data- 后面的部分只能包含 JavaScript 属性名中允许使用的字符(以及连字符,连字符将被删除)。属性名的 dataset 版本会去掉“data-”前缀,并将名称的其余部分从烤串命名法转换为驼峰命名法。例如,element.getAttribute("data-test") 等同于 element.dataset.test,而 data-test-abc 将以 HTMLElement.dataset.testAbc(或 HTMLElement.dataset["testAbc"])的形式访问。避免使用连字符后的非字母字符,如 data-test-1data--test,因为 HTMLElement.dataset 无法识别这些字符。

用法

通过添加 data-* 属性,即使是普通的 HTML 元素也能变成相当复杂且强大的编程对象。例如,在游戏里的太空船“精灵图”可以只是带有一个 class 属性和几个 data-* 属性的 <img> 元素:

html
<img
  class="spaceship cruiserX3"
  src="shipX3.png"
  data-ship-id="324"
  data-weapons="laserI laserII"
  data-shields="72%"
  data-x="414354"
  data-y="85160"
  data-z="31940"
  onclick="spaceships[this.dataset.shipId].blasted()" />

有关使用 HTML 数据属性的更深入的教程,请参阅使用数据属性

规范

Specification
HTML
# attr-data-*

浏览器兼容性

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
data-* attributes

Legend

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

Full support
Full support

参见