/ Title: contact Description: contact /
来自于:官方
概述
contact 模块封装了系统通讯录的相关接口,通过此模块可实现对系统通讯录的联系人增、删、改、查操作,将底层负责的访问通讯录代码简单成一个个小接口,让开发者轻松访问通讯录。本模块停止更新,已有优化升级版本 contacts
openContact
打开系统通讯录界面
openContact(callback(ret, err))
callback(ret, err)
ret:
- 类型:JSON 对象
- 内部字段:
{
status:true //操作成功状态值
id: //联系人id
name: //联系人姓名,由通讯录里该联系人的姓和名组成
phones: //联系人电话组成的数组,内部字段:[{"标签":"号码"}]
email: //邮箱
company: //公司
title: //职位
address:
{
City: //城市
Country: //国家
CountryCode: //国家缩写
State: //省份
Street: //街道
ZIP: //邮编
}
note: //备注
groupId: //联系人在通讯录中所属分组的id(为空时表示未分组)
groupName: //所在分组的名字(为空时表示未分组)
}
err:
- 类型:JSON 对象
- 内部字段:
{
msg //报错信息
}
示例代码
var contact = api.require('contact');
contact.openContact(function(ret,err) {
if(ret.status) {
var array = ret.phones;
var firstnum = array[0];
var secondnum = array[1];
var thirdnum = array[2];
} else{
api.alert({msg:'用户取消'});
}
});
补充说明
获取联系人信息
可用性
iOS系统,Android系统
可提供的1.0.0及更高版本
addContact
往通讯录添加一个联系人
addContact({params}, callback(ret, err))
params
lastName:
- 类型:字符串
- 默认值:未命名
- 描述:(可选项)联系人姓
firstName:
- 类型:字符串
- 默认值:未命名
- 描述:(可选项)联系人名
groupId:
- 类型:数字
- 默认值:无
- 描述:(可选项)分组id
- 备注:若不传则表示未分组
phones:
- 类型:JSON数组对象
- 默认值:无
- 描述:(可选项)联系人电话JSON对象组成的数组对象
- 内部字段:
[{
label:'',
phone:''
}]
email:
- 类型:字符串
- 默认值:无
- 描述:(可选项)联系人邮箱
company:
- 类型:字符串
- 默认值:无
- 描述:(可选项)联系人公司
title:
- 类型:字符串
- 默认值:无
- 描述:(可选项)联系人职位
address:
- 类型:JSON 对象
- 默认值:无
- 描述:(可选项)联系人地址组成的JSON对象
- 内部字段:
{
City: //(可选项)城市,字符串类型,默认空
Country: //(可选项)国家,字符串类型,默认空
CountryCode: //(可选项)国家缩写,字符串类型,默认空
State: //(可选项)省份,字符串类型,默认空
Street: //(可选项)街道,字符串类型,默认空
ZIP: //(可选项)邮编,字符串类型,默认空
}
note:
- 类型:字符串
- 默认值:无
- 描述:(可选项)联系人备注
callback(ret, err)
ret:
- 类型:JSON 对象
- 内部字段:
{
status:true //操作成功状态值
}
示例代码
var contact = api.require('contact');
contact.addContact({
groupId:1,
firstName:'张',
lastName:'三',
phones:[{label:'住宅',phone:'123'},{label:'工作',phone:'456'}],
address: {
Country:'中国',
State:'北京',
City:'北京市',
Street:'鸟巢街',
ZIP:'100000'
},
email:'zhengcuan.sun@api.com',
company:'柚子科技',
title:'工程师',
note:'无'
},function(ret,err) {
if(ret.status) {
api.alert({msg:'添加成功'});
} else{
api.alert({msg:err.msg});
}
});
补充说明
添加一个联系人
可用性
iOS系统,Android系统
可提供的1.0.0及更高版本
deleteContact
从通讯录删除多个联系人
deleteContact({params}, callback(ret, err))
params
ids:
- 类型:数组
- 默认值:无
- 描述:要删除的联系人的id(数字)组成的数组
callback(ret, err)
ret:
- 类型:JSON 对象
- 内部字段:
{
status:true //操作成功状态值
}
示例代码
var contact = api.require('contact');
contact.deleteContact({
ids:[1,2]
},function(ret,err) {
if(ret.status) {
api.alert({msg:'删除成功'});
}else{
api.alert({msg:'删除失败'});
}
});
补充说明
删除指定联系人信息
可用性
iOS系统,Android系统
可提供的1.0.0及更高版本
updateContact
修改通讯录里的一个联系人
updateContact({params}, callback(ret, err))
params
id:
- 类型:数字
- 默认值:无
- 描述:要修改的联系人的id
groupId:
- 类型:数字
- 默认值:原值
- 描述:(可选项)要修改的联系人的分组id
- 备注:若不传或传空则不移动分组,若id为存在合法值则移动该联系人
lastName:
- 类型:字符串
- 默认值:原值
- 描述:(可选项)联系人的姓
firstName:
- 类型:字符串
- 默认值:原值
- 描述:(可选项)联系人名
phones:
- 类型:JSON 对象数组
- 默认值:原值
- 描述:(可选项)联系人电话组成的JSON对象数组
- 备注:若不传则不修改此属性
- 内部字段:[{ “标签”:”号码” }]
email:
- 类型:字符串
- 默认值:无
- 描述:(可选项)联系人邮箱
company:
- 类型:字符串
- 默认值:无
- 描述:(可选项)联系人公司
title:
- 类型:字符串
- 默认值:无
- 描述:(可选项)联系人职位
address:
- 类型:JSON 对象
- 默认值:无
- 描述:(可选项)联系人地址组成的JSON对象
- 内部字段:
{
City: //(可选项)城市,字符串类型,默认空
Country: //(可选项)国家,字符串类型,默认空
CountryCode: //(可选项)国家缩写,字符串类型,默认空
State: //(可选项)省份,字符串类型,默认空
Street: //(可选项)街道,字符串类型,默认空
ZIP: //(可选项)邮编,字符串类型,默认空
}
note:
- 类型:字符串
- 默认值:无
- 描述:(可选项)联系人备注
callback(ret, err)
ret:
- 类型:JSON 对象
- 内部字段:
{
status:true //操作成功状态值
}
示例代码
var contact = api.require('contact');
contact.updateContact({
id:1,
firstName:'张',
lastName:'三',
phones:[{label:'住宅',phone:'124'},{label:'工作',phone:'346'}],
address: {
Country:'',
State:'',
City:'',
Street:'',
ZIP:''
},
email:'',
company:'',
title:'',
note:''
},function(ret,err) {
if(ret.status) {
api.alert({msg:'修改成功'});
}else{
api.alert({msg:err.msg});
}
});
补充说明
修改指定联系人信息
可用性
iOS系统,Android系统
可提供的1.0.0及更高版本
queryContact
从通讯录查找联系人
queryContact({params}, callback(ret, err))
params
ids:
- 类型:数组对象
- 默认值;无
- 描述:(可选项)要查找的联系人的id(数字)组成的数组
- 备注:若不传则返回全部联系人信息
callback(ret, err)
ret:
- 类型:JSON 对象
- 内部字段:
contacts: //数组对象
[{
status:true //操作成功状态值
id: //联系人的id
name: //联系人名字,由通讯录里联系人的姓和名组成
phones: //联系人电话组成的数组,内部字段:[{"标签":"号码"}]
email: //邮箱
company: //公司
title: //职位
address:
{
City: //城市
Country: //国家
CountryCode: //国家缩写
State: //省份
Street: //街道
ZIP: //邮编
}
note: //备注
groupId: //联系人在通讯录中所属分组的id(为空时表示未分组)
groupName: //所在分组的名字(为空时表示未分组)
}]
示例代码
var contact = api.require('contact');
contact.queryContact({
ids:[1]
},function(ret,err) {
if(ret.status) {
var array =ret.contacts;
var first = array[0];
var arrayPho = first.phones;
var firstnum = arrayPho[0];
var secondnum = arrayPho[1];
var thirdnum = arrayPho[2];
} else{
api.alert({msg:'获取失败'});
}
});
补充说明
获取指定联系人信息
可用性
iOS系统,Android系统
可提供的1.0.0及更高版本
addGroup
创建分组
addGroup({params}, callback(ret, err))
params
name:
- 类型:字符串
- 默认值;无
- 描述:分组名
callback(ret, err)
ret:
- 类型:JSON 对象
- 内部字段:
{
status:true //操作成功状态值
id: //创建成功返回分组的id
}
示例代码
var contact = api.require('contact');
contact.addGroup({
name:'同学'
},function(ret,err){
if(ret.status){
api.alert({msg:'分组创建完成'+'*'+ret.id});
}else{
api.alert({msg:err.msg});
}
});
补充说明
创建分组
可用性
iOS系统,Android系统
可提供的1.0.0及更高版本
queryContactByKey
根据关键字从通讯录查找联系人
queryContactByKey({params}, callback(ret, err))
params
key:
- 类型:字符串
- 默认值;无
- 描述:要查询的关键字
callback(ret, err)
ret:
- 类型:JSON 对象
- 内部字段:
contacts: //数组对象
[{
status:true //操作成功状态值
id: //联系人的id
name: //联系人名字,由通讯录里联系人的姓和名组成
phones: //联系人电话组成的数组,内部字段:[{"标签":"号码"}]
email: //邮箱
company: //公司
title: //职位
address:
{
City: //城市
Country: //国家
CountryCode: //国家缩写
State: //省份
Street: //街道
ZIP: //邮编
}
note: //备注
groupId: //联系人在通讯录中所属分组的id(为空时表示未分组)
groupName: //所在分组的名字(为空时表示未分组)
}]
示例代码
var contact = api.require('contact');
contact.queryContactByKey({
key:'孙'
},function(ret,err) {
if(ret.status) {
var array = ret.contacts;
var first = array[0];
var arrayPho = first.phones;
var firstnum = arrayPho[0];
var secondnum = arrayPho[1];
var thirdnum = arrayPho[2];
}else{
api.alert({msg:'获取失败'});
}
});
补充说明
根据关键字获取联系人信息
可用性
iOS系统,Android系统
可提供的1.0.0及更高版本
queryGroups
获取所有分组信息
queryGroups(callback(ret, err))
callback(ret, err)
ret:
- 类型:JSON数组对象
- 内部字段:
{
groups: //分组名所组成的数组
[{
name: //分组名
id: //分组的id
}]
}
示例代码
var contact = api.require('contact');
contact.queryGroups(function(ret,err) {
if(ret.status){
var array =ret.groups;
var first = array[0];
}else{
api.alert({msg:err.msg});
}
});
补充说明
获取所有分组信息
可用性
iOS系统,Android系统
可提供的1.0.0及更高版本
queryContactByGroupId
查找一个分组内的联系人
queryContactByGroupId({params}, callback(ret, err))
params
id:
- 类型:字符串对象
- 默认值;无
- 描述:(可选项)要查找的分组的id
- 备注:若不传则则返回全部联系人信息
callback(ret, err)
ret:
- 类型:JSON 对象
- 内部字段:
{
status:true //操作成功状态值
id: //联系人id
name: //联系人姓名,由通讯录里该联系人的姓和名组成
phones: //联系人电话组成的数组,内部字段:[{"标签":"号码"}]
email: //邮箱
company: //公司
title: //职位
address:
{
City: //城市
Country: //国家
CountryCode: //国家缩写
State: //省份
Street: //街道
ZIP: //邮编
}
note: //备注
groupId: //联系人在通讯录中所属分组的id(为空时表示未分组)
groupName: //所在分组的名字(为空时表示未分组)
}
示例代码
var contact = api.require('contact');
contact.findContact({
id:1
},function(ret,err) {
if(ret.status) {
var array = ret.names;
var first = array[0];
var arrayPho = first.phones;
var firstnum = arrayPho[0];
var secondnum = arrayPho[1];
var thirdnum = arrayPho[2];
} else{
api.alert({msg:err.msg});
}
});
补充说明
获取指定分子内联系人信息
可用性
iOS系统,Android系统
可提供的1.0.0及更高版本
updateGroupName
修改分组名
updateGroupName({params}, callback(ret, err))
params
id:
- 类型:数字
- 默认值;无
- 描述:要修改的分组的id
name:
- 类型:字符串
- 默认值;无
- 描述:要修改成为的分组名
callback(ret, err)
ret:
- 类型:JSON 对象
- 内部字段:
{
status:true //操作成功状态值
}
示例代码
var contact = api.require('contact');
contact.updateGroupName({
id:1,
name:'同学'
},function(ret,err){
if(ret.status){
api.alert({msg:'分组修改完成'});
}else{
api.alert({msg:err.msg});
}
});
补充说明
目前ios暂不支持此接口,可通过删除分组,然后再创建来实现此功能
可用性
Android系统
可提供的1.0.0及更高版本
deleteGroup
删除分组
deleteGroup({params}, callback(ret, err))
params
id:
- 类型:数字
- 默认值;无
- 描述:要删除的分组的id
callback(ret, err)
ret:
- 类型:JSON 对象
- 内部字段:
{
status: //操作成功状态值
}
示例代码
var contact= api.require('contact');
contact.deleteGroup({
id:1
},function(ret,err){
if(ret.status){
api.alert({msg:'分组删除完成'});
}else{
api.alert({msg:err.msg});
}
});
补充说明
删除分组
可用性
iOS系统,Android系统
可提供的1.0.0及更高版本