aboutsummaryrefslogtreecommitdiff
path: root/files/zh-tw/web/api/htmlelement/dataset/index.html
blob: 690f8e118953dbca21776c4490fec79a8853c69f (plain)
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
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
---
title: HTMLElement.dataset
slug: Web/API/HTMLElement/dataset
translation_of: Web/API/HTMLOrForeignElement/dataset
---
<p>{{ APIRef("HTML DOM") }}</p>

<p><code><strong>HTMLElement.dataset</strong></code> 允許在讀取與寫入模式時使用HTML或DOM裡,所有設置在元件上的<a href="/en/HTML/Global_attributes#attr-data-*" title="https://developer.mozilla.org/en/HTML/Global_attributes#attr-data-*">自定義資料屬性</a>(<em>data-*</em>)。他是一個<a href="/en/DOM/DOMStringMap" title="en/DOM/DOMStringMap">DOMStringMap</a>,每個項目表示一個不同的資料屬性。須注意的是,資料集(dataset)可以被讀取,但不能直接被修改。所有修改必須經由其眾多"屬性"才行,也就是資料屬性。另外,雖然HTML <code><strong>data-</strong></code> 屬性與它相關的 DOM <code><strong>dataset.</strong></code> 名稱不同,但是他們總是有相似之處: </p>

<ul>
 <li>HTML裡的自定義資料屬性名稱開頭為<code>data-</code> 。後面則只接受字母、數字還有以下的符號: dash (<code>-</code>), 點 (<code>.</code>), 冒號 (<code>:</code>), 底線(<code>_</code>) -- 但不包含任何ASCII 大寫字母(A 到 Z)。</li>
 <li>Javascript 裡的自定義資料屬性和HTML裡的一樣,只是命名規則採camelCase,且不含dash,點等上述所提的符號。</li>
</ul>

<p>除了以下的資訊之外,你也可以在 <a href="/en-US/docs/Learn/HTML/Howto/Use_data_attributes">Using data attributes.</a>此篇文章找到使用HTML資料屬性的用法。</p>

<h3 id="名稱變換">名稱變換</h3>

<p> </p>

<p>dash-style 到 camelCase: 將自訂義的資料屬性名稱變換至{{ domxref("DOMStringMap") }}各項目的key值,需根據以下規則:</p>

<ul>
 <li>移除前綴<code>data-</code>(包含dash)。</li>
 <li>任何後面接ASCII小寫a到z的dash(<code>U+002D</code>)都要被移除,接在後面的字母被換成相對應的大寫字母。</li>
 <li>其他字元(包含其他dashes)都保持不變。</li>
</ul>

<p>camelCase 到 dash-style: 與上述相反,將key值轉為資料屬性名稱,需根據以下規則:</p>

<ul>
 <li>限制: dash 不能馬上接任何ASCII小寫字母a到z(在轉換之前)。</li>
 <li>加上前綴字 <code>data-</code> 。</li>
 <li>任何ASCII大寫字母A到Z變成dash加上其相對應的小寫字母。</li>
 <li>其他字元都保持不變。</li>
</ul>

<p>上面所提的限制是為了確保兩個轉換方法互為相反。</p>

<p>舉例來說,資料屬性名稱 <code>data-abc-def</code> 之對應key值為<code>abcDef</code></p>

<p> </p>

<h3 id="存取數值">存取數值</h3>

<ul>
 <li>資料屬性可以藉由camelCase名稱(key)像dataset物件屬性的方式設定或讀取,如element.dataset.keyname。</li>
 <li>資料屬性也可以經由物件屬性[]語法的方式設定或讀取,如 <em>element.</em>dataset[<em>keyname</em>]。</li>
</ul>

<h2 id="語法">語法</h2>

<ul>
 <li><em>string</em> = <em>element</em>.<strong>dataset</strong>.<em>camelCasedName</em>;</li>
 <li><em>element.</em><strong>dataset</strong>.<em>camelCasedName</em> = <em>string</em>;</li>
 <br>
 <li><em>string</em> = <em>element</em>.<strong>dataset</strong>[<em>camelCasedName</em>];</li>
 <li><em>element</em>.<strong>dataset</strong>[<em>camelCasedName</em>] = <em>string</em>;</li>
 <br>
 <li><em>自定的data屬性也可以直接從HTML設定,但是屬性名稱必須使用上述中的data- 語法。 </em></li>
</ul>

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

<pre class="brush: js">&lt;div id="user" data-id="1234567890" data-user="johndoe" data-date-of-birth&gt;John Doe&lt;/div&gt;

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
</pre>

<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#dom-dataset", "HTMLElement.dataset")}}</td>
   <td>{{Spec2('HTML WHATWG')}}</td>
   <td>No change from latest snapshot, {{SpecName('HTML5.1')}}</td>
  </tr>
  <tr>
   <td>{{SpecName('HTML5.1', "dom.html#dom-dataset", "HTMLElement.dataset")}}</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#dom-dataset", "HTMLElement.dataset")}}</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>Edge</th>
   <th>Firefox (Gecko)</th>
   <th>Internet Explorer</th>
   <th>Opera</th>
   <th>Safari</th>
  </tr>
  <tr>
   <td>基本支援</td>
   <td>8</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{ CompatGeckoDesktop("6.0") }}</td>
   <td>11</td>
   <td>11.10</td>
   <td>6</td>
  </tr>
 </tbody>
</table>
</div>

<div id="compat-mobile">
<table class="compat-table">
 <tbody>
  <tr>
   <th>功能</th>
   <th>Android</th>
   <th>Edge</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>{{CompatVersionUnknown}}</td>
   <td>{{CompatGeckoMobile(6)}}</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatVersionUnknown}}</td>
  </tr>
 </tbody>
</table>
</div>

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

<ul>
 <li>The HTML <a href="/en-US/docs/Web/HTML/Global_attributes/data-*"><strong>data-*</strong></a> class of global attributes.</li>
 <li><a href="/en-US/docs/Learn/HTML/Howto/Use_data_attributes">Using data attributes</a></li>
</ul>