HTML5 data-* 自定義屬性與 dataset API 詳解

HTML5 引入 data-* 全局屬性，允許在標準標籤上攜帶私有數據，配合 JavaScript dataset 屬性可方便讀寫。本文詳細介紹用法與注意事項。

基本語法

<div id="user" data-id="1001" data-role="admin" data-last-login="2024-01-15">用戶卡片</div>

• 屬性名必須以 data- 開頭
• 僅包含字母、數字、連字符（-）、冒號（:）、下劃線（_）
• 大寫字母會被轉為小寫（data-userName → dataset.userName）

JavaScript 讀寫

const el = document.getElementById('user');

// 讀取：自動轉駝峰
console.log(el.dataset.id);        // "1001" (字符串)
console.log(el.dataset.role);      // "admin"
console.log(el.dataset.lastLogin); // "2024-01-15"

// 寫入
el.dataset.newProp = 'value';      // 生成 data-new-prop="value"
el.dataset.userName = '張三';       // 生成 data-user-name="張三"

// 刪除
delete el.dataset.role;            // 移除 data-role 屬性

CSS 選擇器配合

[data-role="admin"] { border: 2px solid gold; }
[data-active] { opacity: 1; }

常見應用場景

1. 前端模板渲染：後端輸出 data-json='{...}'，前端 JSON.parse(el.dataset.json)
2. 事件委托攜帶參數：<button data-action="delete" data-id="123">
3. 第三方庫配置：如 data-toggle="tooltip" (Bootstrap)
4. 埋點/分析：data-track="click:button:submit"

注意事項

• 只能存字符串：對象/數組需 JSON.stringify
• 性能：頻繁讀寫 dataset 會觸發屬性重解析，高頻場景建議用 getAttribute/setAttribute 或單獨 JS 變量
• 命名規範：推薦 kebab-case（data-user-id），JS 中自動轉駝峰（dataset.userId）

參考資源

張鑫旭 - HTML5 自定義屬性 dataset 簡介

善用 data-* + dataset，能讓 HTML 與 JavaScript 交互更語義化、結構化。