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

samwong

浏览: 282274 次
性别:
来自: 北京

最近访客更多访客>>

wenjinshan

ShangJinDeLiuMang

dotfeng

kingrom

博主相关

博客

微博

相册

留言

关于我

文章分类

社区版块

存档分类

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

“

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

方法：

contacts.create
contacts.find

参数：

contactFields
contactSuccess
contactError
contactFindOptions

对象：

Contact
ContactName
ContactField
ContactAddress
ContactOrganization
ContactFindOptions
ContactError

contacts.create

返回一个新的Contact对象。

说明：

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

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

支持的平台：

Android
BlackBerry WebWorks (OS 5.0或更高版本)
iOS

简单的范例：

完整的范例：

contacts.find

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

说明：

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

简单的范例：

完整的范例：

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 简单的范例：
Clone 简单的范例：

Remove 简单的范例：

完整的范例：

<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">
 
	// 等待加载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;"><!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
	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;"><!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
	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

简单的范例：

完整的范例：

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;"><!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
	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;"><!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
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数组。

简单的范例：

参数：

contacts：查找操作返回的联系人数组。（Contact[]类型）

范例：

contactError

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

contactFields

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

contactFindOptions

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

选项：

filter：用于查找联系人的搜索字符串。(DOMString类型) (默认值为空字符串)
multiple：决定查找操作是否可以返回多条联系人记录。(布尔类型) (默认值为false)

“

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

方法：

contacts.create
contacts.find

参数：

contactFields
contactSuccess
contactError
contactFindOptions

对象：

Contact
ContactName
ContactField
ContactAddress
ContactOrganization
ContactFindOptions
ContactError

contacts.create

返回一个新的Contact对象。

说明：

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

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

支持的平台：

Android
BlackBerry WebWorks (OS 5.0或更高版本)
iOS

简单的范例：

完整的范例：

contacts.find

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

说明：

contacts.find是一个查询设备通讯录数据库并返回Contact对象数组的同步函数。返回的对象会被传递给contactSuccess回调函数的contactSuccess参数。

属性：

contactFields：Contact字段，用作搜索限定符。在返回的Contact对象中只有这些字段有值。（DOMString[]类型）[必填]
contactSuccess：通讯录获取成功时调用的回调函数，将从通讯录数据库获取的联系人作为参数。[必填]
contactError：错误回调函数，当发生错误的时候被调用。[可选]
contactFindOptions：用于过滤通讯录的搜索选项。[可选]

支持的平台：

Android
BlackBerry WebWorks (OS 5.0或更高版本)
iOS

简单的范例：

完整的范例：

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 简单的范例：
Clone 简单的范例：

Remove 简单的范例：

完整的范例：

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;"><!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
	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。（布尔类型）

详述：

支持的平台：

Android
BlackBerry WebWorks (OS 5.0或更高版本)
iOS

简单的范例：

完整的范例：

<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">
 
	// 等待加载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

简单的范例：

完整的范例：

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;"><!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
	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;"><!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
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数组。

简单的范例：

参数：

contacts：查找操作返回的联系人数组。（Contact[]类型）

范例：

contactError

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

contactFields

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

contactFindOptions

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

选项：

filter：用于查找联系人的搜索字符串。(DOMString类型) (默认值为空字符串)
multiple：决定查找操作是否可以返回多条联系人记录。(布尔类型) (默认值为false)

分享到：

PhoneGap API帮助文档翻译—Events（事件） ... | PhoneGap API帮助文档翻译—Connection（连 ...

2012-02-01 23:06
浏览 621
评论(0)
查看更多

发表评论

您还没有登录,请您登录后再发表评论

最近访客更多访客>>

博主相关

文章分类

社区版块

存档分类

最新评论

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

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

评论

发表评论

相关推荐

最近访客 更多访客>>

博主相关

文章分类

社区版块

存档分类

最新评论

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

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

评论

发表评论

相关推荐

最近访客更多访客>>