PhoneGap API帮助文档翻译—Contacts（通讯录）

来源：互联网发布：java做自我介绍编辑：程序博客网时间：2024/05/17 21:55

PhoneGap API帮助文档翻译—Contacts（通讯录）

“ 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> <script type="text/javascript" charset="utf-8" src="phonegap.js"></script><script type="text/javascript" charset="utf-8"> // 等待加载PhoneGapdocument.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:����;margin-top:10px; margin-bottom:15px; font-size:20px; font-weight:bold"></span>

完整的范例：

<!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"> // 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> <script type="text/javascript" charset="utf-8" src="phonegap.js"></script><script type="text/javascript" charset="utf-8"> // 等待加载PhoneGapdocument.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> <script type="text/javascript" charset="utf-8" src="phonegap.js"></script><script type="text/javascript" charset="utf-8"> // 等待加载PhoneGapdocument.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：支持，将返回BlackBerryaddress1和address2两个地址字段的串联。
locality：支持，存储到BlackBerrycity字段。
region：支持，存储到BlackBerry stateProvince字段。
postalCode：支持，存储到BlackBerryzipPostal字段。
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> <script type="text/javascript" charset="utf-8" src="phonegap.js"></script><script type="text/javascript" charset="utf-8"> // 等待加载PhoneGapdocument.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>

完整的范例：

<span style="font-size:13px;"><!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"> // 等待加载PhoneGapdocument.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>

完整的范例：

<span style="font-size:13px;"><!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"> // 等待加载PhoneGapdocument.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：部分支持，将返回BlackBerryfirstName和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>

完整的范例：

<span style="font-size:13px;"><!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"> // 等待加载PhoneGapdocument.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)