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
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
|
---
title: Contacts API
slug: WebAPI/Contacts
translation_of: Archive/B2G_OS/API/Contacts_API
---
<p>{{ SeeCompatTable }}</p>
<p>{{ B2GOnlyHeader2('privileged') }}</p>
<h2 id="摘要">摘要</h2>
<p>Contacts API 提供簡易的管理介面，可用於系統通訊錄所儲存的聯絡人資訊。Contacts API 的常見使用範例，就是針對通訊錄而建構出管理 Apps。</p>
<div class="note">
<p><strong>注意：</strong>由於聯絡人資訊屬於高敏感性的個人資料，因此僅限 Privileged 與 Certified Apps 可直接存取該 API。其他 Apps 均建議透過 <a href="https://developer.mozilla.org/en-US/docs/WebAPI/Web_Activities" title="/en-US/docs/WebAPI/Web_Activities">Web Activities</a> 而委派相關作業。</p>
</div>
<h2 id="管理聯絡人資訊">管理聯絡人資訊</h2>
<p>透過 <a href="https://developer.mozilla.org/en-US/docs/Web/API/ContactManager" title="/en-US/docs/Web/API/ContactManager">ContactManager</a> 介面的 <a href="https://developer.mozilla.org/en-US/docs/Web/API/window.navigator.mozContacts" title="/en-US/docs/Web/API/window.navigator.mozContacts">navigator.mozContacts</a> 屬性，即可存取儲存於系統通訊錄中的資訊。</p>
<h3 id="新增聯絡人">新增聯絡人</h3>
<p>若要在系統通訊錄中建立新的項目，可分為 2 個步驟：</p>
<ol>
<li>建立新的 <a href="https://developer.mozilla.org/en-US/docs/Web/API/mozContact" title="The MozContact interface is used to describe a single contact in the device's contact database.">mozContact</a> 物件，並列出其必要屬性的欄位。<a href="https://developer.mozilla.org/en-US/docs/Web/API/mozContact" title="The MozContact interface is used to describe a single contact in the device's contact database.">mozContact</a> 介面將定義既有聯絡人的所有可能屬性。這些屬性絕大部分均與 vCard 4.0 規格所定義的相同。以下列出例外：
<ul>
<li>vCard N 分為 5 項屬性：<a href="https://developer.mozilla.org/en-US/docs/Web/API/ContactProperties.familyName" title="/en-US/docs/Web/API/ContactProperties.familyName"><code>familyName</code></a>、<a href="https://developer.mozilla.org/en-US/docs/Web/API/ContactProperties.givenName" title="/en-US/docs/Web/API/ContactProperties.givenName"><code>givenName</code></a>、<a href="https://developer.mozilla.org/en-US/docs/Web/API/ContactProperties.additionalName" title="/en-US/docs/Web/API/ContactProperties.additionalName"><code>additionalName</code></a>、<a href="https://developer.mozilla.org/en-US/docs/Web/API/ContactProperties.honorificPrefix" title="/en-US/docs/Web/API/ContactProperties.honorificPrefix"><code>honorificPrefix</code></a>、<a href="https://developer.mozilla.org/en-US/docs/Web/API/ContactProperties.honorificSuffix" title="/en-US/docs/Web/API/ContactProperties.honorificSuffix"><code>honorificSuffix</code></a></li>
<li>vCard FN 屬性已重新命名為 <a href="https://developer.mozilla.org/en-US/docs/Web/API/ContactProperties.name" title="/en-US/docs/Web/API/ContactProperties.name"><code>name</code></a></li>
<li>vCard GENDER 分為 2 項屬性：<a href="https://developer.mozilla.org/en-US/docs/Web/API/ContactProperties.sex" title="/en-US/docs/Web/API/ContactProperties.sex"><code>sex</code></a>、<a href="https://developer.mozilla.org/en-US/docs/Web/API/ContactProperties.genderIdentity" title="/en-US/docs/Web/API/ContactProperties.genderIdentity"><code>genderIdentity</code></a></li>
</ul>
</li>
<li>以 <a href="https://developer.mozilla.org/en-US/docs/Web/API/ContactManager.save" title="/en-US/docs/Web/API/ContactManager.save">ContactManager.save()</a> 函式搭配聯絡人物件，並作為第一屬性。此函式將回傳 <a href="https://developer.mozilla.org/en-US/docs/Web/API/DOMRequest" title="/en-US/docs/Web/API/DOMRequest">DOMRequest</a> 以追蹤儲存作業是否成功或發生錯誤。</li>
</ol>
<pre class="brush: js">var person = new mozContact();
person.givenName = ["John"];
person.familyName = ["Doe"];
person.nickName = ["No kidding"];
var saving = navigator.mozContacts.save(person);
saving.onsuccess = function() {
console.log('new contact saved');
// This update the person as it is stored
// It includes its internal unique ID
// Note that saving.result is null here
};
saving.onerror = function(err) {
console.error(err);
};
</pre>
<h3 id="尋找聯絡人">尋找聯絡人</h3>
<p>有 2 個函式可檢索系統通訊錄中的聯絡人：</p>
<ul>
<li><a href="https://developer.mozilla.org/en-US/docs/Web/API/ContactManager.find" title="/en-US/docs/Web/API/ContactManager.find">ContactManager.find()</a> 可檢索特定的聯絡人清單。</li>
<li><a href="https://developer.mozilla.org/en-US/docs/Web/API/ContactManager.getAll" title="/en-US/docs/Web/API/ContactManager.getAll">ContactManager.getAll()</a> 可檢索全部聯絡人。</li>
</ul>
<p>這 2 組函式都是讓參數 (本身即為物件) 能定義出篩選與排序的選項。<a href="https://developer.mozilla.org/en-US/docs/Web/API/ContactManager.getAll" title="The getAll method is used to access a sorted list of contact from the device's contact database. This method is best suited to access a large data set, where find() is better suited for a small data set.">ContactManager.getAll</a> 僅接受排序選項。這些選項為：</p>
<ul>
<li><code>sortBy</code><code>：</code>此字串將為排序過的搜尋結果。目前僅支援 givenName 與 familyName。</li>
<li><code>sortOrder</code>:：此字串將顯示結果的排序。可能為 <code>descending</code> (降冪) 或 <code>ascending</code> (升冪)。</li>
</ul>
<p>還有其他搜尋選項：</p>
<ul>
<li><code>filterBy</code><code>：</code>此字串陣列代表所要篩選的全部欄位。</li>
<li><code>filterValue</code><code>：</code>符合的數值。</li>
<li><code>filterOp</code><code>：</code>所要使用的篩選器比較運算子，可能為 <code>equals</code>、<code>startsWith</code>、<code>match</code>。則最後的 <code>match</code> 則特別用於電話號碼。</li>
<li><code>filterLimit</code><code>：</code><a href="https://developer.mozilla.org/en-US/docs/Web/API/ContactManager.find" title="/en-US/docs/Web/API/ContactManager.find"><code>find</code></a> <code>函式所將檢索的聯絡人數量。</code></li>
</ul>
<p><a href="https://developer.mozilla.org/en-US/docs/Web/API/ContactManager.find" title="The find method is used to retrieve a limited list of contacts from the device's contact database. This method is best suited to access a small data set, where getAll() is better suited for a large data set.">find</a> 將回傳 <a href="https://developer.mozilla.org/en-US/docs/Web/API/DOMRequest" title="A DOMRequest object represents an ongoing operation. It provides callbacks that are called when the operation completes, as well as a reference to the operation's result. A DOM method that initiates an ongoing operation may return a DOMRequest object that">DOMRequest</a> 物件；<a href="https://developer.mozilla.org/en-US/docs/Web/API/ContactManager.getAll" title="The getAll method is used to access a sorted list of contact from the device's contact database. This method is best suited to access a large data set, where find() is better suited for a small data set.">getAll</a> 將回傳 <a href="https://developer.mozilla.org/en-US/docs/Web/API/DOMCursor" title="A DOMCursor object represents an ongoing operation over a list of results. It is an enhanced DOMRequest that allows to iterate through a list of results asynchronously. Each time its continue() method is called, the DOMCursor tries to reach the next resul">DOMCursor</a> 物件，以存取成功或錯誤的搜尋作業。</p>
<p>若搜尋成功，則可於 <a href="https://developer.mozilla.org/en-US/docs/Web/API/DOMRequest.result" title="/en-US/docs/Web/API/DOMRequest.result">DOMRequest.result</a> 屬性中找到搜尋結果。可能是 <a href="https://developer.mozilla.org/en-US/docs/Web/API/ContactManager.find" title="The find method is used to retrieve a limited list of contacts from the device's contact database. This method is best suited to access a small data set, where getAll() is better suited for a large data set.">find</a> 的 <a href="https://developer.mozilla.org/en-US/docs/Web/API/mozContact" title="The MozContact interface is used to describe a single contact in the device's contact database.">mozContact</a> 物件陣列；也可能是 <a href="https://developer.mozilla.org/en-US/docs/Web/API/ContactManager.getAll" title="The getAll method is used to access a sorted list of contact from the device's contact database. This method is best suited to access a large data set, where find() is better suited for a small data set.">getAll</a> 的單一 <a href="https://developer.mozilla.org/en-US/docs/Web/API/mozContact" title="The MozContact interface is used to describe a single contact in the device's contact database.">mozContact</a> 物件。若要以 <a href="https://developer.mozilla.org/en-US/docs/Web/API/ContactManager.getAll" title="The getAll method is used to access a sorted list of contact from the device's contact database. This method is best suited to access a large data set, where find() is better suited for a small data set.">getAll</a> 接收清單中的其他結果，則可呼叫指示器的 <code>continue()</code> 函式。</p>
<pre class="brush: js">var options = {
filterValue : "John",
filterBy : ["givenName","name","nickName"],
filterOp : "contains",
filterLimit : 1,
sortBy : "familyName"
sortOrder : "ascending"
}
var search = navigator.mozContacts.find(options);
search.onsuccess = function() {
if (search.result.length === 1) {
var person = search.result[0];
console.log("Found:" + person.givenName[0] + " " + person.familyName[0]);
} else {
console.log("Sorry, there is no such contact.")
}
}
search.onerror = function() {
console.warn("Uh! Something goes wrong, no result found!");
}
var allContacts = navigator.mozContacts.getAll({sortBy: "familyName", sortOrder: "descending"});
allContacts.onsuccess = function(event) {
var cursor = event.target;
if (cursor.result) {
console.log("Found: " + cursor.result.givenName[0] + " " + cursor.result.familyName[0]);
cursor.continue();
} else {
console.log("No more contacts");
}
}
allContacts.onerror = function() {
console.warn("Something went terribly wrong! :(");
}
</pre>
<h3 id="更新聯絡人">更新聯絡人</h3>
<p>在透過 <a href="https://developer.mozilla.org/en-US/docs/Web/API/ContactManager.find" title="/en-US/docs/Web/API/ContactManager.find"><code>find()</code></a> 或 <a href="https://developer.mozilla.org/en-US/docs/Web/API/ContactManager.getAll" title="/en-US/docs/Web/API/ContactManager.getAll"><code>getAll()</code></a> 檢索聯絡人時，又或針對新聯絡人而成功呼叫 <a href="https://developer.mozilla.org/en-US/docs/Web/API/ContactManager.save" title="/en-US/docs/Web/API/ContactManager.save"><code>save()</code></a> 時，此聯絡人必須附加某些後設資料 (Meta-data)：</p>
<ul>
<li>透過 <a href="https://developer.mozilla.org/en-US/docs/Web/API/mozContact.id" title="The id property is a unique string representing the contact within the device's contact database.">mozContact.id</a> 取得專屬 ID</li>
<li><a href="https://developer.mozilla.org/en-US/docs/Web/API/mozContact.updated" title="The updated property provides the date of when the contact was updated for the last time on the device's contact database.">mozContact.updated</a> 中的 <a href="https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Date" title="/en-US/docs/JavaScript/Reference/Global_Objects/Date">Date</a> 物件，將代表聯絡人最後的更新時間</li>
</ul>
<p>若更新某位聯絡人，其實只是更改其屬性值，再呼叫 <a href="https://developer.mozilla.org/en-US/docs/Web/API/ContactManager.save" title="/en-US/docs/Web/API/ContactManager.save">save()</a> 函式即可儲存。</p>
<div class="note">
<p><strong>注意：</strong>每次只要新增、更新、刪除聯絡人，就會觸發 <a href="https://developer.mozilla.org/en-US/docs/Web/Reference/Events/contactchange" title="/en-US/docs/Web/Reference/Events/contactchange">contactchange</a> 事件，以追蹤系統通訊錄的所有變更。另可透過 <a href="https://developer.mozilla.org/en-US/docs/Web/API/ContactManager.oncontactchange" title="/en-US/docs/Web/API/ContactManager.oncontactchange">ContactManager.oncontactchange</a> 屬性而處理該事件。</p>
</div>
<h3 id="刪除聯絡人">刪除聯絡人</h3>
<p>呼叫 <a href="https://developer.mozilla.org/en-US/docs/Web/API/ContactManager.remove" title="/en-US/docs/Web/API/ContactManager.remove"><code>ContactManager.remove()</code></a> 函式，只會刪除已傳入的 <a href="https://developer.mozilla.org/en-US/docs/Web/API/mozContact" title="The MozContact interface is used to describe a single contact in the device's contact database.">mozContact</a> 物件。</p>
<p>在某些極端情況下，也可透過 <a href="https://developer.mozilla.org/en-US/docs/Web/API/ContactManager.clear" title="/en-US/docs/Web/API/ContactManager.clear"><code>ContactManager.clear()</code></a> 而刪除所有的聯絡人。因為一旦完成就沒辦法恢復資料，所以呼叫此函式時請特別謹慎。</p>
<h2 id="Specifications" name="Specifications">規格</h2>
<table class="standard-table">
<thead>
<tr>
<th scope="col">Specification</th>
<th scope="col">Status</th>
<th scope="col">Comment</th>
</tr>
</thead>
<tbody>
<tr>
<td>{{ SpecName('Contacts', '', 'Contacts Manager API') }}</td>
<td>{{ Spec2('Contacts') }}</td>
<td>First Working Draft (未穩定)</td>
</tr>
<tr>
<td><a href="http://tools.ietf.org/html/rfc6350" title="http://tools.ietf.org/html/rfc6350">vCard Format Specification</a></td>
<td>RFC</td>
<td><code>RFC6350</code></td>
</tr>
</tbody>
</table>
<h2 id="瀏覽器相容性">瀏覽器相容性</h2>
<p>{{ CompatibilityTable() }}</p>
<div id="compat-desktop">
<table class="compat-table">
<tbody>
<tr>
<th>Feature</th>
<th>Chrome</th>
<th>Firefox (Gecko)</th>
<th>Internet Explorer</th>
<th>Opera</th>
<th>Safari</th>
</tr>
<tr>
<td>基本支援</td>
<td>{{CompatNo()}}</td>
<td>{{CompatNo()}}</td>
<td>{{CompatNo()}}</td>
<td>{{CompatNo()}}</td>
<td>{{CompatNo()}}</td>
</tr>
</tbody>
</table>
</div>
<div id="compat-mobile">
<table class="compat-table">
<tbody>
<tr>
<th>Feature</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>{{CompatNo()}}</td>
<td>{{CompatNo()}}</td>
<td>{{CompatVersionUnknown()}}</td>
<td>{{CompatNo()}}</td>
<td>{{CompatNo()}}</td>
<td>{{CompatNo()}}</td>
</tr>
</tbody>
</table>
</div>
<h3 id="Gecko_說明">Gecko 說明</h3>
<p>此規格尚未確定，因此目前 Gecko 仍屬非標準建構。</p>
<h2 id="另可參閱">另可參閱</h2>
<ul>
<li><a href="https://developer.mozilla.org/en-US/docs/Web/API/window.navigator.mozContacts" title="Return a ContactManager to access and manage all the contacts available on the device.">navigator.mozContacts</a></li>
<li><a href="https://developer.mozilla.org/en-US/docs/Web/API/mozContact" title="The MozContact interface is used to describe a single contact in the device's contact database.">mozContact</a></li>
<li><a href="https://developer.mozilla.org/en-US/docs/Web/API/ContactManager" title="The ContactManager interface is used to access and manage the contact available on the device.">ContactManager</a></li>
<li><a href="https://developer.mozilla.org/en-US/docs/Web/API/MozContactChangeEvent" title="The MozContactChangeEvent interface provides information about the contact that has changed. It inherits from the Event interface.">MozContactChangeEvent</a></li>
</ul>
|
