files/zh-tw/web/html/global_attributes/data-_star_/index.html


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114

---
title: data-*
slug: Web/HTML/Global_attributes/data-*
translation_of: Web/HTML/Global_attributes/data-*
---
<p class="note">{{HTMLSidebar("Global_attributes")}}</p>

<p><strong>data-*</strong><a href="/zh-TW/docs/Web/HTML/Global_attributes">全域屬性</a>構成一組稱作<strong>自訂 data 屬性</strong>的屬性。它能令 <a href="/zh-TW/docs/Web/HTML" title="zh-TW/HTML">HTML</a> 與其 <a href="/zh-TW/docs/DOM" title="zh-TW/DOM">DOM</a> 擁有給腳本用的交換資訊。這種屬性設置的自訂資料，能透過元素的 {{domxref("HTMLElement")}} 介面而活用。{{domxref("HTMLElement.dataset")}} property 允許訪問它們。<code>*</code> 可以是任何遵循以下規則的 <a class="external" href="http://www.w3.org/TR/REC-xml/#NT-Name" title="http://www.w3.org/TR/REC-xml/#NT-Name">xml 名稱</a>：</p>

<ul>
 <li>名字絕對不能以 <code>xml</code> 起頭，無論是否用於 xml、</li>
 <li>名字絕對不能包含分號（<code>U+003A</code>）、</li>
 <li>名字絕對不能包含大寫 <code>A</code> 到大小 <code>Z</code> 的拉丁字母。</li>
</ul>

<p>請注意 {{domxref("HTMLElement.dataset")}} property 是個 {{domxref("DOMStringMap")}}，而自訂的 data 屬性名 <em>data-test-value</em> 因為所有的減號（<code>U+002D</code>）都會被消去、緊接著的第一個字母，會被取代為駝峰式（camelcase）名字，所以要透過 <code>HTMLElement.dataset.testValue</code> 或 <code>HTMLElement.dataset["<em>testValue</em>"]</code> 訪問。</p>

<h3 id="用法">用法</h3>

<p>藉由增加 <strong>data-* </strong> 屬性，即使是普通的 HTML 元素也能變成複雜而強大程式物件。例如說遊戲裡面的太空船<a href="https://zh.wikipedia.org/zh-tw/%E7%B2%BE%E7%81%B5_(%E8%AE%A1%E7%AE%97%E6%9C%BA%E5%9B%BE%E5%BD%A2%E5%AD%A6)">精靈</a> 能成為帶有 <a href="/zh-TW/docs/Web/HTML/Global_attributes/class">class</a> 與數個 data-* 屬性的 {{HTMLElement("img")}} 元素：</p>

<pre>&lt;img class="spaceship cruiserX3" src="shipX3.png"
  data-ship-id="324"   data-weapons="laserI laserII"   data-shields="72%"
  data-x="414354" data-y="85160" data-z="31940"
  onclick="spaceships[this.dataset.shipId].blasted()" /&gt;
</pre>

<p id="Specifications">（參見<em><a href="https://html.spec.whatwg.org/multipage/dom.html#embedding-custom-non-visible-data-with-the-data-*-attributes">這個網站</a></em>）</p>

<h2 id="規範">規範</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">規範</th>
   <th scope="col">狀態</th>
   <th scope="col">註解</th>
  </tr>
  <tr>
   <td>{{SpecName('HTML WHATWG', "dom.html#embedding-custom-non-visible-data-with-the-data-*-attributes", "data-*")}}</td>
   <td>{{Spec2('HTML WHATWG')}}</td>
   <td>No change from latest snapshot, {{SpecName('HTML5.1')}}</td>
  </tr>
  <tr>
   <td>{{SpecName('HTML5.1', "dom.html#embedding-custom-non-visible-data-with-the-data-*-attributes", "data-*")}}</td>
   <td>{{Spec2('HTML5.1')}}</td>
   <td>Snapshot of {{SpecName('HTML WHATWG')}}, no change from {{SpecName('HTML5 W3C')}}</td>
  </tr>
  <tr>
   <td>{{SpecName('HTML5 W3C', "dom.html#embedding-custom-non-visible-data-with-the-data-*-attributes", "data-*")}}</td>
   <td>{{Spec2('HTML5 W3C')}}</td>
   <td>Snapshot of  {{SpecName('HTML WHATWG')}}, initial definition.</td>
  </tr>
 </tbody>
</table>

<h2 id="瀏覽器相容性">瀏覽器相容性</h2>

<p>{{ CompatibilityTable() }}</p>

<div id="compat-desktop">
<table class="compat-table">
 <tbody>
  <tr>
   <th>功能</th>
   <th>Chrome</th>
   <th>Firefox (Gecko)</th>
   <th>Internet Explorer</th>
   <th>Opera</th>
   <th>Safari</th>
  </tr>
  <tr>
   <td>基本支援</td>
   <td>{{ CompatVersionUnknown() }}</td>
   <td>{{ CompatGeckoDesktop(6) }}</td>
   <td>{{ CompatVersionUnknown() }}</td>
   <td>{{ CompatVersionUnknown() }}</td>
   <td>{{ CompatVersionUnknown() }}</td>
  </tr>
 </tbody>
</table>
</div>

<div id="compat-mobile">
<table class="compat-table">
 <tbody>
  <tr>
   <th>功能</th>
   <th>Android</th>
   <th>Chrome for Android</th>
   <th>Firefox Mobile (Gecko)</th>
   <th>IE Mobile</th>
   <th>Opera Mobile</th>
   <th>Safari Mobile</th>
  </tr>
  <tr>
   <td>基本支援</td>
   <td>{{ CompatVersionUnknown() }}</td>
   <td>{{ CompatGeckoMobile(6) }}</td>
   <td>{{ CompatVersionUnknown() }}</td>
   <td>{{ CompatVersionUnknown() }}</td>
   <td>{{ CompatVersionUnknown() }}</td>
   <td>{{ CompatVersionUnknown() }}</td>
  </tr>
 </tbody>
</table>
</div>

<h2 id="參見">參見</h2>

<ul>
 <li>所有的<a href="/zh-TW/docs/Web/HTML/Global_attributes">全域屬性</a></li>
 <li>The {{domxref("HTMLElement.dataset")}} property that allows to access and modify these values.</li>
</ul>