HTML data-* 全局属性

data-* 全局属性构成了一类称为自定义数据属性的属性,它们允许专有信息在 HTML 和脚本的 DOM 表示之间进行交换。

试一试

<h1>Secret agents</h1>

<ul>
  <li data-id="10784">Jason Walters, 003: Found dead in "A View to a Kill".</li>
  <li data-id="97865">
    Alex Trevelyan, 006: Agent turned terrorist leader; James' nemesis in
    "Goldeneye".
  </li>
  <li data-id="45732">
    James Bond, 007: The main man; shaken but not stirred.
  </li>
</ul>
h1 {
  margin: 0;
}

ul {
  margin: 10px 0 0;
}

li {
  position: relative;
  width: 200px;
  padding-bottom: 10px;
}

li::after {
  content: "Data ID: " attr(data-id);
  position: absolute;
  top: -22px;
  left: 10px;
  background: black;
  color: white;
  padding: 2px;
  border: 1px solid #eeeeee;
  opacity: 0;
  transition: 0.5s opacity;
}

li:hover::after {
  opacity: 1;
}

所有这些自定义数据都可通过设置该属性的元素的 HTMLElement 接口进行访问。 HTMLElement.dataset 属性提供了对它们的访问。* 可以被任何符合 XML 名称生产规则 的名称替换,其中包括以下建议:

  • 名称不应以 xml (不区分大小写) 开头,因为它被保留给未来的 XML 规范。
  • 名称不应包含任何冒号字符 (:),因为 XML 会赋予这些名称特定的含义。
  • 名称不应包含任何大写字母,因为 XML 全是小写。

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

如果您计划使用 HTMLElement.dataset,则 data- 后面的属性名称部分只能包含 JavaScript 属性名称允许的字符(以及将被移除的连字符)。属性名称的 dataset 版本会移除 "data-" 前缀,并将剩余的名称从 kebab-case 转换为 camelCase。例如,element.getAttribute("data-test") 等同于 element.dataset.test,而 data-test-abc 将可以作为 HTMLElement.dataset.testAbc 访问(或通过 HTMLElement.dataset["testAbc"])。避免在连字符后使用非字母字符,例如 data-test-1data--test,因为它们不会被 HTMLElement.dataset 识别。

用法说明

通过添加 data-* 属性,即使是普通的 HTML 元素也可以变成相当复杂和强大的程序对象。例如,游戏中的一个太空飞船“sprite 可以只是一个带有 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" />
js
function clickSpaceship() {
  spaceships[this.dataset.shipId].blasted();
}

document.querySelectorAll("img.spaceship").forEach((ship) => {
  ship.addEventListener("click", clickSpaceship);
});

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

规范

规范
HTML
# attr-data-*

浏览器兼容性

另见