现在的位置: 首页 > 综合 > 正文

PhoneGap API中文帮助文档——Contacts（通讯录)

2013年01月31日 ⁄ 综合 ⁄ 共 4994字 ⁄ 字号 小 中 大 ⁄ 评论关闭

contacts对象提供对设备通讯录数据库的访问。
方法：

  • contacts.create
  • contacts.find


参数：

  • contactFields
  • contactSuccess
  • contactError
  • contactFindOptions


对象：

  • Contact
  • ContactName
  • ContactField
  • ContactAddress
  • ContactOrganization
  • ContactFindOptions
  • ContactError

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.     <span style="font-size:13px;">var myContact = navigator.service.contacts.create({"displayName": "Test User"});</span>  

复制代码

完整的范例：

  1.     <span style="font-size:13px;"><!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></span>  

复制代码


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. <span style="font-size:13px;">function onSuccess(contacts) {  
  2.     alert('Found ' + contacts.length + ' contacts.');  
  3. }  
  4.   
  5. function onError() {  
  6.     alert('onError!');  
  7. }  
  8.   
  9. // 从所有联系人中查找任意名字字段中包含“Bob”的联系人  
  10. var options = new ContactFindOptions();  
  11. options.filter="Bob";  
  12. var fields = ["displayName", "name"];  
  13. 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">  

复制代码

完整的范例：

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

复制代码

Clone 简单的范例：

  1. <span style="font-size:13px;">// 克隆联系人对象  
返回
【上篇】
【下篇】

作者:

抱歉!评论已关闭.

返回首页

Copyright © 2013-2018 学步园  保留所有权利.
软文销售 QQ客服：2265327166 点击这里给我发消息（其他合作也可洽谈）
必威体育
必威电竞