Ios教程網 >> IOS編程開發 >> IOS開發綜合 >> PhoneGap API中文幫助文檔——Contacts（通訊錄)

PhoneGap API中文幫助文檔——Contacts（通訊錄)

編輯：IOS開發綜合

contacts對象提供對設備通訊錄數據庫的訪問。
方法：
contacts.create
contacts.find

參數：
contactFields
contactSuccess
contactError
contactFindOptions

對象：
Contact
ContactName
ContactField
ContactAddress
ContactOrganization
ContactFindOptions
ContactError

contacts.create

--------------------------------------------------------------------------------
返回一個新的Contact對象。
var contact = navigator.service.contacts.create(properties);
復制代碼說明：
contacts.create是用於創建並返回一個新Contact對象的同步函數。
該方法不會將新創建的Contact對象持久化到設備的通訊錄數據庫。可通過調用Contact.save方法將新建的Contact對象持久化到設備。
支持的平台：
Android
BlackBerry WebWorks (OS 5.0或更高版本)
iOS

簡單的范例：
<span style="font-size:13px;">var myContact = navigator.service.contacts.create({"displayName": "Test User"});</span>
復制代碼完整的范例：
<span style="font-size:13px;"><!DOCTYPE html>

<html>

<head>

<title>Contact Example</title>

// 等待加載PhoneGap

document.addEventListener("deviceready", onDeviceReady, false);

// PhoneGap加載完畢

function onDeviceReady() {

var myContact = navigator.service.contacts.create({"displayName": "Test User"});

myContact.gender = "male";

console.log("The contact, " + myContact.displayName + ", is of the " + myContact.gender + " gender");

}

</script>

</head>

<body>

<h1>Example</h1>

<p>Create Contact</p>

</body>

</html></span>
復制代碼
contacts.find
查詢設備通訊錄數據庫，並返回包含指定字段的一個或多個Contact對象。
navigator.service.contacts.find(contactFields, contactSuccess, contactError, contactFindOptions);
復制代碼
說明：
contacts.find是一個查詢設備通訊錄數據庫並返回Contact對象數組的同步函數。返回的對象會被傳遞給contactSuccess回調函數的contactSuccess參數。
用戶必須在contactFields參數中指定聯系人的字段作為搜索限定符。系統傳遞給contactSuccess回調函數的Contact對象屬性只會包含在contactFields參數中定義的字段。如果定義0長度的contactFields參數會導致返回的Contact對象只填充了id屬性。
contactFindOptions.filter字符串可以用來作為查詢通訊錄數據庫時的搜索過濾器。如果設定了該參數，系統會對通訊錄數據庫中所有聯系人按照contactFields參數中指定的每個字段進行不區分大小寫的部分值匹配。任何指定的字段符合過濾器所要求的內容的聯系人數據都會被返回。

屬性：

contactFields：Contact字段，用作搜索限定符。在返回的Contact對象中只有這些字段有值。（DOMString[]類型）[必填]
contactSuccess：通訊錄獲取成功時調用的回調函數，將從通訊錄數據庫獲取的聯系人作為參數。[必填]
contactError：錯誤回調函數，當發生錯誤的時候被調用。[可選]
contactFindOptions：用於過濾通訊錄的搜索選項。[可選]

支持的平台：
Android
BlackBerry WebWorks (OS 5.0或更高版本)
iOS

簡單的范例：
<span style="font-size:13px;">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.service.contacts.find(fields, onSuccess, onError, options);</span><span style="font-family:Tahoma;margin-top:10px; margin-bottom:15px; font-size:20px; font-weight:bold">
復制代碼完整的范例：
<!DOCTYPE html>

<html>

<head>

<title>Contact Example</title>

// PhoneGap加載完畢

function onDeviceReady() {

// 從所有聯系人中查找任意名字字段中包含“Bob”的聯系人

var options = new ContactFindOptions();

options.filter="Bob";

var fields = ["displayName", "name"];

navigator.service.contacts.find(fields, onSuccess, onError, options);

}

// onSuccess: 獲取當前聯系人結果集的快照

function onSuccess(contacts) {

for (var i=0; i<contacts.length; i++) {

console.log("Display Name = " + contacts[i].displayName);

}

// onError: 獲得聯系人失敗

function onError() {

alert('onError!');

}

</script>

</head>

<body>

<h1>Example</h1>

<p>Find Contact</p>

</body>

</html>
復制代碼
Contact
--------------------------------------------------------------------------------
包含描述聯系人的屬性，比如用戶的個人或者商務聯系方式。

屬性：
id：全局唯一標識符。（DOMString類型）
displayname：聯系人顯示名稱，適合向最終用戶展示的聯系人名稱。（DOMString類型）
name：聯系人姓名所有部分的對象。（CantactName類型）
nickname：昵稱，對聯系人的非正式稱呼。（DOMString類型）
phoneNumbers：聯系人所有聯系電話的數組。（ContactField[]類型）
emails：聯系人所有email地址的數組。（ContactField[]類型）
addrsses：聯系人所有聯系地址的數組。（ContactAddresses[]類型）
ims：聯系人所有IM地址的數組。（ContactField[]類型）
organizations：聯系人所屬所有組織的數組。（ContactOrganization[]類型）
birthday：聯系人的生日。（日期類型）
note：聯系人的注釋信息。（DOMString類型）
photos：聯系人所有照片的數組.（ContactField[]類型）
categories：聯系人所屬的所有用戶自定義類別的數組。（ContactField[]類型）
urls：與聯系人相關網頁的數組。（ContactField[]類型）

方法：
clone：返回一個新的Contact對象，它是調用對象的深度拷貝，其id屬性被設為null。
remove：從通訊錄數據庫中刪除聯系人。當刪除不成功的時候，觸發以ContactError對象為參數的錯誤處理回調函數。
save：將一個新聯系人存儲到通訊錄數據庫，如果通訊錄數據庫中已經包含與其ID相同的記錄，則更新該已有記錄。

詳述：
Contact對象代表一個用戶聯系人。Contacts可以在設備通訊錄數據庫中被創建，存儲或者刪除，同樣也可以使用 contacts.find方法從數據庫中進行檢索。
備注：並不是所有的設備平台都支持以上列出的所有聯系人字段。請通過查看每個平台的特異情況描述部分，了解每個平台分別支持哪些字段。

支持的平台：
Android
BlackBerry WebWorks (OS 5.0或更高版本)
iOS

Save 簡單的范例：

<span style="font-size:13px;">function onSuccess(contacts) {

alert("Save Success");

}

function onError(contactError) {

alert("Error = " + contactError.code);

}

// 建立一個新的聯系人對象

var contact = navigator.service.contacts.create();

contact.displayName = "Plumber";

contact.nickname = "Plumber"; //同時指定以支持所有設備

// 填充一些字段

var name = new ContactName();

name.givenName = "Jane";

name.familyName = "Doe";

contact.name = name;

// 存儲到設備上

contact.save(onSuccess,onError);</span>
復制代碼Clone 簡單的范例：
<span style="font-size:13px;">// 克隆聯系人對象

var clone = contact.clone();

clone.name.givenName = "John";

console.log("Original contact name = " + contact.name.givenName);

console.log("Cloned contact name = " + clone.name.givenName);</span>
復制代碼Remove 簡單的范例：
function onSuccess() {

alert("Removal Success");

}

function onError(contactError) {

alert("Error = " + contactError.code);

}

// 從設備上刪除該聯系人

contact.remove(onSuccess,onError);
復制代碼完整的范例：
<span style="font-size:13px;"><!DOCTYPE html>

<html>

<head>

<title>Contact Example</title>

// 等待加載PhoneGap

document.addEventListener("deviceready", onDeviceReady, false);

// PhoneGap加載完畢

function onDeviceReady() {

// 創建聯系人

var contact = navigator.service.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);

// 刪除聯系人

contact.remove(onRemoveSuccess,onRemoveError);

}

// onSaveSuccess: 返回當前保存成功的聯系人數據的快照

function onSaveSuccess(contacts) {

alert("Save Success");

}

// onSaveError: 獲取聯系人數據失敗

function onSaveError(contactError) {

alert("Error = " + contactError.code);

}

// onRemoveSuccess: 返回當前刪除成功的聯系人數據的快照

function onRemoveSuccess(contacts) {

alert("Removal Success");

}

// onRemoveError: 獲取聯系人數據失敗

function onRemoveError(contactError) {

alert("Error = " + contactError.code);

}

</script>

</head>

<body>

<h1>Example</h1>

<p>Find Contact</p>

</body>

</html></span>
復制代碼
Android 2.X的特異情況：
categories：Android2.X設備上不支持該屬性，返回值總是null。

Android 1.X的特異情況：
name：Android1.x設備上不支持該屬性，返回值總是null。
nickname：Android1.x設備上不支持該屬性，返回值總是null。
birthday： Android1.x設備上不支持該屬性，返回值總是null。
photos：Android1.x設備上不支持該屬性，返回值總是null。
categories：Android1.x設備上不支持該屬性，返回值總是null。
urls：Android1.x設備上不支持該屬性，返回值總是null。

BlackBerry WebWorks (OS 5.0或更高版本)的特異情況：
id：支持，系統在存儲聯系人記錄時自動分配。
displayname：支持，存儲到BlackBerry的user1字段。
nickname：不支持該屬性，返回值總是null。
phoneNumber：部分支持，類型為“home”的電話號碼將被存儲到BlackBerry的homePhone1和homePhone2字段；類型為“work”將被存儲到workPhone1和workPhone2字段；類型為“mobile”將被存儲到mobilePhone；類型為“fax”將被存儲到faxPhone字段；類型為“pager”將被存儲到pagerPhone；如果電話號碼不屬於以上類型則被存儲到otherPhone字段。
emails：部分支持，前三個郵件地址將被分別存儲到BlackBerry的email1、email2和email3這三個字段。
addresses：部分支持，第一和第二個地址將被分別存儲到BlackBerry的homeAddress以及workAddress字段。
ims：不支持該屬性，返回值總是null。
organizations：部分支持，第一個組織的名稱和職務將被分別存儲到BlackBerry的company和title字段。
photos：部分支持，只支持一個縮略圖大小的照片。要設置一個聯系人照片的話，可以通過傳遞一個Base64編碼的圖片或一個指向圖片的URL，該圖片在存儲到聯系人數據庫之前會被縮小。聯系人照片會以Base64編碼形式的圖片返回。
categories：部分支持，只支持“Business”和“Personal”這兩個類別。
urls：部分支持，第一個url將被存儲到BlackBerry的webpage字段。

iOS的特異情況：
displayName：iOS不支持該屬性。除非沒有給聯系人指定ContactName，否則該字段返回值總是null。如果沒有指定ContactName，系統會根據有無設定值的情況依次返回composite name，nickename或空字符串。
birthday：對於輸入而言，必須為其提供一個JavaScript日期對象。同樣其返回值也是JavaScript日期對象。
photos：傳回的照片存儲在應用程序的臨時目錄，同時返回指向該照片的文件URL。臨時目錄在應用程序退出後被刪除。
categories：目前不支持該屬性，返回值總是null。

ContactAddress
--------------------------------------------------------------------------------

包含Contact對象的地址屬性。

屬性：
pref：如果該ContactAddress包含用戶的首選值，則設置為true。（布爾類型）
type：用來標示該地址對應的類型的字符串（例如：“home”）。（DOMString類型）
formatted：完整的地址顯示格式。（DOMString格式）
streeAddress：完整的街道地址。（DOMString格式）
locality：城市或地區。（DOMString格式）
region：州或省份。（DOMString格式）
postalCode：郵政編碼。（DOMString格式）
country：國家名稱。（DOMString格式）

詳述：
ContactAddress對象存儲一個聯系人的單個地址。一個Contact對象可以擁有一個或多個地址，這些地址存儲在一個ContactAddress[]數組中。

支持的平台：
Android
BlackBerry WebWorks (OS 5.0或更高版本)
iOS

簡單的范例：
<span style="font-size:13px;">// 顯示所有聯系人的地址信息

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

}

function onError(contactError) {

alert('onError!');

}

// 從全部聯系人中查找

var options = new ContactFindOptions();

options.filter="";

var filter = ["displayName","addresses"];

navigator.contacts.find(filter, onSuccess, onError, options);</span>
復制代碼完整的范例：
<span style="font-size:13px;"><!DOCTYPE html>

<html>

<head>

<title>Contact Example</title>

// 等待加載PhoneGap

document.addEventListener("deviceready", onDeviceReady, false);

// PhoneGap加載完畢

function onDeviceReady() {

// 從全部聯系人中進行搜索

var options = new ContactFindOptions();

options.filter="";

var filter = ["displayName","addresses"];

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

}

// onSuccess: 返回當前聯系人結果集的快照

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

}

// onError: 獲取聯系人結果集失敗

function onError() {

alert('onError!');

}

</script>

</head>

<body>

<h1>Example</h1>

<p>Find Contact</p>

</body>

</html></span>
復制代碼
Android 2.X 的特異情況
pref：Android2.X設備上不支持該屬性，返回值總是false。

Android 1.X 的特異情況：
pref：Android1.X設備上不支持該屬性，返回值總是false。
type：Android1.X設備上不支持該屬性，返回值總是null。
streetAddress：Android1.X設備上不支持該屬性，返回值總是null。
locality：Android1.X設備上不支持該屬性，返回值總是null。
region：Android1.X設備上不支持該屬性，返回值總是null。
postalCode：Android1.X設備上不支持該屬性，返回值總是null。
country：Android1.X設備上不支持該屬性，返回值總是null。

BlackBerry WebWorks (OS 5.0或更高版本)的特異情況：
pref：BlackBerry設備上不支持該屬性，返回值總是false。
type：部分支持，對於一個聯系人對象只能分別存儲一個“Work”和一個“Home”類型的地址。
formatted：部分支持，將返回所有BlackBerry 地址字段的串聯。
streetAddress：支持，將返回BlackBerry address1和address2兩個地址字段的串聯。
locality：支持，存儲到BlackBerry city字段。
region：支持，存儲到BlackBerry stateProvince字段。
postalCode：支持，存儲到BlackBerry zipPostal字段。
country：支持。

iOS的特異情況：
pref：iOS設備上不支持該屬性，返回值總是false。
formatted：目前不支持。

ContactField

Contact對象中支持的通用字段類型，存儲為ContactField對象的屬性包括：email addresses、phone numbers和urls等。

屬性：
type：說明當前字段類型的字符串（例如：“home”）。（DOMString類型）
value：字段的值（例如：電話號碼或郵件地址）。（DOMString類型）
pref：如果當前ContactField包含用戶的首選項，則設置為true。（布爾類型）

詳述：
ContactField對象是一個可重用的組件，用於支持通用方式的聯系人字段。每個ContactField對象都包含一個值屬性、一個類型屬性和一個首選項屬性。一個Contact對象將多個屬性分別存儲到多個ContactField[]數組中，例如電話號碼與郵件地址等。
在大多數情況下，ContactField對象中的type屬性並沒有事先確定值。例如，一個電話號碼的type屬性值可以是：“home”、“work”、“mobile”、“iPhone”或其他相應特定設備平台的聯系人數據庫所支持的值。然而對於Contact對象的photos字段，PhoneGap使用type字段來表示返回的圖像格式。如果value屬性包含的是一個指向照片圖像的URL，PhoneGap對於type會返回“url”；如果value屬性包含的是圖像的Base64編碼字符串，PhoneGap對於type會返回“base64”。

支持的平台：
Android
BlackBerry WebWorks (OS 5.0或更高版本)
iOS

簡單的范例：
<span style="font-size:13px;">// 建立一個新的聯系人記錄

var contact = navigator.service.contacts.create();

// 存儲聯系人電話號碼到ContactField[]數組

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();</span>
復制代碼完整的范例：
<span style="font-size:13px;"><!DOCTYPE html>

<html>

<head>

<title>Contact Example</title>

// 等待加載PhoneGap

document.addEventListener("deviceready", onDeviceReady, false);

// PhoneGap加載完畢

function onDeviceReady() {

// 建立一個新的聯系人記錄

var contact = navigator.service.contacts.create();

//存儲聯系人電話號碼到ContactField[]數組

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();

// 搜索聯系人列表，返回符合條件聯系人的顯示名及電話號碼

var options = new ContactFindOptions();

options.filter="";

filter = ["displayName","phoneNumbers"];

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

}

// onSuccess：返回聯系人結果集的快照

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

}

// onError: 獲取聯系人結果集失敗

function onError() {

alert('onError!');

}

</script>

</head>

<body>

<h1>Example</h1>

<p>Find Contact</p>

</body>

</html></span>
復制代碼
Android 的特異情況：
pref：Android設備上不支持該屬性，返回值總是false。

BlackBerry WebWorks (OS 5.0或更高版本)的特異情況：
type：部分支持，用於電話號碼。
value：支持。
pref：不支持該屬性，返回值總是false。

iOS的特異情況：
pref：iOS設備上不支持該屬性，返回值總是false。

ContactFindOptions

包含用於contacts.find操作對所有聯系人進行過濾的屬性。

屬性：
filter：用於查找聯系人的搜索字符串。(DOMString類型) (默認值為空字符串)
multiple：決定查收操作是否可以返回多條聯系人記錄。(布爾類型) (默認值為false)

支持的平台：
Android
BlackBerry WebWorks (OS 5.0或更高版本)
iOS

簡單的范例：

<span style="font-size:13px;">// 成功後的回調函數

function onSuccess(contacts) {

for (var i=0; i< ;contacts.length; i++) {

alert(contacts[i].displayName);

}

// 出錯後的回調函數

function onError() {

alert('onError!');

}

// 指定聯系人搜索條件

var options = new ContactFindOptions();

options.filter=""; // 空搜索字符串將返回所有聯系人

options.multiple=true; // 可返回多條記錄

filter = ["displayName"]; // 僅返回contact.displayName字段

// 查找聯系人

navigator.service.contacts.find(filter, onSuccess, onError, options);</span>
復制代碼完整的范例：

<html>

<head>

<title>Contact Example</title>

// 等待加載PhoneGap

document.addEventListener("deviceready", onDeviceReady, false);

// PhoneGap加載完畢

function onDeviceReady() {

// 指定聯系人搜索條件

var options = new ContactFindOptions();

options.filter=""; // 空搜索字符串將返回所有聯系人

options.multiple=true; // 可返回多條記錄

filter = ["displayName"]; // 僅返回contact.displayName字段

// 查找聯系人

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

}

// onSuccess: 返回當前聯系人記錄集的快照

function onSuccess(contacts) {

for (var i=0; i< contacts.length; i++) {

alert(contacts[i].displayName);

}

// onError: 獲取聯系人失敗

function onError() {

alert('onError!');

}

</script>

</head>

<body>

<h1>Example</h1>

<p>Find Contact</p>

</body>

</html></span>
復制代碼
ContactName
包含Contact對象的名稱屬性。
屬性：
formatted：聯系人的全名。（DOMString類型）
familyName：聯系人的姓氏。（DOMString類型）
givenName：聯系人的名字。（DOMString類型）
middleName：聯系人的中間名。（DOMString類型）
honorificPrefix：敬語前綴。（例如：Mr.或Dr.）(DOMString類型)
honorificSuffix：敬語後綴。（例如：Esq.）(DOMString)

詳述：
ContactName對象存儲聯系人的name屬性。

支持的平台：
Android 2.X
BlackBerry WebWorks (OS 5.0或更高版本)
iOS

簡單的范例：

<span style="font-size:13px;">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.honorificSuffix);

}

function onError() {

alert('onError!');

}

var options = new ContactFindOptions();

options.filter="";

filter = ["displayName","name"];

navigator.service.contacts.find(filter, onSuccess, onError, options);</span>
復制代碼
完整的范例：

<html>

<head>

<title>Contact Example</title>

// 等待加載PhoneGap

document.addEventListener("deviceready", onDeviceReady, false);

// PhoneGap加載完畢

function onDeviceReady() {

var options = new ContactFindOptions();

options.filter="";

filter = ["displayName"];

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

}

// onSuccess: 返回聯系人結果集的快照

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

}

// onError: 獲取聯系人結果集失敗

function onError() {

alert('onError!');

}

</script>

</head>

<body>

<h1>Example</h1>

<p>Find Contact</p>

</body>

</html></span>
復制代碼
Android 的特異情況：
formatted：部分支持，將返回honorificPrefix、givenName、middleName、familyName和honorificSuffix的串聯結果，但不會單獨存儲。

BlackBerry WebWorks (OS 5.0或更高版本)的特異情況：
formatted：部分支持，將返回BlackBerry firstName和lastName兩個字段的串聯結果。
familyName：支持，存放到BlackBerry 的lastName字段。
givenName：支持，存儲到BlackBerry 的firstName字段。
middleName：不支持該屬性，返回值總是null。
honorificPrefix：不支持該屬性，返回值總是null。
honorificSuffix：不支持該屬性，返回值總是null。

iOS的特異情況：
formatted：部分支持，將返回iOS的Composite Name，但不會單獨存儲。

ContactOrganization

--------------------------------------------------------------------------------

包含Contact對象的所屬組織屬性。

屬性：

pref：如果該ContactOrganization包含用戶的首選值，則設置為true。（布爾類型）

type：用來標示該所屬組織對應的類型的字符串（例如：“home”）。（DOMString類型）

name：組織的名稱。（DOMString類型）

department：聯系人工作的部門。（DOMString類型）

title：聯系人在所屬組織內的職務。（DOMString類型）

詳述：

ContactOrganization對象存儲聯系人的所屬組織屬性，Contact對象通過一個數組存儲一個或多個ContactOrganization對象。

支持的平台：

Android

BlackBerry WebWorks (OS 5.0或更高版本)

iOS

簡單的范例：
復制代碼 <span style="font-size:13px;">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);

}

function onError() {

alert('onError!');

}

var options = new ContactFindOptions();

options.filter="";

filter = ["displayName","organizations"];

navigator.service.contacts.find(filter, onSuccess, onError, options);</span>
復制代碼
完整的范例：

<html>

<head>

<title>Contact Example</title>

// 等待加載PhoneGap

document.addEventListener("deviceready", onDeviceReady, false);

// PhoneGap加載完畢

function onDeviceReady() {

var options = new ContactFindOptions();

options.filter="";

filter = ["displayName","organizations"];

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

}

// onSuccess: 返回當前聯系人結果集的快照

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

}

// onError：獲取聯系人失敗

function onError() {

alert('onError!');

}

</script>

</head>

<body>

<h1>Example</h1>

<p>Find Contact</p>

</body>

</html></span>
復制代碼
Android 2.X 的特異情況：
pref：Android2.X設備上不支持該屬性，返回值總是false。

Android 1.X 的特異情況：
pref：Android1.X設備上不支持該屬性，返回值總是false。
type：Android1.X設備上不支持該屬性，返回值總是null。
title：Android1.X設備上不支持該屬性，返回值總是null。

BlackBerry WebWorks (OS 5.0或更高版本)的特異情況：
pref：BlackBerry設備上不支持該屬性，返回值總是false。
type：BlackBerry設備上不支持該屬性，返回值總是null。
name：部分支持，第一個組織名稱將被存儲到BlackBerry 的company字段。
department：不支持該屬性，返回值總是null。
title：部分支持，第一個組織職務將被存儲到BlackBerry 的jobTitle字段。

iOS的特異情況：
pref：iOS設備上不支持該屬性，返回值總是false。
type：iOS設備上不支持該屬性，返回值總是null。
name：部分支持，第一個組織名稱將被存放到iOS的kABPersonOrganizationProperty字段。
department：部分支持，第一個部門名字將被存放到iOS的kABPersonDepartmentProperty字段。
title：部分支持，第一個組織職務將被存放到iOS的kABPersonJobTitleProperty字段。

ContactError

--------------------------------------------------------------------------------

當有錯誤發生時，一個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：權限被拒絕錯誤類型

說明：
當有錯誤發生時，ContactError對象會通過contactError回調函數返回給用戶。

contactSuccess

--------------------------------------------------------------------------------
contacts.find操作成功時調用的回調函數，同時返回查找到的Contact數組。

簡單的范例：
<span style="font-size:13px;">function(contacts) {

// 後續操作

}</span>
復制代碼參數：
contacts：查找操作返回的聯系人數組。（Contact[]類型）

范例： <span style="font-size:13px;">function contactSuccess(contacts) {

for (var i=0; i< contacts.length; i++) {

console.log(“Display Name = ” + contacts[i].displayName;

}

}</span>
復制代碼contactError
--------------------------------------------------------------------------------

操作聯系人出錯時的回調函數。

function(error) {

// 錯誤處理

}
復制代碼contactFields

--------------------------------------------------------------------------------

contacts.find方法的必填參數，該參數定義了查找操作返回的Contact對象中應該包含哪些字段。
["name", "phoneNumbers", "emails"]
復制代碼contactFindOptions
--------------------------------------------------------------------------------
contats.find方法的可選參數，通過該參數從通訊錄數據庫中篩選聯系人。

{

filter: "",

multiple: true

}
復制代碼選項：
filter：用於查找聯系人的搜索字符串。(DOMString類型) (默認值為空字符串)
multiple：決定查找操作是否可以返回多條聯系人記錄。(布爾類型) (默認值為false)

作者：LuoXianXion

上一頁:PhoneGap API中文幫助文檔——Storage（存儲）
下一頁:iPhone開發：info.plist（四）

IOS開發綜合

iOS開發根本功的那些事兒(未完待續) Objc 一.三大特性 1.封裝_點語法 2.承繼 3.多

ios下(個人公司非企業級)AdHoc在線安裝全環境配置 1，環境客戶端開發：MacOs 10.8.5 服務器開發：

關於iOS導航欄前往按鈕成績的處理辦法比來碰到一個關於導航欄前往按鈕的成績，由於之前項目外面都是

IOS編程開發

IOS開發基礎 IOS編程技術 IOS開發綜合

iOS 畫地圖上的標注氣泡