Contacts API

摘要

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

管理聯絡人資訊

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

新增聯絡人

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

1. 建立新的 mozContact 物件，並列出其必要屬性的欄位。mozContact 介面將定義既有聯絡人的所有可能屬性。這些屬性絕大部分均與 vCard 4.0 規格所定義的相同。以下列出例外：
   • vCard N 分為 5 項屬性：familyName、givenName、additionalName、honorificPrefix、honorificSuffix
   • vCard FN 屬性已重新命名為 name
   • vCard GENDER 分為 2 項屬性：sex、genderIdentity
2. 以 ContactManager.save() 函式搭配聯絡人物件，並作為第一屬性。此函式將回傳 DOMRequest 以追蹤儲存作業是否成功或發生錯誤。

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 個函式可檢索系統通訊錄中的聯絡人：

• ContactManager.find() 可檢索特定的聯絡人清單。
• ContactManager.getAll() 可檢索全部聯絡人。

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

• sortBy：此字串將為排序過的搜尋結果。目前僅支援 givenName 與 familyName。
• sortOrder:：此字串將顯示結果的排序。可能為 descending (降冪) 或 ascending (升冪)。

還有其他搜尋選項：

• filterBy：此字串陣列代表所要篩選的全部欄位。
• filterValue：符合的數值。
• filterOp：所要使用的篩選器比較運算子，可能為 equals、startsWith、match。則最後的 match 則特別用於電話號碼。
• filterLimit：find 函式所將檢索的聯絡人數量。

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)：

• 透過 mozContact.id 取得專屬 ID
• mozContact.updated 中的 Date 物件，將代表聯絡人最後的更新時間

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

刪除聯絡人

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

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

規格

瀏覽器相容性

Gecko 說明

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

另可參閱

• navigator.mozContacts
• mozContact
• ContactManager
• MozContactChangeEvent