initial commit

1 files changed, 197 insertions, 0 deletions

diff --git a/files/zh-tw/webapi/contacts/index.html b/files/zh-tw/webapi/contacts/index.html
new file mode 100644
index 0000000000..6775c57248
--- /dev/null
+++ b/files/zh-tw/webapi/contacts/index.html
@@ -0,0 +1,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>