PhoneGap API介绍:Contacts

移动开发
本文将介绍PhoneGap API——Contacts:和设备联系人数据库相关操作。Contacts对象提供对设备通讯录数据库的访问。

方法

参数

对象

contacts.create

返回一个新的Contact对象。

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

说明

contacts.create是用于创建并返回一个新Contact对象的同步函数。

该方法不会将新创建的Contact对象持久化到设备的通讯录数据库。可通过调用Contact.save方法将新建的Contact对象持久化到设备。

支持的平台

Android

BlackBerry WebWorks (OS 5.0或更高版本)

iOS

简单的范例

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

完整的范例

  1. <!DOCTYPE html> 
  2. <html> 
  3. <head> 
  4. <title>Contact Example</title> 
  5.  
  6. <script type="text/javascript" charset="utf-8" src="phonegap.js"></script> 
  7. <script type="text/javascript" charset="utf-8"> 
  8.  
  9.     // 等待加载PhoneGap 
  10.     document.addEventListener("deviceready", onDeviceReady, false); 
  11.  
  12.     // PhoneGap加载完毕 
  13.     function onDeviceReady() { 
  14.         var myContact = navigator.service.contacts.create({"displayName": "Test User"}); 
  15.         myContact.gender = "male"
  16.         console.log("The contact, " + myContact.displayName + ", is of the " + myContact.gender + " gender"); 
  17.     }  
  18.  
  19. </script> 
  20. </head> 
  21. <body> 
  22.  <h1>Example</h1> 
  23.  <p>Create Contact</p> 
  24. </body> 
  25. </html>

 

contacts.find

查询设备通讯录数据库,并返回包含指定字段的一个或多个Contact对象。

  1. 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

简单的范例

  1. function onSuccess(contacts) { 
  2. alert('Found ' + contacts.length + ' contacts.'); 
  3. function onError() { 
  4. alert('onError!'); 
  5. // 从所有联系人中查找任意名字字段中包含“Bob”的联系人 
  6. var options = new ContactFindOptions(); 
  7. options.filter="Bob"
  8. var fields = ["displayName""name"]; 
  9. navigator.service.contacts.find(fields, onSuccess, onError, options); 

完整的范例

  1. <!DOCTYPE html> 
  2. <html> 
  3. <head> 
  4. <title>Contact Example</title> 
  5.  
  6. <script type="text/javascript" charset="utf-8" src="phonegap.js"></script> 
  7. <script type="text/javascript" charset="utf-8"> 
  8.  
  9.     // PhoneGap加载完毕 
  10.     function onDeviceReady() { 
  11.  
  12.         // 从所有联系人中查找任意名字字段中包含“Bob”的联系人 
  13.         var options = new ContactFindOptions(); 
  14.         options.filter="Bob"
  15.         var fields = ["displayName", "name"]; 
  16.         navigator.service.contacts.find(fields, onSuccess, onError, options); 
  17.     } 
  18.  
  19.     // onSuccess: 获取当前联系人结果集的快照 
  20.     function onSuccess(contacts) { 
  21.         for (var i=0; i<contacts.length; i++) { 
  22.             console.log("Display Name = " + contacts[i].displayName); 
  23.         } 
  24.     } 
  25.  
  26.     // onError: 获得联系人失败 
  27.     function onError() { 
  28.         alert('onError!'); 
  29.     } 
  30.  
  31. </script> 
  32. </head> 
  33. <body> 
  34.  <h1>Example</h1> 
  35.  <p>Find Contact</p> 
  36. </body> 
  37. </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 简单的范例

  1. function onSuccess(contacts) { 
  2.     alert("Save Success"); 
  3.     } 
  4.  
  5. function onError(contactError) { 
  6.     alert("Error = " + contactError.code); 
  7.  
  8. // 建立一个新的联系人对象 
  9. var contact = navigator.service.contacts.create(); 
  10. contact.displayName = "Plumber"
  11. contact.nickname = "Plumber";       //同时指定以支持所有设备 
  12.  
  13. // 填充一些字段 
  14. var name = new ContactName();  
  15. name.givenName = "Jane"
  16. name.familyName = "Doe"
  17. contact.name = name; 
  18.  
  19. // 存储到设备上 
  20. contact.save(onSuccess,onError); 

Remove 简单的范例

  1. function onSuccess(contacts) { 
  2. alert("Save Success"); 
  3. function onError(contactError) { 
  4. alert("Error = " + contactError.code); 
  5. // 建立一个新的联系人对象 
  6. var contact = navigator.service.contacts.create(); 
  7. contact.displayName = "Plumber"
  8. contact.nickname = "Plumber"//同时指定以支持所有设备 
  9. // 填充一些字段 
  10. var name = new ContactName(); 
  11. name.givenName = "Jane"
  12. name.familyName = "Doe"
  13. contact.name = name; 
  14. // 存储到设备上 
  15. contact.save(onSuccess,onError); 

 

完整的范例:

  1. <!DOCTYPE html> 
  2. <html> 
  3. <head> 
  4. <title>Contact Example</title> 
  5.  
  6. <script type="text/javascript" charset="utf-8" src="phonegap.js"></script> 
  7. <script type="text/javascript" charset="utf-8"> 
  8.  
  9.     // 等待加载PhoneGap 
  10.     document.addEventListener("deviceready", onDeviceReady, false); 
  11.      
  12.     // PhoneGap加载完毕 
  13.     function onDeviceReady() { 
  14.      
  15.         // 创建联系人 
  16.         var contact = navigator.service.contacts.create(); 
  17.         contact.displayName = "Plumber"
  18.         contact.nickname = "Plumber";       //同时指定以支持所有设备 
  19.         var name = new ContactName(); 
  20.         name.givenName = "Jane"
  21.         name.familyName = "Doe"
  22.         contact.name = name; 
  23.      
  24.         // 存储联系人 
  25.         contact.save(onSaveSuccess,onSaveError); 
  26.      
  27.         // 克隆联系人 
  28.         var clone = contact.clone(); 
  29.         clone.name.givenName = "John"
  30.         console.log("Original contact name = " + contact.name.givenName); 
  31.         console.log("Cloned contact name = " + clone.name.givenName); 
  32.      
  33.         // 删除联系人 
  34.         contact.remove(onRemoveSuccess,onRemoveError); 
  35.     } 
  36.      
  37.         // onSaveSuccess: 返回当前保存成功的联系人数据的快照 
  38.     function onSaveSuccess(contacts) { 
  39.         alert("Save Success"); 
  40.     } 
  41.      
  42.     // onSaveError: 获取联系人数据失败 
  43.     function onSaveError(contactError) { 
  44.         alert("Error = " + contactError.code); 
  45.     } 
  46.      
  47.     // onRemoveSuccess: 返回当前删除成功的联系人数据的快照 
  48.     function onRemoveSuccess(contacts) { 
  49.         alert("Removal Success"); 
  50.     } 
  51.      
  52.     // onRemoveError: 获取联系人数据失败 
  53.     function onRemoveError(contactError) { 
  54.         alert("Error = " + contactError.code); 
  55.     } 
  56.  
  57. </script> 
  58. </head> 
  59. <body> 
  60.  <h1>Example</h1> 
  61.  <p>Find Contact</p> 
  62. </body> 
  63. </html> 

 

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

简单的范例

  1. // 显示所有联系人的地址信息 
  2. function onSuccess(contacts) { 
  3. for (var i=0; i< contacts.length; i++) { 
  4. for (var j=0; j< contacts[i].addresses.length; j++) { 
  5. alert("Pref: " + contacts[i].addresses[j].pref + "\n" + 
  6. "Type: " + contacts[i].addresses[j].type + "\n" + 
  7. "Formatted: " + contacts[i].addresses[j].formatted + "\n" + 
  8. "Street Address: " + contacts[i].addresses[j].streetAddress + "\n" + 
  9. "Locality: " + contacts[i].addresses[j].locality + "\n" + 
  10. "Region: " + contacts[i].addresses[j].region + "\n" + 
  11. "Postal Code: " + contacts[i].addresses[j].postalCode + "\n" + 
  12. "Country: " + contacts[i].addresses[j].country); 
  13. function onError(contactError) { 
  14. alert('onError!'); 
  15. // 从全部联系人中查找 
  16. var options = new ContactFindOptions(); 
  17. options.filter=""
  18. var filter = ["displayName","addresses"]; 
  19. navigator.contacts.find(filter, onSuccess, onError, options); 

完整的范例

 

  1. <!DOCTYPE html> 
  2. <html> 
  3. <head> 
  4. <title>Contact Example</title> 
  5.  
  6. <script type="text/javascript" charset="utf-8" src="phonegap.js"></script> 
  7. <script type="text/javascript" charset="utf-8"> 
  8.  
  9.     // 等待加载PhoneGap 
  10.     document.addEventListener("deviceready", onDeviceReady, false); 
  11.      
  12.     // PhoneGap加载完毕 
  13.     function onDeviceReady() { 
  14.      
  15.         // 从全部联系人中进行搜索 
  16.         var options = new ContactFindOptions(); 
  17.         options.filter=""
  18.         var filter = ["displayName","addresses"]; 
  19.         navigator.service.contacts.find(filter, onSuccess, onError, options); 
  20.     } 
  21.      
  22.     // onSuccess: 返回当前联系人结果集的快照 
  23.     function onSuccess(contacts) { 
  24.         // 显示所有联系人的地址信息 
  25.         for (var i=0; i<contacts.length; i++) { 
  26.             for (var j=0; j<contacts[i].addresses.length; j++) { 
  27.                 alert("Pref: " + contacts[i].addresses[j].pref + "\n" + 
  28.                     "Type: " + contacts[i].addresses[j].type + "\n" + 
  29.                     "Formatted: " + contacts[i].addresses[j].formatted + "\n" + 
  30.                     "Street Address: "  + contacts[i].addresses[j].streetAddress + "\n" + 
  31.                     "Locality: "  + contacts[i].addresses[j].locality + "\n" + 
  32.                     "Region: "  + contacts[i].addresses[j].region + "\n" + 
  33.                     "Postal Code: "  + contacts[i].addresses[j].postalCode + "\n" + 
  34.                     "Country: "  + contacts[i].addresses[j].country); 
  35.             } 
  36.         } 
  37.     } 
  38.      
  39.     // onError: 获取联系人结果集失败 
  40.     function onError() { 
  41.         alert('onError!'); 
  42.     } 
  43.  
  44. </script> 
  45. </head> 
  46. <body> 
  47.  <h1>Example</h1> 
  48.  <p>Find Contact</p> 
  49. </body> 
  50. </html>

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

简单的范例

  1. // 建立一个新的联系人记录 
  2. var contact = navigator.service.contacts.create(); 
  3. // 存储联系人电话号码到ContactField[]数组 
  4. var phoneNumbers = [3]; 
  5. phoneNumbers[0] = new ContactField('work''212-555-1234'false); 
  6. phoneNumbers[1] = new ContactField('mobile''917-555-5432'true); // ***项 
  7. phoneNumbers[2] = new ContactField('home''203-555-7890'false); 
  8. contact.phoneNumbers = phoneNumbers; 
  9. // 保存联系人 
  10. contact.save(); 

完整的范例

  1. <!DOCTYPE html> 
  2. <html> 
  3. <head> 
  4. <title>Contact Example</title> 
  5.  
  6. <script type="text/javascript" charset="utf-8" src="phonegap.js"></script> 
  7. <script type="text/javascript" charset="utf-8"> 
  8.  
  9.     // 等待加载PhoneGap 
  10.     document.addEventListener("deviceready", onDeviceReady, false); 
  11.      
  12.     // PhoneGap加载完毕 
  13.     function onDeviceReady() { 
  14.      
  15.         // 建立一个新的联系人记录 
  16.         var contact = navigator.service.contacts.create(); 
  17.      
  18.         //存储联系人电话号码到ContactField[]数组 
  19.         var phoneNumbers = [3]; 
  20.         phoneNumbers[0] = new ContactField('work', '212-555-1234', false); 
  21.         phoneNumbers[1] = new ContactField('mobile', '917-555-5432', true);     // ***项 
  22.         phoneNumbers[2] = new ContactField('home', '203-555-7890', false); 
  23.         contact.phoneNumbers = phoneNumbers; 
  24.      
  25.         // 存储联系人 
  26.         contact.save(); 
  27.      
  28.         // 搜索联系人列表,返回符合条件联系人的显示名及电话号码 
  29.         var options = new ContactFindOptions(); 
  30.         options.filter=""
  31.         filter = ["displayName","phoneNumbers"]; 
  32.         navigator.service.contacts.find(filter, onSuccess, onError, options); 
  33.     } 
  34.      
  35.     // onSuccess:返回联系人结果集的快照 
  36.     function onSuccess(contacts) { 
  37.         for (var i=0; i< contacts.length; i++) { 
  38.         // 显示电话号码 
  39.             for (var j=0; j< contacts[i].phoneNumbers.length; j++) { 
  40.                 alert("Type: " + contacts[i].phoneNumbers[j].type + "\n" + 
  41.                     "Value: "  + contacts[i].phoneNumbers[j].value + "\n" + 
  42.                     "Preferred: "  + contacts[i].phoneNumbers[j].pref); 
  43.             } 
  44.         } 
  45.     } 
  46.      
  47.     // onError: 获取联系人结果集失败 
  48.     function onError() { 
  49.         alert('onError!'); 
  50.     } 
  51.  
  52. </script> 
  53. </head> 
  54. <body> 
  55.  <h1>Example</h1> 
  56.  <p>Find Contact</p> 
  57. </body> 
  58. </html> 

 

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

简单的范例

  1. // 成功后的回调函数 
  2. function onSuccess(contacts) { 
  3. for (var i=0; i< ;contacts.length; i++) { 
  4. alert(contacts[i].displayName); 
  5. // 出错后的回调函数 
  6. function onError() { 
  7. alert('onError!'); 
  8. // 指定联系人搜索条件 
  9. var options = new ContactFindOptions(); 
  10. options.filter=""// 空搜索字符串将返回所有联系人 
  11. options.multiple=true// 可返回多条记录 
  12. filter = ["displayName"]; // 仅返回contact.displayName字段 
  13. // 查找联系人 
  14. navigator.service.contacts.find(filter, onSuccess, onError, options); 

完整的范例

  1. <!DOCTYPE html> 
  2. <html> 
  3. <head> 
  4. <title>Contact Example</title> 
  5.  
  6. <script type="text/javascript" charset="utf-8" src="phonegap.js"></script> 
  7. <script type="text/javascript" charset="utf-8"> 
  8.  
  9.     // 等待加载PhoneGap 
  10.     document.addEventListener("deviceready", onDeviceReady, false); 
  11.      
  12.     // PhoneGap加载完毕 
  13.     function onDeviceReady() { 
  14.      
  15.         // 指定联系人搜索条件 
  16.         var options = new ContactFindOptions(); 
  17.         options.filter="";          // 空搜索字符串将返回所有联系人 
  18.         options.multiple=true;      // 可返回多条记录         
  19.         filter = ["displayName"];   // 仅返回contact.displayName字段 
  20.      
  21.         // 查找联系人 
  22.         navigator.service.contacts.find(filter, onSuccess, onError, options); 
  23.     } 
  24.      
  25.     // onSuccess: 返回当前联系人记录集的快照 
  26.     function onSuccess(contacts) { 
  27.         for (var i=0; i< contacts.length; i++) { 
  28.         alert(contacts[i].displayName); 
  29.     } 
  30.     } 
  31.      
  32.     // onError: 获取联系人失败 
  33.     function onError() { 
  34.         alert('onError!'); 
  35.     } 
  36.  
  37. </script> 
  38. </head> 
  39. <body> 
  40.  <h1>Example</h1> 
  41.  <p>Find Contact</p> 
  42. </body> 
  43. </html> 

 

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

简单的范例

  1. function onSuccess(contacts) { 
  2. for (var i=0; i< ;contacts.length;i++) { 
  3. alert('Formatted: ' + contacts[i].name.formatted + '\n' + 
  4. 'Family Name: ' + contacts[i].name.familyName + '\n' + 
  5. 'Given Name: ' + contacts[i].name.givenName + '\n' + 
  6. 'Middle Name: ' + contacts[i].name.middleName + '\n' + 
  7. 'Suffix: ' + contacts[i].name.honorificSuffix + '\n' + 
  8. 'Prefix: ' + contacts[i].name.honorificSuffix); 
  9. function onError() { 
  10. alert('onError!'); 
  11. var options = new ContactFindOptions(); 
  12. options.filter=""
  13. filter = ["displayName","name"]; 
  14. navigator.service.contacts.find(filter, onSuccess, onError, options); 

完整的范例

  1. <!DOCTYPE html>  
  2. <html>  
  3. <head>  
  4. <title>Contact Example</title>  
  5.   
  6. <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>  
  7. <script type="text/javascript" charset="utf-8">  
  8.   
  9.     // 等待加载PhoneGap  
  10.     document.addEventListener("deviceready", onDeviceReady, false);  
  11.       
  12.     // PhoneGap加载完毕  
  13.     function onDeviceReady() {  
  14.         var options = new ContactFindOptions();  
  15.         options.filter="";  
  16.         filter = ["displayName"];  
  17.         navigator.service.contacts.find(filter, onSuccess, onError, options);  
  18.     }  
  19.       
  20.     // onSuccess: 返回联系人结果集的快照  
  21.     function onSuccess(contacts) {  
  22.         for (var i=0; i< contacts.length; i++) {  
  23.             alert("Formatted: " + contacts[i].name.formatted + "\n" +  
  24.                 "Family Name: "  + contacts[i].name.familyName + "\n" +  
  25.                 "Given Name: "  + contacts[i].name.givenName + "\n" +  
  26.                 "Middle Name: "  + contacts[i].name.middleName + "\n" +  
  27.                 "Suffix: "  + contacts[i].name.honorificSuffix + "\n" +  
  28.                 "Prefix: "  + contacts[i].name.honorificPrefix);  
  29.         }  
  30.     }  
  31.       
  32.     // onError: 获取联系人结果集失败  
  33.     function onError() {  
  34.         alert('onError!');  
  35.     }  
  36.   
  37. </script>  
  38. </head>  
  39. <body>  
  40.  <h1>Example</h1>  
  41.  <p>Find Contact</p>  
  42. </body>  
  43. </html>  

 

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

简单的范例

  1. function onSuccess(contacts) { 
  2. for (var i=0; i< contacts.length; i++) { 
  3. for (var j=0; j< contacts[i].organizations.length; j++) { 
  4. alert("Pref: " + contacts[i].organizations[j].pref + "\n" + 
  5. "Type: " + contacts[i].organizations[j].type + "\n" + 
  6. "Name: " + contacts[i].organizations[j].name + "\n" + 
  7. "Department: " + contacts[i].organizations[j].department + "\n" + 
  8. "Title: " + contacts[i].organizations[j].title); 
  9. function onError() { 
  10. alert('onError!'); 
  11. var options = new ContactFindOptions(); 
  12. options.filter=""
  13. filter = ["displayName","organizations"]; 
  14. navigator.service.contacts.find(filter, onSuccess, onError, options); 

完整的范例

  1. <!DOCTYPE html> 
  2. <html> 
  3. <head>   
  4. <title>Contact Example</title> 
  5.  
  6. <script type="text/javascript" charset="utf-8" src="phonegap.js"></script> 
  7. <script type="text/javascript" charset="utf-8"> 
  8.  
  9. // 等待加载PhoneGap 
  10. document.addEventListener("deviceready", onDeviceReady, false); 
  11.  
  12. // PhoneGap加载完毕 
  13. function onDeviceReady() { 
  14.     var options = new ContactFindOptions(); 
  15.     options.filter=""
  16.     filter = ["displayName","organizations"]; 
  17.     navigator.service.contacts.find(filter, onSuccess, onError, options); 
  18.  
  19. // onSuccess: 返回当前联系人结果集的快照 
  20. function onSuccess(contacts) { 
  21.     for (var i=0; i<contacts.length; i++) { 
  22.         for (var j=0; j<contacts[i].organizations.length; j++) { 
  23.             alert("Pref: " + contacts[i].organizations[j].pref + "\n" + 
  24.             "Type: " + contacts[i].organizations[j].type + "\n" + 
  25.             "Name: " + contacts[i].organizations[j].name + "\n" + 
  26.             "Department: "  + contacts[i].organizations[j].department + "\n" + 
  27.             "Title: "  + contacts[i].organizations[j].title); 
  28.         } 
  29.     } 
  30.  
  31. // onError:获取联系人失败 
  32. function onError() { 
  33.     alert('onError!'); 
  34. }    
  35.  
  36. </script> 
  37. </head> 
  38. <body> 
  39.  <h1>Example</h1> 
  40.  <p>Find Contact</p> 
  41. </body> 
  42. </html> 

 

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数组。

简单的范例

  1. function(contacts) { 
  2. // 后续操作 

参数

contacts:查找操作返回的联系人数组。(Contact[]类型)

范例

  1. function contactSuccess(contacts) { 
  2. for (var i=0; i< contacts.length; i++) { 
  3. console.log(“Display Name = ” + contacts[i].displayName; 

contactError

操作联系人出错时的回调函数。

  1. function(error) { 
  2. // 错误处理 

contactFields

contacts.find方法的必填参数,该参数定义了查找操作返回的Contact对象中应该包含哪些字段。

  1. ["name""phoneNumbers""emails"
  2. contactFindOptions 

contats.find方法的可选参数,通过该参数从通讯录数据库中筛选联系人。

  1. filter: ""
  2. multiple: true 

选项

filter:用于查找联系人的搜索字符串。(DOMString类型) (默认值为空字符串)

multiple:决定查找操作是否可以返回多条联系人记录。(布尔类型) (默认值为false)

责任编辑:佚名 来源: PhoneGap中国
相关推荐

2011-12-30 13:47:57

PhoneGap AP视频Contacts

2011-12-20 11:20:46

PhoneGap APCompass

2011-12-19 16:09:32

PhoneGap APCamera

2011-12-22 09:27:36

PhoneGap APGeolocation

2011-12-22 10:33:39

PhoneGap APNotificatio

2011-12-22 10:45:32

PhoneGap APStorage

2011-12-21 21:56:45

PhoneGap APFile

2011-12-20 15:34:55

PhoneGap APConnection

2011-12-19 16:26:39

PhoneGap APCapture

2011-12-22 09:54:40

PhoneGap APMedia

2011-12-19 15:30:25

AccelerometPhoneGap AP

2011-12-20 16:09:57

PhoneGap APDevice

2011-12-20 17:15:52

PhoneGap APEvents

2011-12-30 13:59:38

PhoneGap APDevice视频

2011-12-30 14:09:32

PhoneGap APCompass视频

2011-12-30 14:05:17

PhoneGap APConnection视频

2011-12-30 14:13:05

PhoneGap APCamera视频

2011-12-30 14:16:02

AccelerometPhoneGap AP视频

2011-07-05 17:29:53

PhoneGapevents

2011-09-02 15:12:29

PhoneGapSencha Touc
点赞
收藏

51CTO技术栈公众号