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

瀏覽器相容性

另見