We're looking for a user researcher to understand the needs of developers and designers. Is this you or someone you know? Check out the post: https://mzl.la/2IGzdXS

翻譯不完整。請協助 翻譯此英文文件

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各項目的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!

功能 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)

參見

文件標籤與貢獻者

此頁面的貢獻者: willynpi
最近更新: willynpi,