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 : 无