contacts


简介:

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

方法:

对象:

  • create : 创建联系人对象
  • find : 查找联系人对象

回调方法:

getAddressBook


获取通讯录对象

rd.contacts.getAddressBook(type, AddressBookSuccessCallback(), ContactsErrorCallback());
说明:

根据指定通讯录类型获取通讯录对象,获取通讯录对象后可对其进行增、删、改操作。

参数:
  • type:必选 要获取的通讯录类型,可取通讯录类型常量,可获取手机通讯录或SIM卡通讯录。
    • rd.contacts.ADDRESSBOOK_PHONE: 手机通讯录
    • rd.contacts.ADDRESSBOOK_SIM: SIM卡通讯录(Android设备,iOS设备暂不支持sim卡)
  • AddressBookSuccessCallback: 必选 获取通讯录对象成功回调
  • ContactsErrorCallback: 必选 获取通讯录对象失败回调
返回值:

示例:
var type = rd.contacts.ADDRESSBOOK_PHONE;
rd.contacts.getAddressBook(type,AddressBookSuccessCallback(),ContactsErrorCallback());
function AddressBookSuccessCallback(addressbook){

};
function ContactsErrorCallback(error){

};

AddressBookSuccessCallback


获取通讯录操作成功回调函数

参数:
  • addressbook : 通讯录对象
对象:
  • create : 创建联系人
  • find : 在通讯录中查找联系人
返回值:

create


创建联系人

var contact = addressbook.create();
说明:

创建一个系统联系人,并返回联系人对象,可对联系人对象进行操作设置联系人信息,如名称、地址、电话等。

属性:
  • displayName : (String) 联系人显示的名字(仅可读)
  • name : (JSON)联系人名称
    • familyName: (String)联系人的姓
    • givenName: (String)联系人的名
    • middleName: (String)联系人的中间名
    • honorificPrefix: (String)联系人的前缀(如Mr.或Dr.)
    • honorificSuffix: (String)联系人的后缀
  • phoneNumbers : (JSON)数组 联系人的电话
    • type: (String)联系人电话类型,如电话号码中的“mobile”表示移动电话、“main”表示主要联系方式
    • value: (String)电话号码
  • emails : (JSON)数组 联系人的邮箱
    • type: (String)联系人邮箱类型,如电话号码中的“home”表示个人邮箱、“work”表示工作邮箱、空值表示为其他
    • value: (String)邮箱地址
  • addresses : (JSON) 数组 联系人的地址
    • type: (String)联系人地址类型,如“home”表示家庭地址,“work”表示工作地址,值为空或其他字段时表示 显示地址为——其他
    • streetAddress: (String)街道地址
    • locality: (String)城市或地区
    • region: (String)省或地区
    • country: (String)国家
    • postalCode: (String)邮政编码
    • organizations : (JSON) 数组 联系人所属组织信息
      • name: (String) 联系人所属组织名称
      • streetAddress: (String) 联系人所属组织地址
      • title: (String) 联系人在组织中的职位
  • note : (String) 联系人的备注
对象:
  • save:将联系人数据保存到通讯录中,操作成功将调用successCB回调函数,操作失败将通过通过errorCB回调函数返回错误信息。
返回值:
  • 联系人对象
示例:
rd.contacts.getAddressBook(rd.contacts.ADDRESSBOOK_PHONE,function(addressbook)
    {
        var contact = addressbook.create();
        contact.name = {givenName:"名字",familyName:"姓氏"};
        contact.phoneNumbers = [{type:"mobile",value:"88888888"},{type:"main",value:"999999999"},{type:"other",value:"11111111"}];
        contact.nickName = "昵称";
        contact.save(function()
                   {
                        alert('success');
                   },
                   function(e)
                   {
                        alert(e);
                   });
    },
    function (e)
    {
        alert("Get address book failed: " + e.message);
    }
);

find


在通讯录中查找联系人

addressbook.find(FindSuccessCallback(),ContactsErrorCallback(),ContactFindOption);
说明:

在通讯录中按照指定的规则查找联系人(目前仅支持通过姓名关键字查询),查找联系人成功时通过successCB回调返回,查找联系人失败则通过errorCB回调返回。

参数:
  • FindSuccessCallback: 必选 查找联系人操作成功回调
  • ContactsErrorCallback: 必选 查找联系人操作失败回调
  • ContactFindOption: 必选 查找联系人的参数
返回值:
  • 联系人对象
示例:
rd.contacts.getAddressBook(rd.contacts.ADDRESSBOOK_PHONE,function(addressbook){
    var ContactFindOption = {
        name:"111"
    };
    addressbook.find(FindSuccessCallback(),ContactsErrorCallback(),ContactFindOption)
},
 function (e){
    alert("Get address book failed: " + e.message);
 }
);
function FindSuccessCallback(Contact){
    var contact = Contact[0];
    contact.name.givenname = '新名字';
};
function ContactsErrorCallback(){

};

FindSuccessCallback


查找联系人操作成功回调函数

function FindSuccessCallback (Contact) {
    var contact = Contact[0];
}
参数:
  • contact :(Array)必选 数组,查找到的联系人对象
    • displayName : (String) 联系人显示的名字(仅可读)
    • name : (JSON)联系人名称
      • familyName: (String)联系人的姓
      • givenName: (String)联系人的名
      • middleName: (String)联系人的中间名
      • honorificPrefix: (String)联系人的前缀(如Mr.或Dr.)
      • honorificSuffix: (String)联系人的后缀
    • phoneNumbers : (JSON)数组 联系人的电话
      • type: (String)联系人电话类型,如电话号码中的“mobile”表示移动电话、“main”表示主要联系方式
      • value: (String)电话号码
    • emails : (JSON)数组 联系人的邮箱
      • type: (String)联系人邮箱类型,如电话号码中的“home”表示个人邮箱、“work”表示工作邮箱、空值表示为其他
      • value: (String)邮箱地址
    • addresses : (JSON) 数组 联系人的地址
      • type: (String)联系人地址类型,如“home”表示家庭地址,“work”表示工作地址,值为空或其他字段时表示 显示地址为——其他
      • streetAddress: (String)街道地址
      • locality: (String)城市或地区
      • region: (String)省或地区
      • country: (String)国家
      • postalCode: (String)邮政编码
      • organizations : (JSON) 数组 联系人所属组织信息
        • name: (String) 联系人所属组织名称
        • streetAddress: (String) 联系人所属组织地址
        • title: (String) 联系人在组织中的职位
    • note : (String) 联系人的备注
返回值:

ContactsErrorCallback


查找联系人操作失败回调函数

function ContactsErrorCallback (error) {
}
参数:
  • error : (String) 必选
返回值:

ContactFindOption


查找联系人参数

var ContactFindOption = {name:'111'};
属性:
  • name: (String) 姓名关键字

remove


删除联系人

contact.remove(ContactsSuccessCallback(),ContactsErrorCallback());
说明:

删除联系人,操作成功将调用successCB回调函数,操作失败将通过通过errorCB回调函数返回错误信息。

参数:
  • ContactsSuccessCallback :必选 删除联系人操作成功回调
  • ContactsErrorCallback : 必选 删除联系人操作失败回调
返回值:

示例:
rd.contacts.getAddressBook(rd.contacts.ADDRESSBOOK_PHONE,function(addressbook)
    {
       addressbook.find(function(s)
                  {
                      var contact = s[0];
                      contact.remove(ContactsSuccessCallback(),ContactsErrorCallback());
                 },function(e){
                      alert(e);
                 },{name:"Jimmy"});
    },
    function (e)
    {
        alert("Get address book failed: " + e.message);
    }
);
function ContactsSuccessCallback(){
};
function ContactsErrorCallback(){
};

ContactsSuccessCallback


联系人操作成功回调函数

function ContactsSuccessCallback () {
}
参数:

返回值:

ContactsErrorCallback


查找联系人操作失败回调函数

function ContactsErrorCallback (error) {
}
参数:
  • error : (String) 必选
返回值: