mozilla
您的搜尋結果

    Contacts API

    這是一個實驗中的功能
    此功能在某些瀏覽器尚在開發中,請參考兼容表格以得到不同瀏覽器用的前輟。

    This API is available on Firefox OS for privileged or certified applications only.

    摘要

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

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

    管理聯絡人資訊

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

    新增聯絡人

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

    1. 建立新的 mozContact 物件,並列出其必要屬性的欄位。mozContact 介面將定義既有聯絡人的所有可能屬性。這些屬性絕大部分均與 vCard 4.0 規格所定義的相同。以下列出例外:
    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 個函式可檢索系統通訊錄中的聯絡人:

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

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

    還有其他搜尋選項:

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

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

    若搜尋成功,則可於 DOMRequest.result 屬性中找到搜尋結果。可能是 findmozContact 物件陣列;也可能是 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() 而刪除所有的聯絡人。因為一旦完成就沒辦法恢復資料,所以呼叫此函式時請特別謹慎。

    規格

    Specification Status Comment
    Contacts Manager API Working Draft First Working Draft (未穩定)
    vCard Format Specification RFC RFC6350

    瀏覽器相容性

    Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
    基本支援 Not supported Not supported Not supported Not supported Not supported
    Feature Android Chrome for Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
    基本支援 Not supported Not supported (Yes) Not supported Not supported Not supported

    Gecko 說明

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

    另可參閱

    Document Tags and Contributors

    Contributors to this page: MashKao
    最近更新: MashKao,