HTML5+规范：contacts(管理系统通讯录)
Contacts模块管理系统通讯录，用于可对系统通讯录进行增、删、改、查等操作。通过plus.contacts获取系统通讯录管理对象。
1、常量
1.1、ADDRESSBOOK_PHONE: 手机通讯录，通讯录类型常量，数值类型，固定值为0，用于获取系统的联系人信息。
1.2、ADDRESSBOOK_SIM: SIM卡通讯录，通讯录类型常量，数值类型，固定值为1，用于获取SIM卡上的联系人信息。平台支持：Android - 2.2+ (不支持): 暂未实现SIM卡联系人的访问，iOS - 4.3+ (不支持): 不支持SIM卡联系人的访问
2、方法
getAddressBook: 获取通讯录对象
void plus.contacts.getAddressBook( type, succesCB, errorCB );
说明：根据指定通讯录类型获取通讯录对象，获取通讯录对象后可对其进行增、删、改操作。
参数：
type: ( Number ) 必选 要获取的通讯录类型，可取通讯录类型常量，可获取手机通讯录或SIM卡通讯录。
successCB: ( AddressBookSuccessCallback ) 必选 获取通讯录对象成功回调
errorCB: ( ContactsErrorCallback ) 可选 获取通讯录对象失败回调
返回值：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<span style="font-family: FangSong_GB2312; background-color: rgb(255, 255, 255);">></span>
3、对象
3.1、AddressBook: 通讯录对象
interface AddressBook {
function Contact create();
function void find( contactFields, successCB, errorCB, findOptions );
}
说明：通讯录管理对象，可对系统通讯录进行联系人的增、删、改、查操作。
方法：
（1）、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>
（2）、find: 在通讯录中查找联系人
void addressbook.find( contactFields, successCB, errorCB, findOptions );
说明：在通讯录中安装指定的规则查找联系人，contactFields可设定查找返回的联系人中包含的字段值，查找联系人成功时通过successCB回调返回，查找联系人失败则通过errorCB回调返回。
参数：
contactFields: ( String[] ) 必选 查找返回联系人中需要包含的信息，可取Contact对象的属性名称，若指定为null或""或空数组则包含所有联系人信息。可通过“.”来分割子项，如“name.familyName”指定获取联系人名称中的姓；对于ContactField类型的值则可指定类型值，如“phoneNumbers.mobile”指定获取联系人的手机号码。
successCB: ( FindSuccessCallback ) 必选 查找联系人操作成功回调
errorCB: ( ContactsErrorCallback ) 可选 查找联系人操作失败回调
findOptions: ( ContactFindOption ) 可选 查找联系人的参数
返回值：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>
3.2、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 );
}
说明：联系人对象，包括联系人的各种信息，如名称、电话号码、地址等。也包括新增、删除联系人的操作方法。
（1）、属性
id: 联系人的id，联系人id由系统分配维护，从系统获取联系人时自动赋值，再次查询时可使用此id值进行检索。 注意：此值为只读属性，改写此值可能会导致无法预期的错误。
displayName: 联系人显示的名字，联系人显示的名字通常由其姓和名组合而成。
name: 联系人的名称
nickname: 联系人的昵称
phoneNumbers: 数组，联系人的电话，如果联系人中未保存电话信息，则返回空数组。
emails: 数组，联系人的邮箱
addresses: 数组，联系人的地址
ims: 数组，联系人的即时通讯地址
organizations: 数组，联系人所属组织信息
birthday: 联系人的生日
note: 联系人的备注
photos: 数组，联系人的头像
categories: 数组，联系人的组名
urls: 数组，联系人的网址
（2）、方法
1）、clone: 克隆联系人
Contact contact.clone();
说明：克隆联系人，创建出一个新的联系人对象。
返回值：Contact : 克隆出的Contact对象
示例：
var newcnt = contact.clone();
2）、remove: 删除联系人
void contact.remove( successCB, errorCB );
参数：
successCB: ( ContactsSuccessCallback ) 必选 删除联系人操作成功回调
errorCB: ( ContactsErrorCallback ) 可选 删除联系人操作失败回调
返回值：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} );
} );
3）、save: 保存联系人
void contact.save( successCB, errorCB );
说明：将联系人数据保存到通讯录中，操作成功将通过successCB回调函数返回保存结果，操作失败将通过通过errorCB回调函数返回错误信息。
参数：
successCB: ( ContactsSuccessCallback ) 必选 添加联系人操作成功回调
errorCB: ( ContactsErrorCallback ) 可选 添加联系人操作失败回调
返回值：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 );
} );
3.3、ContactField: JSON对象，联系人域数据对象
JSON对象，联系人域数据对象
interface ContactField {
attribute String type;
attribute String value;
attribute Boolean preferred;
}
说明：联系人域数据对象，保存联系人特定域信息。
属性：
type: (String 类型 )联系人域类型，如电话号码中的“mobile”、“home”、“company”
value: (String 类型 )联系人域值
preferred: (Boolean 类型 )是否为首选项
3.4、ContactName: JSON对象，联系人名称对象
JSON对象，联系人名称对象
interface ContactName {
attribute String formatted;
attribute String familyName;
attribute String givenName;
attribute String middleName;
attribute String honorificPrefix;
attribute String honorificSuffix;
}
说明：联系人名称对象，保存联系人名称信息，如姓、名等。
属性：
formatted: (String 类型 )联系人的完整名称，由其它字段组合生成
familyName: (String 类型 )联系人的姓
givenName: (String 类型 )联系人的名
middleName: (String 类型 )联系人的中间名
honorificPrefix: (String 类型 )联系人的前缀（如Mr.或Dr.）
honorificSuffix: (String 类型 )联系人的后缀
3.5、ContactAddress: JSON对象，联系人地址对象
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;
}
说明：联系人地址对象，保存联系人地址信息，如国家、省份、城市等。
属性：
type: (String 类型 )联系人地址类型，如“home”表示家庭地址、“company”表示单位地址
formatted: (String 类型 )完整地址，由其它字段组合而成
streetAddress: (String 类型 )完整的街道地址
locality: (String 类型 )城市或地区
region: (String 类型 )省或地区
country: (String 类型 )国家
postalCode: (String 类型 )邮政编码
preferred: (Boolean 类型 )是否为首选项
3.6、ContactOrganization: JSON对象，联系人所属组织信息
JSON对象，联系人所属组织信息
interface ContactOrganization {
attribute String type;
attribute String name;
attribute String department;
attribute String title;
attribute Boolean preferred;
}
属性：
type: (String 类型 )联系人所属组织类型，如"company"
name: (String 类型 ) 联系人所属组织名称
department: (String 类型 )联系人所属组织部门
title: (String 类型 )联系人在组织中的职位
preferred: (Boolean 类型 )是否为首选项
3.7、ContactFindOption: JSON对象，查找联系人参数
JSON对象，查找联系人参数
interface ContactFindOption {
attribute ContactFindFilte[] filter;
attribute Boolean multiple;
}
属性：
filter: (ContactFindFilter 类型 )数组，查找时的过滤器，可设置为空，表示不过滤。
multiple: (Boolean 类型 )是否查找多个联系人，默认值为true
3.8、ContactFindFilter: JSON对象，联系人查找过滤器
JSON对象，联系人查找过滤器
interface ContactFindFilter {
attribute String logic;
attribute String field;
attribute String value;
}
属性：
logic: (String 类型 )区配的逻辑，可取“and”、“or”、“not”，默认值为“and”。
field: (String 类型 )区配的联系人域，可取联系人的属性名称
value: (String 类型 )区配的联系人值，可使用区配符号“?”和“*”
示例：
// 区配所有包括姓或名中包括“王”的联系人
[{logic:"or",field:"displayNam",value:"*王*"},{logic:"or",field:"nickname",value:"*王*"}]
4、回调方法
4.1、AddressBookSuccessCallback: 获取通讯录操作成功回调函数
void onSuccess( addressbook ){
// Code AddressBook here
}
参数：addressbook: ( AddressBook ) 必选 获取到的通讯录对象
返回值：void : 无
4.2、FindSuccessCallback: 查找联系人操作成功回调函数
void onSuccess( contacts ){
// Find contact success.
}
参数：contacts: ( Contact ) 必选 数组，查找到的联系人对象
返回值：void : 无
4.3、ContactsSuccessCallback: 联系人操作成功回调函数
void onSuccess(){
// Operate success
}
返回值：void : 无
4.4、ContactsErrorCallback: 联系人操作失败回调
void onError( error ){
// Handle the error
}
参数：error: ( DOMException ) 必选 联系人操作的错误信息
返回值：void : 无