【Html】自定義屬性：data-* 的命名規則和取值方法

本篇重點

• 屬性必須以 data- 為前綴
• 建議使用 kebab-case 命名
• data-* 的常見應用時機
• JavaScript 使用 dataset. 取值
• jQuery 使用 .data() 或是 .attr() 取值

HTML5 引入了 data-* 屬性，讓開發者可以在標籤上自訂屬性，儲存額外的資訊，並能夠被 JavaScript 獲取與操作。

命名規則

1

<div id="example" data-user-id="12345" data-role="admin" data-info='{"name": "Alice", "age": 25}'></div>

1. 必須以 data- 為前綴

   • data- 是固定的屬性前綴，用於告訴瀏覽器這是一個自定義數據屬性。

2. 後續名稱只能包含

   • 小寫字母（a-z）
   • 數字（0-9）
   • 中橫線（-）

   建議使用「kebab-case（短橫線命名法）」，例如 data-user-id，避免使用 data_user_id 或 dataUserId，這可能會影響取值的操作

3. data-* 屬性值可以是

   • 字串
   • 數字
   • JSON 格式

常見應用時機

1. 前端與後端溝通的小型數據

1

<li data-product-id="101" data-price="25.99">商品名稱</li>

2. 控制前端行為

1

<button data-toggle="modal">開啟模態窗</button>

3. 統計與分析

1

<a href="example.html" data-track="nav-link">點擊我</a>

讀取 data-* 屬性的方法

Javascript

使用 dataset 物件讀取 data-* 屬性：

• dataset 會將 data-* 的 kebab-case 轉換為 camelCase（駝峰式命名法），例如 data-user-id 使用 dataset.userId 讀取
• 如果屬性名稱包含大寫（不建議這樣做），JavaScript 仍然會轉為小寫處理。例如 data-User-Name 使用 dataset.userName 讀取

1
2
3
4
5
6
7
8

<div id="example" 
    data-user-id="12345" 
    data-User-Name="Alice" 
    data-role="admin" 
    data-info='{"name": "Alice", "age": 25}'>
</div>

<p id="output"></p>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

const div = document.getElementById("example");
const output = document.getElementById("output");

// 取得 data-* 屬性值
const userId = div.dataset.userId;
const userName = div.dataset.userName;
const role = div.dataset.role;
const info = JSON.parse(div.dataset.info); // 解析 JSON 字串

output.innerHTML = `
    使用者 ID: ${userId} <br>
    使用者名稱: ${userName} <br>
    角色: ${role} <br>
    額外資訊: 名字 - ${info.name}, 年齡 - ${info.age}
`;

JQuery

可以使用 .data() 或是 attr() 存取 data-* 屬性：

• 使用 .data() 讀取 data-*，無論屬性名稱使用 kebab-case 或 camelCase，都能正確獲取對應的值
• 如果 data-* 的值是有效的 JSON，且在 HTML 載入時已經存在，.data() 會自動將其解析為 JavaScript 物件

1
2
3
4
5
6
7
8
9

<div
  id="example"
  data-user-id="12345"
  data-User-Name="Alice"
  data-role="admin"
  data-info='{"name": "Alice", "age": 25}'
></div>

<p id="output"></p>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

const div = $("#example");
const output = $("#output");

// 取得 data-* 屬性值
const userId = div.data('user-id'); // kebab-case 也可讀取
const userId2 = div.data('userId');
const userName = div.data('userName');
const role = div.attr('data-role');
const info = div.data('info');

$("#output").html(`
    使用者 ID: ${userId} <br>
    使用者 ID 2: ${userId2} <br>
    使用者名稱: ${userName} <br>
    角色: ${role} <br>
    額外資訊: 名字 - ${info.name}, 年齡 - ${info.age}
`);

結論

HTML 的 data-* 屬性是一種靈活且易用的方式，用於存儲自定義數據，方便前端操作，但有幾個需要注意的地方：

• 避免存放敏感信息
  data-* 屬性數據是公開的，任何人都可以通過檢視原始碼或瀏覽器開發工具查看，避免存放密碼、API 金鑰等敏感資訊。

• 適度使用
  data-* 屬性適合存放小型且靜態的數據。如果數據過於龐大或動態，建議改用其他方式，例如 API 或 JavaScript 物件。

了解後能夠大幅提升程式碼的可讀性與維護性！

延伸閱讀

• 【MDN】data-* 介紹
• 【MDN】dataset 介紹
• 【jQuery 官方文件】.data() 介紹
• 【Camel ‘s blog】常見的命名規則