From 218934fa2ed1c702a6d3923d2aa2cc6b43c48684 Mon Sep 17 00:00:00 2001 From: Peter Bengtsson Date: Tue, 8 Dec 2020 14:43:23 -0500 Subject: initial commit --- files/zh-tw/webapi/contacts/index.html | 197 +++++++++++++++++++++++++++++++++ 1 file changed, 197 insertions(+) create mode 100644 files/zh-tw/webapi/contacts/index.html (limited to 'files/zh-tw/webapi/contacts') 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 +--- +

{{ SeeCompatTable }}

+

{{ B2GOnlyHeader2('privileged') }}

+

摘要

+

Contacts API 提供簡易的管理介面，可用於系統通訊錄所儲存的聯絡人資訊。Contacts API 的常見使用範例，就是針對通訊錄而建構出管理 Apps。

+
+

注意：由於聯絡人資訊屬於高敏感性的個人資料，因此僅限 Privileged 與 Certified Apps 可直接存取該 API。其他 Apps 均建議透過 Web Activities 而委派相關作業。

+
+

管理聯絡人資訊

+

透過 ContactManager 介面的 navigator.mozContacts 屬性，即可存取儲存於系統通訊錄中的資訊。

+

新增聯絡人

+

若要在系統通訊錄中建立新的項目，可分為 2 個步驟：

+
    +
  1. 建立新的 mozContact 物件，並列出其必要屬性的欄位。mozContact 介面將定義既有聯絡人的所有可能屬性。這些屬性絕大部分均與 vCard 4.0 規格所定義的相同。以下列出例外： + +
    2. +
  2. 以 ContactManager.save() 函式搭配聯絡人物件，並作為第一屬性。此函式將回傳 DOMRequest 以追蹤儲存作業是否成功或發生錯誤。
    3. +
+
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);
+};
+
+

尋找聯絡人

+

有 2 個函式可檢索系統通訊錄中的聯絡人：

+ +

這 2 組函式都是讓參數 (本身即為物件) 能定義出篩選與排序的選項。ContactManager.getAll 僅接受排序選項。這些選項為：

+ +

還有其他搜尋選項：

+ +

find 將回傳 DOMRequest 物件；getAll 將回傳 DOMCursor 物件，以存取成功或錯誤的搜尋作業。

+

若搜尋成功，則可於 DOMRequest.result 屬性中找到搜尋結果。可能是 find 的 mozContact 物件陣列；也可能是 getAll 的單一 mozContact 物件。若要以 getAll 接收清單中的其他結果，則可呼叫指示器的 continue() 函式。

+
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! :(");
+}
+
+
+

更新聯絡人

+

在透過 find() 或 getAll() 檢索聯絡人時，又或針對新聯絡人而成功呼叫 save() 時，此聯絡人必須附加某些後設資料 (Meta-data)：

+ +

若更新某位聯絡人，其實只是更改其屬性值，再呼叫 save() 函式即可儲存。

+
+

注意：每次只要新增、更新、刪除聯絡人，就會觸發 contactchange 事件，以追蹤系統通訊錄的所有變更。另可透過 ContactManager.oncontactchange 屬性而處理該事件。

+
+

刪除聯絡人

+

呼叫 ContactManager.remove() 函式，只會刪除已傳入的 mozContact 物件。

+

在某些極端情況下，也可透過 ContactManager.clear() 而刪除所有的聯絡人。因為一旦完成就沒辦法恢復資料，所以呼叫此函式時請特別謹慎。

+

規格

+ + + + + + + + + + + + + + + + + + + + +
SpecificationStatusComment
{{ SpecName('Contacts', '', 'Contacts Manager API') }}{{ Spec2('Contacts') }}First Working Draft (未穩定)
vCard Format SpecificationRFCRFC6350
+

瀏覽器相容性

+

{{ CompatibilityTable() }}

+
+ + + + + + + + + + + + + + + + + + + +
FeatureChromeFirefox (Gecko)Internet ExplorerOperaSafari
基本支援{{CompatNo()}}{{CompatNo()}}{{CompatNo()}}{{CompatNo()}}{{CompatNo()}}
+
+
+ + + + + + + + + + + + + + + + + + + + + +
FeatureAndroidChrome for AndroidFirefox Mobile (Gecko)IE MobileOpera MobileSafari Mobile
基本支援{{CompatNo()}}{{CompatNo()}}{{CompatVersionUnknown()}}{{CompatNo()}}{{CompatNo()}}{{CompatNo()}}
+
+

Gecko 說明

+

此規格尚未確定，因此目前 Gecko 仍屬非標準建構。

+

另可參閱

+ -- cgit v1.2.3-54-g00ecf