HTML5 引進了 data-* 自訂屬性,讓我們能把附加資料直接寫在標籤上而不必另開 API 請求。jQuery 從 1.4.3 起會自動把這些屬性收進內部資料物件,讀取方式與一般 data 完全一致。
.data( key, value ) // 設定單一值 .data( obj ) // 批次設定 .data( key ) // 讀取單一值 .data() // 取得全部資料物件
HTML:
<div data-role="page" data-last-value="43" data-hidden="true"
data-options='{"name":"John"}'></div>
以下四行程式碼全部回傳 true:
$("div").data("role") === "page";
$("div").data("lastValue") === 43;
$("div").data("hidden") === true;
$("div").data("options").name === "John";
請注意屬性名的轉換規則:HTML 上的 data-last-value 在 JavaScript 中要寫成 lastValue,連字號後的首字母會被大寫化。
與原生 dataset API 不同,jQuery 會主動嘗試把字串轉成對應的 JavaScript 值,涵蓋布林值、數字、物件、陣列與 null。判斷標準是「轉換後是否改變了值的表示」:字串 "100" 會變成數字 100,但 "1E02" 與 "100.000" 雖然數值等同 100,轉換會改變原本的寫法,因此仍保留為字串。
若屬性值以 { 開頭被視為物件、以 [ 開頭被視為陣列,jQuery 會用 parseJSON 解析,內容必須符合合法 JSON 語法,包含屬性名稱要加雙引號這點。解析失敗則原樣保留為字串。
想要純字串就用 attr()。如果你的資料剛好是 "007" 這種前導零的編號,或是版本號 "1.10",用 data() 會被轉成數字而失去格式,這種情況請改用 attr("data-xxx")。
data-* 只在首次讀取時生效。jQuery 第一次存取某個屬性後,值就會被快取進內部資料物件,之後對元素呼叫 .data(obj) 的變更不會反映回 HTML 屬性上,反之 HTML 上的改動也不會被 data() 察覺。這點在「伺服器端更新 DOM 後想用 data() 重讀」的情境特別容易踩坑。
最後,不帶參數呼叫 .data() 會回傳一個全新的 JavaScript 物件。這個物件一旦取出就與元素脫鉤,後續對元素的 data 操作不影響它;反過來說,直接操作這個物件也比每次呼叫 .data() 往返存取來得有效率,處理大量資料時值得採用。