您现在的位置: IOS教程網 >> IOS系統 >  >> iOS 程式開發 >> iOS 開發綜合

PhoneGap API 中文說明文件:Contacts(通訊錄)

編輯:iOS 開發綜合

Contacts 模組概覽

Contacts 模組讓網頁應用程式得以讀寫裝置的通訊錄資料庫——建立聯絡人、搜尋聯絡人、更新既有資料、刪除記錄,都在它的能力範圍之內。

模組只提供兩個主要方法:

  • contacts.create:建立並傳回新的 Contact 物件
  • contacts.find:查詢通訊錄並傳回符合條件的 Contact 陣列

相關參數有 contactFields、contactSuccess、contactError、contactFindOptions;相關物件則包括 Contact、ContactName、ContactField、ContactAddress、ContactOrganization、ContactFindOptions 與 ContactError。

支援平台:Android、BlackBerry WebWorks(OS 5.0 以上)、iOS。

contacts.create

建立並傳回一個新的 Contact 物件。這是同步函式,重點在於它不會自動寫入通訊錄——必須再呼叫 Contact 的 save 方法才會真正持久化。

var contact = navigator.contacts.create(properties);
var myContact = navigator.contacts.create({"displayName": "Test User"});
myContact.gender = "male";
console.log("The contact, " + myContact.displayName
          + ", is of the " + myContact.gender + " gender");

contacts.find

查詢裝置通訊錄,傳回 Contact 物件陣列,並透過 contactSuccess 回呼交給呼叫端。

navigator.contacts.find(contactFields, contactSuccess, contactError, contactFindOptions);

參數:

  • contactFields(必填,DOMString[]):作為搜尋限定欄位的 Contact 屬性名稱。回傳的 Contact 物件只會填入這裡列出的欄位。若傳入長度為 0 的陣列,結果物件將只帶有 id。
  • contactSuccess(必填,Function):查詢成功時呼叫,參數為聯絡人陣列。
  • contactError(選填,Function):出錯時呼叫。
  • contactFindOptions(選填):搜尋選項物件。

contactFindOptions.filter 是搜尋用的關鍵字字串。一旦設定,系統會對通訊錄中每位聯絡人的指定欄位進行不分大小寫的部分比對,凡任一欄位命中者都會被回傳。

function onSuccess(contacts) {
    alert('Found ' + contacts.length + ' contacts.');
}

function onError() {
    alert('onError!');
}

// 在所有聯絡人中,尋找名字欄位含有 "Bob" 者
var options = new ContactFindOptions();
options.filter = "Bob";
var fields = ["displayName", "name"];
navigator.contacts.find(fields, onSuccess, onError, options);

完整範例:

<!DOCTYPE html>
<html>
<head>
    <title>Contact Example</title>
    <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
    <script type="text/javascript" charset="utf-8">
        function onDeviceReady() {
            var options = new ContactFindOptions();
            options.filter = "Bob";
            var fields = ["displayName", "name"];
            navigator.contacts.find(fields, onSuccess, onError, options);
        }

        // 取得結果快照
        function onSuccess(contacts) {
            for (var i = 0; i < contacts.length; i++) {
                console.log("Display Name = " + contacts[i].displayName);
            }
        }

        function onError() {
            alert('onError!');
        }

        document.addEventListener("deviceready", onDeviceReady, false);
    </script>
</head>
<body>
    <h1>Example</h1>
    <p>Find Contact</p>
</body>
</html>

Contact

代表一位聯絡人,包含個人或商務聯絡資訊。

屬性:

  • id:全域唯一識別碼(DOMString)
  • displayName:適合顯示給使用者看的名稱(DOMString)
  • name:包含姓名各部分的 ContactName 物件
  • nickname:暱稱(DOMString)
  • phoneNumbers:電話陣列(ContactField[])
  • emails:電子郵件陣列(ContactField[])
  • addresses:地址陣列(ContactAddress[])
  • ims:即時通訊帳號陣列(ContactField[])
  • organizations:所屬組織陣列(ContactOrganization[])
  • birthday:生日(Date)
  • note:備註(DOMString)
  • photos:照片陣列(ContactField[])
  • categories:自訂類別陣列(ContactField[])
  • urls:相關網址陣列(ContactField[])

方法:

  • clone:傳回呼叫者的深層複本,且 id 設為 null。
  • remove:從通訊錄刪除該聯絡人,失敗時觸發帶 ContactError 參數的錯誤回呼。
  • save:存入通訊錄;若已存在相同 id 的記錄則改為更新。
// 建立並儲存
function onSaveSuccess(contact) {
    alert("Save Success");
}

function onSaveError(contactError) {
    alert("Error = " + contactError.code);
}

var contact = navigator.contacts.create();
contact.displayName = "Plumber";
contact.nickname = "Plumber";        // 同時指定以相容所有裝置

var name = new ContactName();
name.givenName = "Jane";
name.familyName = "Doe";
contact.name = name;

contact.save(onSaveSuccess, onSaveError);

// 複製
var clone = contact.clone();
clone.name.givenName = "John";
console.log("Original contact name = " + contact.name.givenName);
console.log("Cloned contact name = " + clone.name.givenName);

// 刪除
function onRemoveSuccess() {
    alert("Removal Success");
}
contact.remove(onRemoveSuccess, onSaveError);

須注意:並非所有平台都支援上述全部欄位,實際支援情況請參閱各平台的差異說明。

各平台欄位差異(Contact)

  • Android 2.X:categories 不支援,恆為 null。
  • Android 1.X:name、nickname、birthday、photos、categories、urls 皆不支援,恆為 null。
  • BlackBerry WebWorks(OS 5.0 以上):
    • id 由系統在存入時自動配置;displayName 存到 user1。
    • phoneNumber 部分支援,依型別分流:home 對應 homePhone1/2、work 對應 workPhone1/2、mobile 對應 mobilePhone、fax 對應 faxPhone、pager 對應 pagerPhone,其餘歸入 otherPhone。
    • emails 僅前三筆有效,分別存入 email1、email2、email3。
    • addresses 僅前兩筆有效,存入 homeAddress 與 workAddress。
    • organizations 僅第一筆的名稱與職稱,存入 company 與 title。
    • photos 僅支援一張縮圖;可傳入 Base64 圖片或圖片 URL,存入前會先縮小,讀出時以 Base64 形式回傳。
    • categories 僅支援 "Business" 與 "Personal";urls 僅第一筆,存入 webpage。
    • nickname、ims 不支援,恆為 null。
  • iOS:displayName 在指定了 ContactName 時恆為 null;未指定時才依序回傳 composite name、nickname 或空字串。birthday 的輸入與輸出都是 JavaScript 日期物件。photos 會存到應用程式的暫存目錄並回傳檔案 URL,該目錄在程式結束後即被清除。categories 不支援。

ContactName

承載姓名結構,包含 formatted(全名)、familyName(姓)、givenName(名)、middleName(中間名)、honorificPrefix(前置敬稱,如 Mr.、Dr.)與 honorificSuffix(後置敬稱,如 Esq.)。支援平台:Android 2.X、BlackBerry WebWorks(OS 5.0 以上)、iOS。

function onSuccess(contacts) {
    for (var i = 0; i < contacts.length; i++) {
        alert("Formatted: " + contacts[i].name.formatted + "\n" +
              "Family Name: " + contacts[i].name.familyName + "\n" +
              "Given Name: " + contacts[i].name.givenName + "\n" +
              "Middle Name: " + contacts[i].name.middleName + "\n" +
              "Suffix: " + contacts[i].name.honorificSuffix + "\n" +
              "Prefix: " + contacts[i].name.honorificPrefix);
    }
}

平台差異:Android 的 formatted 是各欄位的串接結果,不會獨立保存;BlackBerry 的 formatted 由 firstName 與 lastName 串接而來,familyName 對應 lastName、givenName 對應 firstName,middleName 與兩個敬稱欄位皆不支援;iOS 的 formatted 回傳系統的 Composite Name,同樣不獨立保存。

ContactField

PhoneGap 用來統一表示「一組值+型別」的通用容器,email、電話號碼、網址等都可用它裝。屬性有三個:type(型別字串,如 "home")、value(實際內容)、pref(是否為使用者的首選,Boolean)。

多數情況下 type 沒有預先定義好的取值,可能是 "home"、"work"、"mobile"、"iPhone",或任何該平台通訊錄所支援的值。唯一的例外是 photos:此時 type 用來表示影像格式,若 value 是圖片 URL 則回傳 "url",若是 Base64 字串則回傳 "base64"。

// 建立聯絡人並存入三組電話
var contact = navigator.contacts.create();

var phoneNumbers = [3];
phoneNumbers[0] = new ContactField('work', '212-555-1234', false);
phoneNumbers[1] = new ContactField('mobile', '917-555-5432', true);   // 首選
phoneNumbers[2] = new ContactField('home', '203-555-7890', false);
contact.phoneNumbers = phoneNumbers;

contact.save();

讀回並逐筆顯示:

function onSuccess(contacts) {
    for (var i = 0; i < contacts.length; i++) {
        for (var j = 0; j < contacts[i].phoneNumbers.length; j++) {
            alert("Type: " + contacts[i].phoneNumbers[j].type + "\n" +
                  "Value: " + contacts[i].phoneNumbers[j].value + "\n" +
                  "Preferred: " + contacts[i].phoneNumbers[j].pref);
        }
    }
}

var options = new ContactFindOptions();
options.filter = "";
navigator.contacts.find(["displayName", "phoneNumbers"], onSuccess, onError, options);

平台差異:Android 與 iOS 的 pref 恆為 false;BlackBerry 的 type 僅用於電話號碼,pref 亦不支援。

ContactAddress

存放單筆地址,一個 Contact 可擁有多筆,以 ContactAddress[] 保存。屬性:pref、type、formatted、streetAddress、locality(城市或地區)、region(州/省)、postalCode、country。

function onSuccess(contacts) {
    for (var i = 0; i < contacts.length; i++) {
        for (var j = 0; j < contacts[i].addresses.length; j++) {
            alert("Pref: " + contacts[i].addresses[j].pref + "\n" +
                  "Type: " + contacts[i].addresses[j].type + "\n" +
                  "Formatted: " + contacts[i].addresses[j].formatted + "\n" +
                  "Street Address: " + contacts[i].addresses[j].streetAddress + "\n" +
                  "Locality: " + contacts[i].addresses[j].locality + "\n" +
                  "Region: " + contacts[i].addresses[j].region + "\n" +
                  "Postal Code: " + contacts[i].addresses[j].postalCode + "\n" +
                  "Country: " + contacts[i].addresses[j].country);
        }
    }
}

var options = new ContactFindOptions();
options.filter = "";
navigator.contacts.find(["displayName", "addresses"], onSuccess, onError, options);

平台差異:Android 2.X 的 pref 恆為 false,Android 1.X 更幾乎所有欄位都回傳 null。BlackBerry 每個聯絡人只能各存一筆 Work 與一筆 Home 地址,formatted 是各地址欄位的串接,streetAddress 由 address1 與 address2 串接,locality 對應 city、region 對應 stateProvince、postalCode 對應 zipPostal。iOS 的 formatted 目前不支援,pref 恆為 false。

ContactOrganization

描述聯絡人的任職資訊:pref、type、name(組織名)、department(部門)、title(職稱)。Contact 以陣列形式保存一或多筆。

function onSuccess(contacts) {
    for (var i = 0; i < contacts.length; i++) {
        for (var j = 0; j < contacts[i].organizations.length; j++) {
            alert("Pref: " + contacts[i].organizations[j].pref + "\n" +
                  "Type: " + contacts[i].organizations[j].type + "\n" +
                  "Name: " + contacts[i].organizations[j].name + "\n" +
                  "Department: " + contacts[i].organizations[j].department + "\n" +
                  "Title: " + contacts[i].organizations[j].title);
        }
    }
}

平台差異:BlackBerry 只保留第一筆的組織名(company)與職稱(jobTitle),department 不支援。iOS 分別對應 kABPersonOrganizationProperty、kABPersonDepartmentProperty 與 kABPersonJobTitleProperty,皆僅取第一筆。Android 1.X 的 type 與 title 不支援,2.X 的 pref 恆為 false。

ContactFindOptions

控制 contacts.find 的搜尋行為:

  • filter:搜尋字串(DOMString,預設空字串;空字串代表傳回全部)。
  • multiple:是否允許傳回多筆(Boolean,預設 false)。
var options = new ContactFindOptions();
options.filter = "";          // 空字串代表傳回所有聯絡人
options.multiple = true;      // 允許傳回多筆
var filter = ["displayName"]; // 只要 displayName 欄位

navigator.contacts.find(filter, onSuccess, onError, options);

回呼函式與輔助型別

contactSuccess:查詢成功時呼叫,收到聯絡人陣列。

function contactSuccess(contacts) {
    for (var i = 0; i < contacts.length; i++) {
        console.log("Display Name = " + contacts[i].displayName);
    }
}

contactError:操作失敗時呼叫,收到 error 物件。

function(error) {
    // 錯誤處理
}

contactFields:find 方法的必填參數,決定回傳物件要填哪些欄位。

["name", "phoneNumbers", "emails"]

contactFindOptions:find 方法的選填參數,用於篩選。

{
    filter: "",
    multiple: true
}

ContactError

出錯時傳給 contactError 回呼,僅有一個 code 屬性。可用的錯誤碼:

  • ContactError.UNKNOWN_ERROR:未知錯誤
  • ContactError.INVALID_ARGUMENT_ERROR:參數無效
  • ContactError.TIMEOUT_ERROR:逾時
  • ContactError.PENDING_OPERATION_ERROR:操作懸置中
  • ContactError.IO_ERROR:輸入輸出錯誤
  • ContactError.NOT_SUPPORTED_ERROR:平台不支援
  • ContactError.PERMISSION_DENIED_ERROR:權限被拒

最後一點在實務上特別重要:讀寫通訊錄屬於敏感資料,無論 iOS 或 Android 都要求先取得使用者授權,未授權時就會收到權限錯誤。除了攔下錯誤,更妥善的做法是在使用前先向使用者說明用途,並為拒絕授權的情況準備降級方案。

  1. 上一篇文章:
  2. 下一篇文章:
蘋果刷機越獄教程| IOS教程問題解答| IOS技巧綜合| IOS7技巧| IOS8教程
Copyright © IOS教程網 All Rights Reserved