API Reference

Plugins

Native.js


contacts

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

常量:

方法:

对象:

回调方法:

模块:

5+功能模块(permissions)


{
// ...
"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.name = {givenName:"王安"};
		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 : 无

示例:


<!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(){
}, false );
function find(){
	plus.contacts.getAddressBook(plus.contacts.ADDRESSBOOK_PHONE, function (addressbook) {
		addressbook.find(["displayName","phoneNumbers"],function(contacts){
			alert(contacts.length);
		}, function () {
			alert("error");
		},{multiple:true});
	},function(e){
		alert("Get address book failed: " + e.message);
	});
}

	</script>
	</head>
	<body>
		<button onclick="find()">Find</button>
	</body>
</html>
						

Contact

联系人对象


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

说明:

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

属性:

方法:

id

联系人的id

说明:

String 类型 只读属性 可选属性

联系人id由系统分配维护,从系统获取联系人时自动赋值,再次查询时可使用此id值进行检索。 注意:此值为只读属性,改写此值可能会导致无法预期的错误。

displayName

联系人显示的名字

说明:

String 类型 可选属性

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

平台支持:

name

联系人的名称

说明:

ContactName 类型

nickname

联系人的昵称

说明:

String 类型 可选属性

phoneNumbers

数组,联系人的电话

说明:

ContactField 类型 可选属性

如果联系人中未保存电话信息,则返回空数组。

emails

数组,联系人的邮箱

说明:

ContactField 类型 可选属性

如果联系人中未保存邮箱信息,则返回空数组。

addresses

数组,联系人的地址

说明:

ContactAddress 类型 可选属性

如果联系人中未保存地址信息,则返回空数组。

ims

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

说明:

ContactField 类型 可选属性

如果联系人中未保存即时通讯地址信息,则返回空数组。

organizations

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

说明:

ContactOrganization 类型 可选属性

如果联系人中未保存所属组织信息,则返回空数组。

birthday

联系人的生日

说明:

Date 类型 可选属性

note

联系人的备注

说明:

String 类型 可选属性

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.displayName+" 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.name = {givenName:"王安"};
		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 String type;
	attribute String value;
	attribute Boolean preferred;
}
				

说明:

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

属性:

ContactName

JSON对象,联系人名称对象


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

说明:

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

属性:

ContactAddress

JSON对象,联系人地址对象


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

说明:

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

属性:

ContactOrganization

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


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

属性:

ContactFindOption

JSON对象,查找联系人参数


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

属性:

ContactFindFilter

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


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

属性:

示例:


// 区配所有包括姓或名中包括“王”的联系人
[{logic:"or",field:"displayNam",value:"*王*"},{logic:"or",field:"nickname",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 : 无