Contacts Document

contacts

Contacts模块管理系统通讯录,用于可对系统通讯录进行增、删、改、查等操作。通过plus.contacts获取系统通讯录管理对象。

常量:

方法:

对象:

回调方法:

权限:

permissions

"Contacts": {
	"description": "访问系统联系人"
}
			

ADDRESSBOOK_PHONE

手机通讯录

plus.contacts.ADDRESSBOOK_PHONE;
				

说明:

Number 类型

通讯录类型常量,数值类型,固定值为0,用于获取系统的联系人信息。

ADDRESSBOOK_SIM

SIM卡通讯录

plus.contacts.ADDRESSBOOK_SIM;
				

说明:

Number 类型

通讯录类型常量,数值类型,固定值为1,用于获取SIM卡上的联系人信息。

平台支持

getAddressBook

获取通讯录对象

void plus.contacts.getAddressBook( type, succesCB, errorCB );
				

说明:

根据指定通讯录类型获取通讯录对象,获取通讯录对象后可对其进行增、删、改操作。

参数:

返回值:

void : 无

示例:

<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8"/>
	<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
	<title>Contacts Example</title>
	<script type="text/javascript">
// 监听plusready事件  
document.addEventListener( "plusready", function(){
	// 扩展API加载完毕,现在可以正常调用扩展API
	plus.contacts.getAddressBook( plus.contacts.ADDRESSBOOK_PHONE, function( addressbook ) {
		// 可通过addressbook进行通讯录操作
		alert( "Get address book success!" );
	}, function ( e ) {
		alert( "Get address book failed: " + e.message );
	} );
}, false );
	</script>
	</head>
	<body>
	</body>
</html>
				

AddressBook

通讯录对象

interface AddressBook {
	function Contact create();
	function void find( contactFields, successCB, errorCB, findOptions );
}
				

说明:

通讯录管理对象,可对系统通讯录进行联系人的增、删、改、查操作。

方法:

create

创建联系人

	Contact addressbook.create();
						

说明:

创建一个系统联系人,并返回联系人对象,可对联系人对象进行操作设置联系人信息,如名称、地址、电话等。

参数:

返回值:

Contact : 联系人对象

示例:

<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8"/>
	<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
	<title>Contacts Example</title>
	<script type="text/javascript">
// 监听plusready事件  
document.addEventListener( "plusready", function(){
	// 扩展API加载完毕,现在可以正常调用扩展API
	plus.contacts.getAddressBook( plus.contacts.ADDRESSBOOK_PHONE, function( addressbook ) {
		// 向通讯录中添加联系人
		var contact = addressbook.create();
		contact.firstname = "王安";
		contact.phoneNumbers = [{type:"手机",value"88888888",preferred:true}];
		contact.save();
	}, function ( e ) {
		alert( "Get address book failed: " + e.message );
	} );
}, false );
	</script>
	</head>
	<body>
	</body>
</html>
						

find

在通讯录中查找联系人

void addressbook.find( contactFields, successCB, errorCB, findOptions );
						

说明:

在通讯录中安装指定的规则查找联系人,contactFields可设定查找返回的联系人中包含的字段值,查找联系人成功时通过successCB回调返回,查找联系人失败则通过errorCB回调返回。

参数:

返回值:

void : 无

Contact

联系人对象

interface Contact {
	attribute DOMString displayName;
	attribute ContactName name;
	attribute DOMString nickname;
	attribute ContackField[] phoneNumbers;
	attribute ContactField[] emails;
	attribute ContactAddress[] addresses;
	attribute ContactField[] ims;
	attribute ContactOriganization[] organizations;
	attribute Date birthday;
	attribute DOMString note;
	attribute ContactField[] photos;
	attribute ContactField[] categories;
	attribute ContactField[] urls;
	function Contact clone();
	function void remove( successCB, errorCB );
	function void save( successCB, errorCB );
}
				

说明:

联系人对象,包括联系人的各种信息,如名称、电话号码、地址等。也包括新增、删除联系人的操作方法。

属性:

方法:

displayName

联系人显示的名字

说明:

DOMString 类型 可选属性

联系人显示的名字通常有其姓和名组合而成。

name

联系人的名称

说明:

ContactName 类型

nickname

联系人的昵称

说明:

DOMString 类型 可选属性

phoneNumbers

数组,联系人的电话

说明:

ContactField 类型 可选属性

emails

数组,联系人的邮箱

说明:

ContactField 类型 可选属性

addresses

数组,联系人的地址

说明:

ContactAddress 类型 可选属性

ims

数组,联系人的即时通讯地址

说明:

ContactField 类型 可选属性

organizations

数组,联系人所属组织信息

说明:

ContactOrganization 类型 可选属性

birthday

联系人的生日

说明:

Date 类型 可选属性

note

联系人的备注

说明:

DOMString 类型 可选属性

photos

数组,联系人的头像

说明:

ContactField 类型 可选属性

其值为头像图片url地址或图片数据: url地址:仅支持本地图片地址,可以是绝对路径或相对路径,如“_doc/a.png”; 图片数据:必须符合Data URI scheme(RFC2397)格式的数据,如“image/png;base64,XXXX”,其中XXXX为base64编码的图片数据。在获取联系人时默认返回此类型的数据。

categories

数组,联系人的组名

说明:

ContactOrganization 类型 可选属性

urls

数组,联系人的网址

说明:

ContactOrganization 类型 可选属性

clone

克隆联系人

Contact contact.clone();
						

说明:

克隆联系人,创建出一个新的联系人对象。

参数:

返回值:

Contact : 克隆出的Contact对象

示例:

var newcnt = contact.clone();
						

remove

删除联系人

void contact.remove( successCB, errorCB );
						

参数:

返回值:

void : 无

示例:

plus.contacts.getAddressBook( plus.contacts.ADDRESSBOOK_PHONE, function( addressbook ) {
	// 可通过addressbook进行通讯录操作
	var contact = addressbook.find( null, function ( contacts ) {
		if ( contacts.length> 0 ) {
			var dc = contacts[0];
			dc.remove( function () {
				alert( "Remove " + dc.firstName + " " + dc.lastName + " success!" );
			}
		}, function ( e ) {
			alert( "Find contact error: " e.message );
	}, {filter:[{logic:"or",field:"phoneNumbers",value:"88888888"}],multi:false} );
} );
						

save

保存联系人

void contact.save( successCB, errorCB );
						

说明:

将联系人数据保存到通讯录中,操作成功将通过successCB回调函数返回保存结果,操作失败将通过通过errorCB回调函数返回错误信息。

参数:

返回值:

void : 无

示例:

plus.contacts.getAddressBook( plus.contacts.ADDRESSBOOK_PHONE, function( addressbook ) {
	// 可通过addressbook进行通讯录操作
	var contact = addressbook.create();
		contact.firstname = "王安";
		contact.phoneNumbers = [{type:"手机",value"88888888",preferred:true}];
		contact.save( function () {
			alert( "保存联系人成功" );
		}, function ( e ) {
			alert( "保存联系人失败:" + e.message );
		} );
	}, function ( e ) {
		alert( "Get address book failed: " + e.message );
} );
						

ContactField

JSON对象,联系人域数据对象

interface ContactField {
	attribute DOMString type;
	attribute DOMString value;
	attribute Boolean preferred;
}
				

说明:

联系人域数据对象,保存联系人特定域信息。

属性:

ContactName

JSON对象,联系人名称对象

interface ContactName {
	attribute DOMString formatted;
	attribute DOMString familyName;
	attribute DOMString givenName;
	attribute DOMString middleName;
	attribute DOMString honorificPrefix;
	attribute DOMString honorificSuffix;
}
				

说明:

联系人名称对象,保存联系人名称信息,如姓、名等。

属性:

ContactAddress

JSON对象,联系人地址对象

interface ContactAddress {
	attribute DOMString type;
	attribute DOMString formatted;
	attribute DOMString streetAddress;
	attribute DOMString locality;
	attribute DOMString region;
	attribute DOMString country;
	attribute DOMString postalCode;
	attribute Boolean preferred;
}
				

说明:

联系人地址对象,保存联系人地址信息,如国家、省份、城市等。

属性:

ContactOrganization

JSON对象,联系人所属组织信息

interface ContactOrganization {
	attribute DOMString type;
	attribute DOMString name;
	attribute DOMString department;
	attribute DOMString title;
	attribute Boolean preferred;
}
				

属性:

ContactFindOption

JSON对象,查找联系人参数

interface ContactFindOption {
	attribute ContactFindFilte[] filter;
	attribute Boolean multiple;
}
				

属性:

ContactFindFilter

JSON对象,联系人查找过滤器

interface ContactFindFilter {
	attribute DOMString logic;
	attribute DOMString field;
	attribute DOMString value;
}
				

属性:

AddressBookSuccessCallback

获取通讯录操作成功回调函数

void onSuccess( addressbook ){
	// Code AddressBook here
}
				

参数:

返回值:

void : 无

FindSuccessCallback

查找联系人操作成功回调函数

void onSuccess( contacts ){
	// Find contact success.
}
				

参数:

返回值:

void : 无

ContactsSuccessCallback

联系人操作成功回调函数

void onSuccess(){
	// Operate success
}
				

参数:

返回值:

void : 无

ContactsErrorCallback

联系人操作失败回调

void onError( error ){
	// Handle the error
}
				

参数:

返回值:

void : 无