HTMLElement: dataset 屬性
HTMLElement 介面的只讀屬性 dataset 提供了對元素上自定義資料屬性 (data-*) 的讀/寫訪問。它暴露了一個字串對映表 (DOMStringMap)，其中包含每個 data-* 屬性的條目。
注意： dataset 屬性本身可以讀取，但不能直接寫入。相反，所有寫入都必須針對 dataset 中的各個屬性進行，這些屬性代表了資料屬性。
HTML data-* 屬性及其對應的 DOM dataset.property 根據其讀取或寫入的位置修改其共享名稱。
- 在 HTML 中
-
屬性名稱以
data-開頭。它只能包含字母、數字、連字元 (-)、句點 (.)、冒號 (:) 和下劃線 (_)。任何 ASCII 大寫字母 (A到Z) 都將轉換為小寫。 - 在 JavaScript 中
-
自定義資料屬性的屬性名與 HTML 屬性名相同，但去掉了
data-字首。單連字元 (-) 會被移除，並且在移除的連字元後的下一個 ASCII 字元將被大寫，從而形成屬性的駝峰式命名。
HTML 和 JavaScript 格式之間的轉換的詳細資訊和示例將在下一節中更詳細地描述。
除了下面的資訊，您還可以在我們的文章 使用資料屬性 中找到有關使用 HTML 資料屬性的指南。
名稱轉換
dash-style到camelCase的轉換-
自定義資料屬性名透過以下方式轉換為
DOMStringMap條目的鍵：- 將所有 ASCII 大寫字母 (
A到Z) 轉換為小寫； - 移除字首
data-(包括連字元)； - 對於任何後跟 ASCII 小寫字母
a到z的連字元 (-)，移除連字元並將字母大寫； - 其他字元 (包括其他連字元) 保持不變。
- 將所有 ASCII 大寫字母 (
camelCase到dash-style的轉換-
相反的轉換，它將一個鍵對映到一個屬性名，使用以下方法：
- 限制： 在轉換之前，連字元 *不得* 緊跟 ASCII 小寫字母
a到z； - 新增
data-字首； - 在任何 ASCII 大寫字母
A到Z前新增連字元，然後將字母小寫； - 其他字元保持不變。
- 限制： 在轉換之前，連字元 *不得* 緊跟 ASCII 小寫字母
例如，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。
示例
<div id="user" data-id="1234567890" data-user="carinaanand" data-date-of-birth>
Carina Anand
</div>
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 |
瀏覽器相容性
載入中…
另見
- HTML
data-*類全域性屬性 - 使用資料屬性
Element.getAttribute()和Element.setAttribute()