Contacts管理系统通讯录

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 );
  } );