Contacts模块管理系统通讯录,用于可对系统通讯录进行增、删、改、查等操作。通过plus.contacts获取系统通讯录管理
ADDRESSBOOK_PHONE:手机通讯录
plus.contacts.ADDRESSBOOK_PHONE;
说明:
Number 类型
通讯录类型常量,数值类型,固定值为0,用于获取系统的联系人信息。
ADDRESSBOOK_SIM:SIM卡通讯录
plus.contacts.ADDRESSBOOK_SIM;
说明:
Number 类型
通讯录类型常量,数值类型,固定值为1,用于获取SIM卡上的联系人信息。
getAddressBook:获取通讯录对象
plus.contacts.getAddressBook( type, succesCB, errorCB );
说明:
根据指定通讯录类型获取通讯录对象,获取通讯录对象后可对其进行增、删、改操作。
参数:
type: ( Number ) 必选 要获取的通讯录类型
可取通讯录类型常量,可获取手机通讯录或SIM卡通讯录。
successCB: ( AddressBookSuccessCallback ) 必选 获取通讯录对象成功回调
errorCB: ( ContactsErrorCallback ) 可选 获取通讯录对象失败回调
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 );
AddressBook:通讯录对象
说明:通讯录管理对象,可对系统通讯录进行联系人的增、删、改、查操作。
方法:
create: 创建联系人 Contact addressbook.create();创建一个系统联系人,并返回联系人对象,可对联系人对象进行操作设
置联系人信息,如名称、地址、电话等。// 监听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 );
find: 在通讯录中查找联系人
addressbook.find( contactFields, successCB, errorCB, findOptions ); 说明: 在通讯录中安装指定的规则查找联系人,contactFields可设定查找返回的联系人中包含的字段值,查找联系人成功时通过 successCB回调返回,查找联系人失败则通过errorCB回调返回。 参数: contactFields: ( String[] ) 必选 查找返回联系人中需要包含的信息 如“name.familyName”指定获取联系人名称中的姓;对于ContactField类型的值则可指定类型值, 如“phoneNumbers.mobile”指定获取联系人的手机号码。 successCB: ( FindSuccessCallback ) 必选 查找联系人操作成功回调 errorCB: ( ContactsErrorCallback ) 可选 查找联系人操作失败回调 findOptions: ( ContactFindOption ) 可选 查找联系人的参数 // 监听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); }); }
Contact:联系人对象
联系人对象,包括联系人的各种信息,如名称、电话号码、地址等。也包括新增、删除联系人的操作方法。
属性
id: 联系人的id
String 类型 只读属性 可选属性 联系人id由系统分配维护,从系统获取联系人时自动赋值,再次查询时可使用此id值进行检索。 注意:此值为只读属性,改写此 值可能会导致无法预期的错误。
displayName: 联系人显示的名字
String 类型 可选属性 联系人显示的名字通常由其姓和名组合而成。
- name: 联系人的名称()
- nickname: 联系人的昵称
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: 数组,联系人的组名
ContactField 类型 可选属性 如果联系人中未保存组名信息,则返回空数组。
urls: 数组,联系人的网址
ContactField 类型 可选属性 如果联系人中未保存网址信息,则返回空数组。
方法
clone: 克隆联系人
克隆联系人,创建出一个新的联系人对象。 var newcnt = contact.clone();
remove: 删除联系人
contact.remove( successCB, errorCB ); 参数: successCB: ( ContactsSuccessCallback ) 必选 删除联系人操作成功回调 errorCB: ( ContactsErrorCallback ) 可选 删除联系人操作失败回调 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: 保存联系人
contact.save( successCB, errorCB );将联系人数据保存到通讯录中,操作成功将通过successCB回调函数返回保存结 果,操作失败将通过通过errorCB回调函数返回错误信息。 参数: successCB: ( ContactsSuccessCallback ) 必选 添加联系人操作成功回调 errorCB: ( ContactsErrorCallback ) 可选 添加联系人操作失败回调 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 ); } );