HTMLElement.dataset
HTMLElement.dataset
允許在讀取與寫入模式時使用HTML或DOM裡,所有設置在元件上的自定義資料屬性(data-*)。他是一個DOMStringMap,每個項目表示一個不同的資料屬性。須注意的是,資料集(dataset)可以被讀取,但不能直接被修改。所有修改必須經由其眾多"屬性"才行,也就是資料屬性。另外,雖然HTML data-
屬性與它相關的 DOM dataset.
名稱不同,但是他們總是有相似之處:
- HTML裡的自定義資料屬性名稱開頭為
data-
。後面則只接受字母、數字還有以下的符號: dash (-
), 點 (.
), 冒號 (:
), 底線(_
) -- 但不包含任何ASCII 大寫字母(A 到 Z)。 - Javascript 裡的自定義資料屬性和HTML裡的一樣,只是命名規則採camelCase,且不含dash,點等上述所提的符號。
除了以下的資訊之外,你也可以在 Using data attributes.此篇文章找到使用HTML資料屬性的用法。
名稱變換
dash-style 到 camelCase: 將自訂義的資料屬性名稱變換至DOMStringMap
(en-US)各項目的key值,需根據以下規則:
- 移除前綴
data-
(包含dash)。 - 任何後面接ASCII小寫a到z的dash(
U+002D
)都要被移除,接在後面的字母被換成相對應的大寫字母。 - 其他字元(包含其他dashes)都保持不變。
camelCase 到 dash-style: 與上述相反,將key值轉為資料屬性名稱,需根據以下規則:
- 限制: dash 不能馬上接任何ASCII小寫字母a到z(在轉換之前)。
- 加上前綴字
data-
。 - 任何ASCII大寫字母A到Z變成dash加上其相對應的小寫字母。
- 其他字元都保持不變。
上面所提的限制是為了確保兩個轉換方法互為相反。
舉例來說,資料屬性名稱 data-abc-def
之對應key值為abcDef
。
存取數值
- 資料屬性可以藉由camelCase名稱(key)像dataset物件屬性的方式設定或讀取,如element.dataset.keyname。
- 資料屬性也可以經由物件屬性[]語法的方式設定或讀取,如 element.dataset[keyname]。
語法
- string = element.dataset.camelCasedName;
- element.dataset.camelCasedName = string;
- string = element.dataset[camelCasedName];
- element.dataset[camelCasedName] = string;
- 自定的data屬性也可以直接從HTML設定,但是屬性名稱必須使用上述中的data- 語法。
範例
<div id="user" data-id="1234567890" data-user="johndoe" data-date-of-birth>John Doe</div>
let el = document.querySelector('#user');
// el.id == 'user'
// el.dataset.id === '1234567890'
// el.dataset.user === 'johndoe'
// el.dataset.dateOfBirth === ''
el.dataset.dateOfBirth = '1960-10-03'; // 設定 DOB.
// 'someDataAttr' in el.dataset === false
el.dataset.someDataAttr = 'mydata';
// 'someDataAttr' in el.dataset === true
規範
規範 | 狀態 | 備註 |
---|---|---|
HTML Living Standard The definition of 'HTMLElement.dataset' in that specification. |
Living Standard | No change from latest snapshot, HTML 5.1 |
HTML 5.1 The definition of 'HTMLElement.dataset' in that specification. |
Recommendation | Snapshot of HTML Living Standard, no change from HTML5 |
HTML5 The definition of 'HTMLElement.dataset' in that specification. |
Recommendation | Snapshot of HTML Living Standard, initial definition. |
瀏覽器相容性
We're converting our compatibility data into a machine-readable JSON format.
This compatibility table still uses the old format,
because we haven't yet converted the data it contains.
Find out how you can help! (en-US)
功能 | Chrome | Edge | Firefox (Gecko) | Internet Explorer | Opera | Safari |
---|---|---|---|---|---|---|
基本支援 | 8 | (Yes) | 6.0 (6.0) | 11 | 11.10 | 6 |
功能 | Android | Edge | Firefox Mobile (Gecko) | IE Mobile | Opera Mobile | Safari Mobile |
---|---|---|---|---|---|---|
基本支援 | (Yes) | (Yes) | 6.0 (6) | (Yes) | (Yes) | (Yes) |
參見
- The HTML data-* class of global attributes.
- Using data attributes