uexContact查看3.0文档

1、简介

系统联系人插件

1.1、说明

打开,添加,删除,查找,修改联系人等功能.

本文的目的是为了开发能够更好更快地将API集成到自己的项目中,在使用前最好先使用好我们提供的demo并对照文档运行看看效果。
这里可以【参考教程】下载AppCan IDE为开发者工具开发,然后集成到自己的项目上。

1.2、UI展示

1.3、开源源码

插件测试用例与源码下载:点击插件中心至插件详情页 (插件测试用例与插件源码已经提供)

1.4、平台版本支持

本插件的所有API默认支持Android4.0+iOS7.0+操作系统. 有特殊版本要求的API会在文档中额外说明.

1.5、接口有效性

本插件所有API默认在插件版本4.0.0+可用.
在后续版本中新添加的接口会在文档中额外说明.

2、API概览

2.1、方法
open //打开联系人

uexContact.open(callbackFunction)

说明:

打开联系人应用,每次只能选择一个联系人.用户选择联系人后会执行回调方法callbackFunction, 将选中的联系人的姓名,电话,邮件返回.

参数:

参数名称 参数类型 是否必选 说明
callbackFunction Function 回调方法

回调参数:

var callbackFunction=function(error,data){}
参数名称 参数类型 说明
error Number 0表示成功,-1为取消,其他表示失败
data Object 成功时返回的数据,形式见下:
var data = {
    name://String,联系人姓名
    num://Array,联系人电话号码数组
    email://String,邮箱
    company://String,公司,仅iOS
    address://json对象,联系人地址,仅iOS
    note://String,备忘录,仅iOS
    title://String,联系人简介,仅iOS
    contactId://String,联系人id,仅iOS
    url://String,联系人链接url,仅iOS
};

示例:

uexContact.open(function(error,data){
      if(!error){
          alert('callback:' + JSON.stringify(data));
      }  
});
multiOpen //打开联系人选择界面

uexContact.multiOpen(callbackFunction)

说明:

打开联系人选择界面,该界面中的数据是当前设备上所有联系人的信息,支持多选.用户选择完成后执行回调方法callbackFunction.

参数:

参数名称 参数类型 是否必选 说明
callbackFunction Function 回调方法

回调参数:

var callbackFunction=function(error,data){}
参数名称 参数类型 说明
error Number 0表示成功,-1为取消,其他表示失败
data Array JSON数组类型,格式,形式见下:
var data = [{
    name://String,联系人姓名
    num://Array,联系人电话号码数组
    email://String,邮箱
    company://String,公司,仅iOS
    address://json对象,联系人地址,仅iOS
    note://String,备忘录,仅iOS
    title://String,联系人简介,仅iOS
    contactId://String,联系人id,仅iOS
    url://String,联系人链接url,仅iOS
}];

示例:

uexContact.multiOpen(function(error,data) {
      if(!error){
        alert('data:' + JSON.stringify(data));
    }
});
addItem //添加联系人

uexContact.addItem(name,num,email,option, callbackFunction)

说明:

添加联系人, 方法执行结束后回调callbackFunction

参数:

参数名称 参数类型 是否必选 说明
name String 名称
num String 电话号码
email String 邮件
option Object 添加联系人配置,json格式字符串,如下:
callbackFunction Function 回调函数
var option = {
    isNeedAlertDialog:
}

各字段含义如下:

字段名称 类型 是否必选 说明
isNeedAlertDialog Boolean 添加过程中是否需要弹出"确认添加"提示框,默认为true,弹出提示框

回调参数:

var callbackFunction=function(error){}
参数名称 参数类型 说明
error Number 0表示成功,-1为取消,其他表示失败

示例:

var option = {
    isNeedAlertDialog:false
}
uexContact.addItem("张三","13436827900","widgetone@3g2win.com",option,function(error){
      if(!error){
      //添加成功
      }
});
deleteWithId //删除联系人

uexContact.deleteWithId(option, callbackFunction)

说明:

通过联系人id精确删除对应联系人,方法执行结束后回调callbackFunction 由于手机端可能存在同名称的联系人导致原有deleteItem接口无法完全满足删除问题.

参数:

参数名称 参数类型 是否必选 说明
option Object 要删除的联系人参数,json格式字符串,如下:
callbackFunction Function 回调函数
var option = {
    contactId://通过查询获取到的联系人id
}

各字段含义如下:

字段名称 类型 是否必选 说明
contactId String 所删除的联系人的id(可通过search获取联系人id)

回调参数

var callbackFunction=function(error){}
参数名称 参数类型 说明
error Number 表示操作是否成功,0表示成功,其他表示失败.

示例:

var option =  {
    contactId:'405'
}
uexContact.deleteWithId(option,function(error){

});
deleteItem //删除联系人

uexContact.deleteItem(name, callbackFunction)

说明:

删除联系人, 方法执行结束后回调callbackFunction

参数:

参数名称 参数类型 是否必选 说明
name String 名称
callbackFunction 函数 回调函数

回调参数

var callbackFunction=function(error){}
参数名称 参数类型 说明
error Number 表示操作是否成功,0表示成功,其他表示失败.

示例:

uexContact.deleteItem("张三",function(error){});
search //查询联系人

uexContact.search(option, callbackFunction)

说明: 查询联系人, 方法执行结束后回调callbackFunction 由于Android联系人的诸多信息要多次查询,因此建议如果有获取所有联系的人的需求的时候建议仅仅查询Name字段,其余字段可考虑设置不查询,以优化查询速度.

参数:

参数名称 参数类型 是否必选 说明
option Object 搜索配置,json格式字符串,如下:
callbackFunction 函数 回调函数
var option = {
    resultNum:,//可选,单次返回数据数量,-1表示一次返回所有结果,默认50
    searchName:,//和contactId字段二选一,通过名字查询联系人,传空默认查询所有.
    contactId:,//和searchName字段二选一,可用于精确查找.(优先于Name)
    isSearchNum:,//可选,true,false是否查询电话号码,默认为true(Android 推荐false)
    isSearchEmail:,//可选,true,false是否查询Email,默认为true(Android 推荐false)
    isSearchAddress:,//可选,true,false是否查询Address,默认为true(Android 推荐false)
    isSearchCompany:,//可选,true,false是否查询Company,默认为true(Android 推荐false)
    isSearchTitle:,//可选,true,false是否查询title,默认为true(Android 推荐false)
    isSearchNote:,//可选,true,false是否查询Note,默认为true(Android 推荐false)
    isSearchUrl:,//可选,true,false是否查询Url,默认为true(Android 推荐false)
}

各字段含义如下:

字段名称 类型 是否必选 说明
resultNum Number 一次最多返回的结果条数,默认为50条,-1表示一次返回所有结果
searchName String 和contactId字段二选一,通过名字查询联系人,传空默认查询所有.
contactId String 和searchName字段二选一,可用于精确查找.(优先于Name)
isSearchNum Boolean true,false是否查询电话号码,默认为true(Android 推荐false)
isSearchEmail Boolean true,false是否查询Email,默认为true(Android 推荐false)
isSearchAddress Boolean true,false是否查询Address,默认为true(Android 推荐false)
isSearchCompany Boolean true,false是否查询Company,默认为true(Android 推荐false)
isSearchTitle Boolean true,false是否查询Title,默认为true(Android 推荐false)
isSearchNote Boolean true,false是否查询Note,默认为true(Android 推荐false)
isSearchUrl Boolean true,false是否查询Url,默认为true(Android 推荐false)

回调参数

var callbackFunction=function(error,data){}
参数名称 参数类型 说明
error Number 表示操作是否成功,0表示成功,其他表示失败.
data Array 搜索结果数据,形式见下:
var data = [
        {
            contactId:,//联系人id
            ...//其余Key值name, num, email
        }
        ...
    ]

示例:

var option = {
    resultNum:-1//-1表示一次返回所有结果
    searchName:'',//全部查询
    isSearchNum:false,
    isSearchEmail:false,
    isSearchAddress:false,
    isSearchCompany:false,
    isSearchTitle:false,
    isSearchNote:false,
    isSearchUrl:false
},
uexContact.search(option,function(error,data){
      if(!error){

      }
});
searchItem //查询联系人

uexContact.searchItem(nameKey,option,callbackFunction)

说明:

查询联系人, 方法执行结束后回调callbackFunction

参数:

参数名称 参数类型 是否必选 说明
nameKey String 名称,传空字符串时,查询通讯录中所有联系人
option Object 搜索配置,json格式字符串,如下:
callbackFunction Function 回调函数
var option = {
    resultNum:-1,//-1表示一次返回所有结果
    isSearchNum:,//可选,true,false是否查询电话号码,默认为true(Android 推荐false)
    isSearchEmail:,//可选,true,false是否查询Email,默认为true(Android 推荐false)
    isSearchAddress:,//可选,true,false是否查询Address,默认为true(Android 推荐false)
    isSearchCompany:,//可选,true,false是否查询Company,默认为true(Android 推荐false)
    isSearchTitle:,//可选,true,false是否查询title,默认为true(Android 推荐false)
    isSearchNote:,//可选,true,false是否查询Note,默认为true(Android 推荐false)
    isSearchUrl:,//可选,true,false是否查询Url,默认为true(Android 推荐false)
}

各字段含义如下:

字段名称 类型 是否必选 说明
resultNum Number 一次最多返回的结果条数,默认为50条,-1表示一次返回所有结果
isSearchNum Boolean true,false是否查询电话号码,默认为true(Android 推荐false)
isSearchEmail Boolean true,false是否查询Email,默认为true(Android 推荐false)
isSearchAddress Boolean true,false是否查询Address,默认为true(Android 推荐false)
isSearchCompany Boolean true,false是否查询Company,默认为true(Android 推荐false)
isSearchTitle Boolean true,false是否查询Title,默认为true(Android 推荐false)
isSearchNote Boolean true,false是否查询Note,默认为true(Android 推荐false)
isSearchUrl Boolean true,false是否查询Url,默认为true(Android 推荐false)

回调参数

var callbackFunction=function(error,data){}
参数名称 参数类型 说明
error Number 表示操作是否成功,0表示成功,其他表示失败.
data Object 搜索结果数据

示例:

var option = {
    resultNum:-1,//-1表示一次返回所有结果
    isSearchNum:false,
    isSearchEmail:false,
    isSearchAddress:false,
    isSearchCompany:false,
    isSearchTitle:false,
    isSearchNote:false,
    isSearchUrl:false
}
uexContact.searchItem("张三", option, function(error,data) {
    alert(JSON.stringify(data));
});
modifyWithId //修改联系人

uexContact.modifyWithId(option, callbackFunction)

说明:

修改联系人, 方法执行结束后回调callbackFunction

参数:

参数名称 参数类型 是否必选 说明
option Object 修改配置,json格式字符串,如下:
callbackFunction 函数 回调函数
var option = {
    contactId://联系人id
    name:,//联系人名称
    num:,//联系人电话
    email:,//联系人Email
}

各字段含义如下:

字段名称 类型 是否必选 说明
contactId String 所修改的联系人的id(可通过search获取联系人id)
name String 联系人修改后的名称
num String 联系人修改后的电话
email String 联系人修改后的Email

回调参数

var callbackFunction=function(error){}
参数名称 参数类型 说明
error Number 表示操作是否成功,0表示成功,其他表示失败.

示例:

var option = {
    contactId:'405',
    name:'Appcan',
    num:'15888888888',
    email:'widgeton@zymobi.com'
}
uexContact.modifyWithId(option, function(error) {
    alert(data);
});
modifyItem //修改联系人

uexContact.modifyItem(name,num,email, callbackFunction)

说明:

修改联系人, 方法执行结束后回调callbackFunction

参数:

参数名称 参数类型 是否必选 说明
name String 名称
num String 电话号码
email String 邮件
callbackFunction Function 回调函数

回调参数

var callbackFunction=function(error){}

errorNumber类型,用来

参数名称 参数类型 说明
error Number 表示操作是否成功,0表示成功,其他表示失败.

示例:

uexContact.modifyItem("张三","13436827900","widgetone@3g2win.com", function(error) {
    alert(data);
});
addItemWithVCard //vCard方式添加联系人

uexContact.addItemWithVCard(data,type, callbackFunction)

说明:

vCard方式添加联系人, 方法执行结束后回调callbackFunction

参数:

参数名称 参数类型 是否必选 说明
data String 联系人数据,数据格式如下:BEGIN:VCARD\nVERSION:3.0\nN:韩;超\nTEL:22334752\nEMAIL:zhuliang@ceair.com\nADR:;;绥宁路628号;;上海;200335\nORG:中国东方航空股有限公司\nTITLE:项目经理\nURL:mp.ceair.com\nNOTE:名\347\211\214二维码\nEND:VCARD 其中:N-姓名,TEL-电话,EMAIL-邮箱,ADR-地址,ORG-公司,TITLE-职位,URL-网址,NOTE-备注
type Number 是否显示提示框,1-不显示,其余情况显示.
callbackFunction 函数 回调函数

回调参数

var callbackFunction=function(error){}
参数名称 参数类型 说明
error Number 表示操作是否成功,0表示成功,其他表示失败.

示例:

uexContact.addItemWithVCard('BEGIN:VCARD\nVERSION:3.0\nN:韩;超\nTEL:22334752\nEMAIL:zhuliang@ceair.com\nADR:;;绥宁路628号;;上海;200335\nORG:中国东方航空股有限公司\nTITLE:项目经理\nURL:mp.ceair.com\nNOTE:名\347\211\214二维码\nEND:VCARD','',function(error){

});

3、更新历史

iOS

API版本: uexContact-4.0.2

最近更新时间:2017-04-28

历史发布版本 更新内容
4.0.2 修复search和searchItem不能返回全部联系人的问题
4.0.1 修复闪退/内存泄露bugs
Android

API版本: uexContact-4.0.2

最近更新时间:2017-4-28

历史发布版本 更新内容
4.0.2 修改search接口返回数据格式与iOS保持一致
4.0.1 解决获取联系人号码重复的问题
还需要帮助吗? 联系我们
最新更新 8th Jul 2021