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。
建立並傳回一個新的 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");
查詢裝置通訊錄,傳回 Contact 物件陣列,並透過 contactSuccess 回呼交給呼叫端。
navigator.contacts.find(contactFields, contactSuccess, contactError, 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>
代表一位聯絡人,包含個人或商務聯絡資訊。
屬性:
方法:
// 建立並儲存
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);
須注意:並非所有平台都支援上述全部欄位,實際支援情況請參閱各平台的差異說明。
承載姓名結構,包含 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,同樣不獨立保存。
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 亦不支援。
存放單筆地址,一個 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。
描述聯絡人的任職資訊: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。
控制 contacts.find 的搜尋行為:
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 回呼,僅有一個 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 都要求先取得使用者授權,未授權時就會收到權限錯誤。除了攔下錯誤,更妥善的做法是在使用前先向使用者說明用途,並為拒絕授權的情況準備降級方案。