DVContacts
概述
DVContacts 插件封装了系统通讯录的相关接口；可实现联系人的增、删、改、查的操作，创建、管理分组、移动联系人等功能；用于读取或管理通讯录联系人的数据。 【安卓邮箱支持字段：家庭、工作、个人、其他】 【安卓电话支持字段：家庭、手机、单位、主要、工作电话、工作传真、家庭传真、传呼机、其他】 【安卓地址支持字段：家庭、工作、其他】 【安卓活动日期支持字段：生日、自定义】 【安卓活动日期支持字段：父亲、母亲、 父母、助理、兄弟、子女、朋友、经理、合作伙伴、介绍人、亲属、姐妹、配偶、同居伴侣、自定义】 【安卓即时通讯支持字段：AIM、雅虎、Skype、QQ、ICQ、Jabber、环聊、自定义】
注意使用此插件云编译时请添加通讯录访问权限。
注意：本插件 iOS 平台上最低适配系统版本为 iOS 9.0
注意：由于iOS 13中将禁止应用开发者访问用户通讯录备注信息，插件取消了note字段的返回和相关操作
openContactsUI
打开系统通讯录界面，选择单个联系人，返回已选的联系人信息
openContactsUI(params, callback(ret,err))
callback(ret,err)
ret:
- 类型：JSON对象
- 内部字段：
{
status: true, //布尔型；true||false
id: 0, //数字类型；系统分配的联系人 id
image: '', //字符类型；图片的沙河路径
lastName: '', //字符串类型；联系人姓氏，若该联系人此信息缺少则本字段为undefine
firstName: '', //字符串类型；联系人名字，若该联系人此信息缺少则本字段为undefine
middleName: '', //字符串类型；联系人中间名，若该联系人此信息缺少则本字段为undefine
prefix: '', //字符串类型；名称前缀，若该联系人此信息缺少则本字段为undefine
suffix: '', //字符串类型；名称后缀，若该联系人此信息缺少则本字段为undefine
fullName: '', //字符串类型；联系人全名，若该联系人此信息缺少则本字段为undefine
company: '', //字符串类型；公司
title: '', //字符串类型；职位
phones: [{'':''},{'':''}], //数组类型；联系人电话组成的数组
//内部字段：[{"标签": '号码'}]
emails: [{'':''},{'':''}], //数组类型；邮箱组成的数组
//内部字段：[{"标签": '邮箱'}]
url: [{'':''},{'':''}], //数组类型；URL组成的数组
//内部字段：[{"标签": 'url'}]
address: [{'':{ //数组类型； 地址组成的数组
City: '', //字符串类型；城市
Country: '', //字符串类型；国家
State: '', //字符串类型；省份
Street: '', //字符串类型；街道
ZIP: '100020' //字符串类型；邮编
}}],
dates: [{'':{ //数组类型； 日期组成的数组
year: '', //字符串类型；年；没有设置返回0
month: '', //字符串类型；月
day: '', //字符串类型；日
}}],
contactRelation: [{'':''},{'':''}], //数组类型；关系人组成的数组
//内部字段：[{"标签": '关系人'}]
socialProfiles: [{'':''},{'':''}], //数组类型；社交资料组成的数组
//内部字段：[{"标签": '社交资料'}]
instantMessageAddresses: [{'':''},{'':''}], //数组类型；即时信息组成的数组
//内部字段：[{"标签": '即时信息'}]
note: '', //字符串类型；备注
}
err：
- 类型：JSON 对象
- 内部字段：
{
code: 0 //数字类型；
//错误码：
-1：（用户未授权本app访问通讯录）
0：（获取成功）
1：（用户取消）
}
示例代码
var DVContacts = api.require('DVContacts');
DVContacts.openContactsUI(function(ret,err) {
if (ret) {
api.alert({
msg: JSON.stringify(ret)
})
} else {
api.alert({
msg: JSON.stringify(err)
})
}
});
可用性
iOS系统，Android系统
可提供的1.0.0及更高版本
allContacts
获取所有联系人
allContacts(params, callback(ret,err))
callback(ret,err)
ret:
- 类型：JSON对象
- 内部字段：
{
status: true, //布尔型；true||false
total: 100, //数字类型；联系人的总数
contacts: [
id: 0, //数字类型；系统分配的联系人 id
image: '', //字符类型；图片的沙河路径
lastName: '', //字符串类型；联系人姓氏，若该联系人此信息缺少则本字段为undefine
firstName: '', //字符串类型；联系人名字，若该联系人此信息缺少则本字段为undefine
middleName: '', //字符串类型；联系人中间名，若该联系人此信息缺少则本字段为undefine
prefix: '', //字符串类型；名称前缀，若该联系人此信息缺少则本字段为undefine
suffix: '', //字符串类型；名称后缀，若该联系人此信息缺少则本字段为undefine
fullName: '', //字符串类型；联系人全名，若该联系人此信息缺少则本字段为undefine
company: '', //字符串类型；公司
title: '', //字符串类型；职位
phones: [{'':''},{'':''}], //数组类型；联系人电话组成的数组
//内部字段：[{"标签": '号码'}]
emails: [{'':''},{'':''}], //数组类型；邮箱组成的数组
//内部字段：[{"标签": '邮箱'}]
url: [{'':''},{'':''}], //数组类型；URL组成的数组
//内部字段：[{"标签": 'url'}]
address: [{'':{ //数组类型； 地址组成的数组
City: '', //字符串类型；城市
Country: '', //字符串类型；国家
State: '', //字符串类型；省份
Street: '', //字符串类型；街道
ZIP: '100020' //字符串类型；邮编
}}],
dates: [{'':{ //数组类型； 日期组成的数组
year: '', //字符串类型；年；没有设置返回0
month: '', //字符串类型；月
day: '', //字符串类型；日
}}],
contactRelation: [{'':''},{'':''}], //数组类型；关系人组成的数组
//内部字段：[{"标签": '关系人'}]
socialProfiles: [{'':''},{'':''}], //数组类型；社交资料组成的数组
//内部字段：[{"标签": '社交资料'}]
instantMessageAddresses: [{'':''},{'':''}], //数组类型；即时信息组成的数组
//内部字段：[{"标签": '即时信息'}]
note: '', //字符串类型；备注
}]
}
err：
- 类型：JSON 对象
- 内部字段：
{
code: 0, //数字类型；
//错误码：
0：（用户未授权本应用访问通讯录，Android 平台忽略此错误码）
1：（读取错误）
msg: '' //字符串类型；错误信息
}
示例代码
var DVContacts = api.require('DVContacts');
DVContacts.allContacts(function(ret,err) {
if (ret) {
api.alert({
msg: JSON.stringify(ret)
})
} else {
api.alert({
msg: JSON.stringify(err)
})
}
});
可用性
iOS系统，Android系统
可提供的1.0.0及更高版本
add
向通讯录添加一个联系人，所有参数不可同时为空。添加
add({params}, callback(ret, err))
params
image：
- 类型：字符串
- 描述：（可选项）联系人头像，支持widget://、fs://
lastName：
- 类型：字符串
- 描述：（可选项）联系人姓氏
firstName：
- 类型：字符串
- 描述：（可选项）联系人名字
middleName：
- 类型：字符串
- 描述：（可选项）联系人中间名
prefix：
- 类型：字符串
- 描述：（可选项）联系人名称前缀
suffix：
- 类型：字符串
- 描述：（可选项）联系人名称后缀
company：
- 类型：字符串
- 描述：（可选项）联系人公司
title：
- 类型：字符串
- 描述：（可选项）联系人职位
phones：
- 类型：数组
- 描述：（可选项）联系人电话组成的数组
- 内部字段：
//数组类型；内部字段：[{"标签": '号码'}]
//标签：iPhone、手机、主要、家庭传真、工作传真、传呼机、其他
[{
'iPhone': '13512345678'
},{
'手机': '13512345678'
}]
address：
- 类型：数组对象
- 描述：（可选项）联系人地址
- 内部字段：
//标签：家庭、工作、其他
[{'工作':{
City: '', //（可选项）字符串类型；城市；
Country: '', //（可选项）字符串类型；国家；
State: '', //（可选项）字符串类型；省份；
Street: '', //（可选项）字符串类型；街道；
ZIP: '' //（可选项）字符串类型；邮编；
}},
{'家庭':{
City: '', //（可选项）字符串类型；城市；
Country: '', //（可选项）字符串类型；国家；
State: '', //（可选项）字符串类型；省份；
Street: '', //（可选项）字符串类型；街道；
ZIP: '' //（可选项）字符串类型；邮编；
}}]
url：
- 类型：数组对象
- 描述：（可选项）URL
- 内部字段：
//数组类型；内部字段：[{"标签": 'url'}]
//标签：家庭、工作、其他、主页
[{
'工作': 'developer.yonyou.com'
},{
'家庭': 'developer.yonyou.com'
}]
emails：
- 类型：数组对象
- 描述：（可选项）邮箱
- 内部字段：
//数组类型；内部字段：[{"标签": '邮箱'}]
//标签：家庭、工作、其他、iCloud、主页
[{
'工作': '13512345678@163.com'
},{
'家庭': '13512345678@163.com'
}]
dates：
- 类型：数组对象
- 描述：（可选项）日期
- 内部字段：
//标签：纪念日、其他
[{'纪念日':{ //数组类型； 日期组成的数组
year: 2018, //数字类型；年；没有设置返回0
month: 7, //数字类型；月
day: 27, //数字类型；日
}},
{'其他':{ //数组类型； 日期组成的数组
year: 2018, //数字类型；年；没有设置返回0
month: 7, //数字类型；月
day: 27, //数字类型；日
}}]
contactRelation：
- 类型：数组对象
- 描述：（可选项）关联人
- 内部字段：
//数组类型；内部字段：[{"标签": '关联人'}]
//标签：父亲、母亲、父母、兄弟、姐妹、子女、朋友、配偶、伴侣、助理、上司、儿子（此标签仅支持 iOS 11.0及以上）、女儿此标签仅支持 iOS 11.0及以上）
[{
'父亲': ''
},{
'母亲': ''
}]
socialProfiles：
- 类型：数组对象
- 描述：（可选项）社交资料
- 内部字段：
//数组类型；内部字段：[{"标签": '社交资料'}]
//标签：新浪微博、Twitter、Facebook、Flickr、领英、Myspace
[{
'Twitter': ''
},{
'Facebook': ''
}]
instantMessageAddresses：
- 类型：数组对象
- 描述：（可选项）即时信息
- 内部字段：
//数组类型；内部字段：[{"标签": '即时信息'}]
//标签：QQ、Skype、MSN、GoogleTalk、Facebook、AIM、Yahoo、ICQ、Jabber、GaduGadu
[{
'QQ': ''
},{
'ICQ': ''
}]
note：
- 类型：字符串
- 描述：（可选项）联系人备注
callback(ret, err)
ret：
- 类型：JSON 对象
- 内部字段：
{
status: true, //布尔型；true||false
}
err：
- 类型：JSON 对象
- 内部字段：
{
code: 0, //数字类型；
//错误码：
0：（用户未授权本应用访问通讯录，Android 平台忽略此错误码）
1：（添加错误）
msg: '' //字符串类型；错误信息
}
示例代码
var VDVContacts = api.require('DVContacts');
DVContacts.add({
lastName: '张',
firstName: '三丰',
middleName: '太极',
prefix: '他',
suffix: '牛',
company: '柚子科技',
title: '工程师',
note: '无',
phones:[{
'工作': '13512345678'
},{
'家庭': '13512345678'
}],
address:[{'工作':{
City: '', //（可选项）字符串类型；城市；
Country: '', //（可选项）字符串类型；国家；
State: '', //（可选项）字符串类型；省份；
Street: '', //（可选项）字符串类型；街道；
ZIP: '' //（可选项）字符串类型；邮编；
}},
{'家庭':{
City: '', //（可选项）字符串类型；城市；
Country: '', //（可选项）字符串类型；国家；
State: '', //（可选项）字符串类型；省份；
Street: '', //（可选项）字符串类型；街道；
ZIP: '' //（可选项）字符串类型；邮编；
}}],
url:[{
'工作': 'developer.yonyou.com'
},{
'家庭': 'developer.yonyou.com'
}],
emails:[{
'工作': '13512345678@163.com'
},{
'家庭': '13512345678@163.com'
}],
dates:[{'纪念日':{ //数组类型； 日期组成的数组
year: '', //字符串类型；年；没有设置返回0
month: '', //字符串类型；月
day: '', //字符串类型；日
}},
{'其他':{ //数组类型； 日期组成的数组
year: '', //字符串类型；年；没有设置返回0
month: '', //字符串类型；月
day: '', //字符串类型；日
}}],
contactRelation:[{
'父亲': ''
},{
'母亲': ''
}],
socialProfiles:[{
'Twitter': ''
},{
'Facebook': ''
}],
instantMessageAddresses:[{
'QQ': ''
},{
'ICQ': ''
}]
}, function(ret, err) {
if (ret) {
api.alert({
msg: JSON.stringify(ret)
})
} else {
api.alert({
msg: JSON.stringify(err)
})
}
});
可用性
iOS系统，Android系统
可提供的1.0.0及更高版本
delete
从通讯录删除一个或多个联系人
delete({params}, callback(ret, err))
params
ids：
- 类型：数组, 数组元素为整型
- 描述：联系人的 id 组成的数组，若传入的 id 不存在，则忽略此id
callback(ret, err)
ret：
- 类型：JSON 对象
- 内部字段：
{
status: true //布尔型；true||false
}
err：
- 类型：JSON 对象
- 内部字段：
{
code: 0, //数字类型；
//错误码：
0：（用户未授权本应用访问通讯录，Android 平台忽略此错误码）
1：（删除错误）
msg: '' //字符串类型；错误信息
}
示例代码
var DVContacts = api.require('DVContacts');
DVContacts.delete({
ids: [1, 2]
}, function(ret, err) {
if (ret) {
api.alert({
msg: JSON.stringify(ret)
})
} else {
api.alert({
msg: JSON.stringify(err)
})
}
});
可用性
iOS系统，Android系统
可提供的1.0.0及更高版本
update
根据 id 更新通讯录的联系人信息
update({params}, callback(ret, err))
params
id：
- 类型：字符串
- 描述：联系人的id
image：
- 类型：字符串
- 描述：（可选项）联系人头像，支持widget://、fs://
lastName：
- 类型：字符串
- 描述：（可选项）联系人姓氏
firstName：
- 类型：字符串
- 描述：（可选项）联系人名字
middleName：
- 类型：字符串
- 描述：（可选项）联系人中间名
prefix：
- 类型：字符串
- 描述：（可选项）联系人名称前缀
suffix：
- 类型：字符串
- 描述：（可选项）联系人名称后缀
company：
- 类型：字符串
- 描述：（可选项）联系人公司
title：
- 类型：字符串
- 描述：（可选项）联系人职位
phones：
- 类型：数组
- 描述：（可选项）联系人电话组成的数组
- 内部字段：
//数组类型；内部字段：[{"标签": '号码'}]
//标签：iPhone、手机、主要、家庭传真、工作传真、传呼机、其他
[{
'iPhone': '13512345678'
},{
'手机': '13512345678'
}]
address：
- 类型：数组对象
- 描述：（可选项）联系人地址
- 内部字段：
//标签：家庭、工作、其他
{'工作':{
City: '', //（可选项）字符串类型；城市；
Country: '', //（可选项）字符串类型；国家；
State: '', //（可选项）字符串类型；省份；
Street: '', //（可选项）字符串类型；街道；
ZIP: '' //（可选项）字符串类型；邮编；
},
'家庭':{
City: '', //（可选项）字符串类型；城市；
Country: '', //（可选项）字符串类型；国家；
State: '', //（可选项）字符串类型；省份；
Street: '', //（可选项）字符串类型；街道；
ZIP: '' //（可选项）字符串类型；邮编；
}}
url：
- 类型：数组对象
- 描述：（可选项）URL
- 内部字段：
//数组类型；内部字段：[{"标签": 'url'}]
//标签：家庭、工作、其他、主页
[{
'工作': 'developer.yonyou.com'
},{
'家庭': 'developer.yonyou.com'
}]
emails：
- 类型：数组对象
- 描述：（可选项）邮箱
- 内部字段：
//数组类型；内部字段：[{"标签": '邮箱'}]
//标签：家庭、工作、其他、iCloud、主页
[{
'工作': '13512345678@163.com'
},{
'家庭': '13512345678@163.com'
}]
dates：
- 类型：数组对象
- 描述：（可选项）日期
- 内部字段：
//标签：纪念日、其他
{'纪念日':{ //数组类型； 日期组成的数组
year: 2018, //数字类型；年；没有设置返回0
month: 7, //数字类型；月
day: 27, //数字类型；日
},
'其他':{ //数组类型； 日期组成的数组
year: 2018, //数字类型；年；没有设置返回0
month: 7, //数字类型；月
day: 27, //数字类型；日
}}
contactRelation：
- 类型：数组对象
- 描述：（可选项）关联人【仅ios支持】
- 内部字段：
//数组类型；内部字段：[{"标签": '关联人'}]
//标签：父亲、母亲、父母、兄弟、姐妹、子女、朋友、配偶、伴侣、助理、上司、儿子（此标签仅支持 iOS 11.0及以上）、女儿此标签仅支持 iOS 11.0及以上）
[{
'父亲': ''
},{
'母亲': ''
}]
socialProfiles：
- 类型：数组对象
- 描述：（可选项）社交资料【仅ios支持】
- 内部字段：
//数组类型；内部字段：[{"标签": '社交资料'}]
//标签：新浪微博、Twitter、Facebook、Flickr、领英、Myspace
[{
'Twitter': ''
},{
'Facebook': ''
}]
instantMessageAddresses：
- 类型：数组对象
- 描述：（可选项）即时信息
- 内部字段：
//数组类型；内部字段：[{"标签": '即时信息'}]
//标签：QQ、Skype、MSN、GoogleTalk、Facebook、AIM、Yahoo、ICQ、Jabber、GaduGadu
[{
'QQ': ''
},{
'ICQ': ''
}]
note：
- 类型：字符串
- 描述：（可选项）联系人备注
callback(ret, err)
ret：
- 类型：JSON 对象
- 内部字段：
{
status: true //布尔型；true||false
}
err：
- 类型：JSON 对象
- 内部字段：
{
code: 0, //数字类型；
//错误码：
0：（用户未授权本应用访问通讯录）
1：（更新错误）
msg: '' //字符串类型；错误信息
}
示例代码
var DVContacts = api.require('DVContacts');
DVContacts.update({
id: 1,
lastName: '李',
firstName: '四',
middleName: 'Cloud',
prefix: 'API',
suffix: '柚子',
phones: [{
'住宅': '12345678'
}, {
'工作': '87654321'
}],
email: 'zhengcuan@api.com',
company: '柚子科技',
title: '工程师',
address: {
Country: '中国',
State: '北京',
City: '北京市',
Street: '鸟巢街',
ZIP: '100000'
},
note: '无'
}, function(ret, err) {
if (ret) {
api.alert({
msg: JSON.stringify(ret)
})
} else {
api.alert({
msg: JSON.stringify(err)
})
}
});
可用性
iOS系统，Android系统
可提供的1.0.0及更高版本
query
根据联系人 id 查找联系人
query({params}, callback(ret, err))
params
ids：
- 类型：数组
- 描述：联系人 id 组成的数组，若 id 不存在则不处理
callback(ret, err)
ret：
- 类型：JSON 对象
- 内部字段：
{
status: true, //布尔型；true||false
total: 100, //数字类型；联系人的总数
contacts: [
id: 0, //数字类型；系统分配的联系人 id
image: '', //字符类型；图片的沙河路径
lastName: '', //字符串类型；联系人姓氏，若该联系人此信息缺少则本字段为undefine
firstName: '', //字符串类型；联系人名字，若该联系人此信息缺少则本字段为undefine
middleName: '', //字符串类型；联系人中间名，若该联系人此信息缺少则本字段为undefine
prefix: '', //字符串类型；名称前缀，若该联系人此信息缺少则本字段为undefine
suffix: '', //字符串类型；名称后缀，若该联系人此信息缺少则本字段为undefine
fullName: '', //字符串类型；联系人全名，若该联系人此信息缺少则本字段为undefine
company: '', //字符串类型；公司
title: '', //字符串类型；职位
phones: [{'':''},{'':''}], //数组类型；联系人电话组成的数组
//内部字段：[{"标签": '号码'}]
emails: [{'':''},{'':''}], //数组类型；邮箱组成的数组
//内部字段：[{"标签": '邮箱'}]
url: [{'':''},{'':''}], //数组类型；URL组成的数组
//内部字段：[{"标签": 'url'}]
address: [{'':{ //数组类型； 地址组成的数组
City: '', //字符串类型；城市
Country: '', //字符串类型；国家
State: '', //字符串类型；省份
Street: '', //字符串类型；街道
ZIP: '100020' //字符串类型；邮编
}}],
dates: [{'':{ //数组类型； 日期组成的数组
year: '', //字符串类型；年；没有设置返回0
month: '', //字符串类型；月
day: '', //字符串类型；日
}}],
contactRelation: [{'':''},{'':''}], //数组类型；关系人组成的数组
//内部字段：[{"标签": '关系人'}]
socialProfiles: [{'':''},{'':''}], //数组类型；社交资料组成的数组
//内部字段：[{"标签": '社交资料'}]
instantMessageAddresses: [{'':''},{'':''}], //数组类型；即时信息组成的数组
//内部字段：[{"标签": '即时信息'}]
note: '', //字符串类型；备注
}]
}
err：
- 类型：JSON 对象
- 内部字段：
{
code: 0, //数字类型；
//错误码：
0：（用户未授权本应用访问通讯录，Android 平台忽略此错误码）
1：（获取错误）
msg: '' //字符串类型；错误信息
}
示例代码
var DVContacts = api.require('DVContacts');
DVContacts.query({
ids: [1, 2]
}, function(ret, err) {
if (ret) {
api.alert({
msg: JSON.stringify(ret)
})
} else {
api.alert({
msg: JSON.stringify(err)
})
}
});
可用性
iOS系统，Android系统
可提供的1.0.0及更高版本
queryByKeyword
根据关键字从通讯录查找联系人
queryByKeyword({params}, callback(ret, err))
params
keyword：
- 类型：字符串
- 描述：要查询的关键字 注意：仅搜索 lastName 和 firstName 包含的关键字
callback(ret, err)
ret：
- 类型：JSON 对象
- 内部字段：
{
status: true, //布尔型；true||false
total: 100, //数字类型；联系人的总数
contacts: [
id: 0, //数字类型；系统分配的联系人 id
image: '', //字符类型；图片的沙河路径
lastName: '', //字符串类型；联系人姓氏，若该联系人此信息缺少则本字段为undefine
firstName: '', //字符串类型；联系人名字，若该联系人此信息缺少则本字段为undefine
middleName: '', //字符串类型；联系人中间名，若该联系人此信息缺少则本字段为undefine
prefix: '', //字符串类型；名称前缀，若该联系人此信息缺少则本字段为undefine
suffix: '', //字符串类型；名称后缀，若该联系人此信息缺少则本字段为undefine
fullName: '', //字符串类型；联系人全名，若该联系人此信息缺少则本字段为undefine
company: '', //字符串类型；公司
title: '', //字符串类型；职位
phones: [{'':''},{'':''}], //数组类型；联系人电话组成的数组
//内部字段：[{"标签": '号码'}]
emails: [{'':''},{'':''}], //数组类型；邮箱组成的数组
//内部字段：[{"标签": '邮箱'}]
url: [{'':''},{'':''}], //数组类型；URL组成的数组
//内部字段：[{"标签": 'url'}]
address: [{'':{ //数组类型； 地址组成的数组
City: '', //字符串类型；城市
Country: '', //字符串类型；国家
State: '', //字符串类型；省份
Street: '', //字符串类型；街道
ZIP: '100020' //字符串类型；邮编
}}],
dates: [{'':{ //数组类型； 日期组成的数组
year: '', //字符串类型；年；没有设置返回0
month: '', //字符串类型；月
day: '', //字符串类型；日
}}],
contactRelation: [{'':''},{'':''}], //数组类型；关系人组成的数组
//内部字段：[{"标签": '关系人'}]
socialProfiles: [{'':''},{'':''}], //数组类型；社交资料组成的数组
//内部字段：[{"标签": '社交资料'}]
instantMessageAddresses: [{'':''},{'':''}], //数组类型；即时信息组成的数组
//内部字段：[{"标签": '即时信息'}]
note: '', //字符串类型；备注
}]
}
err：
- 类型：JSON 对象
- 内部字段：
{
code: 0, //数字类型；
//错误码：
0：（用户未授权本应用访问通讯录，Android 平台忽略此错误码）
1：（获取错误）
msg: '' //字符串类型；错误信息
}
示例代码
var DVContacts = api.require('DVContacts');
DVContacts.queryByKeyword({
keyword: '王'
}, function(ret, err) {
if (ret) {
api.alert({
msg: JSON.stringify(ret)
})
} else {
api.alert({
msg: JSON.stringify(err)
})
}
});
可用性
iOS系统，Android系统
可提供的1.0.0及更高版本
createGroup
创建分组
createGroup({params}, callback(ret, err))
params
groupName：
- 类型：字符串
- 描述：分组名
callback(ret, err)
ret：
- 类型：JSON 对象
- 内部字段：
{
status: true, //布尔型；true||false
groupId: 1 //创建成功返回的分组 id
}
err：
- 类型：JSON 对象
- 内部字段：
{
code: 0, //数字类型；
//错误码：
0：（用户未授权本应用访问通讯录，Android 平台忽略此错误码）
1:创建失败
msg: '' //字符串类型；错误信息
}
示例代码
var DVContacts = api.require('DVContacts');
DVContacts.createGroup({
groupName: '同学'
}, function(ret, err) {
if (ret) {
api.alert({
msg: JSON.stringify(ret)
})
} else {
api.alert({
msg: JSON.stringify(err)
})
}
});
可用性
iOS系统，Android系统
可提供的1.0.0及更高版本
deleteGroup
删除分组，只删除分组，不删除其中的联系人
deleteGroup({params}, callback(ret, err))
params
groupId：
- 类型：字符
- 描述：分组 id
callback(ret, err)
ret：
- 类型：JSON 对象
- 内部字段：
{
status: true //布尔型；true||false
}
err：
- 类型：JSON 对象
- 内部字段：
{
code: 0, //数字类型；
//错误码：
0：（用户未授权本应用访问通讯录，Android 平台忽略此错误码）
1：（删除失败）
msg: '' //字符串类型；错误信息
}
示例代码
var DVContacts = api.require('DVContacts');
DVContacts.deleteGroup({
groupId: ''
}, function(ret, err) {
if (ret) {
api.alert({
msg: JSON.stringify(ret)
})
} else {
api.alert({
msg: JSON.stringify(err)
})
}
});
可用性
iOS系统，Android系统
可提供的1.0.0及更高版本
queryGroups
获取所有分组信息
queryGroups(callback(ret, err))
callback(ret, err)
ret：
- 类型：JSON 对象
- 内部字段：
{
status: true, //布尔型；true||false
groups: [{
name: '', //字符串类型；分组名
id: 1 //数字类型；分组 id
}]
}
err：
- 类型：JSON 对象
- 内部字段：
{
code: 0, //数字类型；
//错误码：
0：（用户未授权本应用访问通讯录，Android 平台忽略此错误码）
1：（获取失败）
msg: '' //字符串类型；错误信息
}
示例代码
var DVContacts = api.require('DVContacts');
DVContacts.queryGroups(function(ret, err) {
if (ret) {
api.alert({
msg: JSON.stringify(ret)
})
} else {
api.alert({
msg: JSON.stringify(err)
})
}
});
可用性
iOS系统，Android系统
可提供的1.0.0及更高版本
queryByGroupId
根据分组 id 查找联系人
queryByGroupId({params}, callback(ret, err))
params
groupId：
- 类型：数字
- 描述：（可选项）要查找的分组 id
callback(ret, err)
ret：
- 类型：JSON 对象
- 内部字段：
{
status: true, //布尔型；true||false
total: 100, //数字类型；联系人的总数
contacts: [
id: 0, //数字类型；系统分配的联系人 id
image: '', //字符类型；图片的沙河路径
lastName: '', //字符串类型；联系人姓氏，若该联系人此信息缺少则本字段为undefine
firstName: '', //字符串类型；联系人名字，若该联系人此信息缺少则本字段为undefine
middleName: '', //字符串类型；联系人中间名，若该联系人此信息缺少则本字段为undefine
prefix: '', //字符串类型；名称前缀，若该联系人此信息缺少则本字段为undefine
suffix: '', //字符串类型；名称后缀，若该联系人此信息缺少则本字段为undefine
fullName: '', //字符串类型；联系人全名，若该联系人此信息缺少则本字段为undefine
company: '', //字符串类型；公司
title: '', //字符串类型；职位
phones: [{'':''},{'':''}], //数组类型；联系人电话组成的数组
//内部字段：[{"标签": '号码'}]
emails: [{'':''},{'':''}], //数组类型；邮箱组成的数组
//内部字段：[{"标签": '邮箱'}]
url: [{'':''},{'':''}], //数组类型；URL组成的数组
//内部字段：[{"标签": 'url'}]
address: [{'':{ //数组类型； 地址组成的数组
City: '', //字符串类型；城市
Country: '', //字符串类型；国家
State: '', //字符串类型；省份
Street: '', //字符串类型；街道
ZIP: '100020' //字符串类型；邮编
}}],
dates: [{'':{ //数组类型； 日期组成的数组
year: '', //字符串类型；年；没有设置返回0
month: '', //字符串类型；月
day: '', //字符串类型；日
}}],
contactRelation: [{'':''},{'':''}], //数组类型；关系人组成的数组
//内部字段：[{"标签": '关系人'}]
socialProfiles: [{'':''},{'':''}], //数组类型；社交资料组成的数组
//内部字段：[{"标签": '社交资料'}]
instantMessageAddresses: [{'':''},{'':''}], //数组类型；即时信息组成的数组
//内部字段：[{"标签": '即时信息'}]
note: '', //字符串类型；备注
}]
}
err：
- 类型：JSON 对象
- 内部字段：
{
code: 0, //数字类型；
//错误码：
0：（用户未授权本应用访问通讯录，Android 平台忽略此错误码）
1：（获取失败）
msg: '' //字符串类型；错误信息
}
示例代码
var DVContacts = api.require('DVContacts');
DVContacts.queryByGroupId({
groupId: 1
}, function(ret, err) {
if (ret) {
api.alert({
msg: JSON.stringify(ret)
})
} else {
api.alert({
msg: JSON.stringify(err)
})
}
});
可用性
iOS系统，Android系统
可提供的1.0.0及更高版本
move
根据 id 移动联系人至指定分组
move({params}, callback(ret, err))
params
id：
- 类型：字符
- 描述：联系人 id
groupId：
- 类型：字符
- 描述：联系人的分组 id；若分组不存在则不移动分组
callback(ret, err)
ret：
- 类型：JSON 对象
- 内部字段：
{
status: true //布尔型；true||false
}
err：
- 类型：JSON 对象
- 内部字段：
{
code: 0, //数字类型；
//错误码：
0：（用户未授权本应用访问通讯录）
1：（移动失败）
msg: '' //字符串类型；错误信息
}
示例代码
var DVContacts = api.require('DVContacts');
DVContacts.move({
id: '10',
groupId: '20'
}, function(ret, err) {
if (ret) {
api.alert({
msg: JSON.stringify(ret)
})
} else {
api.alert({
msg: JSON.stringify(err)
})
}
});
可用性
iOS系统，Android系统
可提供的1.0.0及更高版本
deleteFromGroup
根据 id 从指定分组删除
deleteFromGroup({params}, callback(ret, err))
params
id：
- 类型：字符
- 描述：联系人 id
groupId：
- 类型：字符
- 描述：联系人的分组 id；若分组不存在则不从分组删除
callback(ret, err)
ret：
- 类型：JSON 对象
- 内部字段：
{
status: true //布尔型；true||false
}
err：
- 类型：JSON 对象
- 内部字段：
{
code: 0, //数字类型；
//错误码：
0：（用户未授权本应用访问通讯录）
1：（删除失败）
msg: '' //字符串类型；错误信息
}
示例代码
var DVContacts = api.require('DVContacts');
DVContacts.deleteFromGroup({
id: '10',
groupId: '20'
}, function(ret, err) {
if (ret) {
api.alert({
msg: JSON.stringify(ret)
})
} else {
api.alert({
msg: JSON.stringify(err)
})
}
});
可用性
iOS系统，Android系统
可提供的1.0.0及更高版本
queryByPage
根据页码查找指定数量的联系人
queryByPage({params}, callback(ret, err))
params
count：
- 类型：数字
- 描述：（可选项）每页联系人的数量，若不传则返回全部联系人，不建议不传本参数
pageIndex：
- 类型：数字
- 描述：（可选项）联系人的分页索引
- 默认值：0
callback(ret, err)
ret：
- 类型：JSON 对象
- 内部字段：
{
status: true, //布尔型；true||false
total: 100, //数字类型；联系人的总数
pages: 10, //数字类型；联系人总页数
contacts: [
id: 0, //数字类型；系统分配的联系人 id
image: '', //字符类型；图片的沙河路径
lastName: '', //字符串类型；联系人姓氏，若该联系人此信息缺少则本字段为undefine
firstName: '', //字符串类型；联系人名字，若该联系人此信息缺少则本字段为undefine
middleName: '', //字符串类型；联系人中间名，若该联系人此信息缺少则本字段为undefine
prefix: '', //字符串类型；名称前缀，若该联系人此信息缺少则本字段为undefine
suffix: '', //字符串类型；名称后缀，若该联系人此信息缺少则本字段为undefine
fullName: '', //字符串类型；联系人全名，若该联系人此信息缺少则本字段为undefine
company: '', //字符串类型；公司
title: '', //字符串类型；职位
phones: [{'':''},{'':''}], //数组类型；联系人电话组成的数组
//内部字段：[{"标签": '号码'}]
emails: [{'':''},{'':''}], //数组类型；邮箱组成的数组
//内部字段：[{"标签": '邮箱'}]
url: [{'':''},{'':''}], //数组类型；URL组成的数组
//内部字段：[{"标签": 'url'}]
address: [{'':{ //数组类型； 地址组成的数组
City: '', //字符串类型；城市
Country: '', //字符串类型；国家
State: '', //字符串类型；省份
Street: '', //字符串类型；街道
ZIP: '100020' //字符串类型；邮编
}}],
dates: [{'':{ //数组类型； 日期组成的数组
year: '', //字符串类型；年；没有设置返回0
month: '', //字符串类型；月
day: '', //字符串类型；日
}}],
contactRelation: [{'':''},{'':''}], //数组类型；关系人组成的数组
//内部字段：[{"标签": '关系人'}]
socialProfiles: [{'':''},{'':''}], //数组类型；社交资料组成的数组
//内部字段：[{"标签": '社交资料'}]
instantMessageAddresses: [{'':''},{'':''}], //数组类型；即时信息组成的数组
//内部字段：[{"标签": '即时信息'}]
note: '', //字符串类型；备注
}]
}
err：
- 类型：JSON 对象
- 内部字段：
{
code: 0 //数字类型；
//错误码：
-1：（用户未授权本应用访问通讯录，Android 平台忽略此错误码）
0：（获取成功）
}
示例代码
var DVContacts = api.require('DVContacts');
DVContacts.queryByPage({
count: 20,
pageIndex: 0
}, function(ret, err) {
if (ret) {
api.alert({
msg: JSON.stringify(ret)
})
} else {
api.alert({
msg: JSON.stringify(err)
})
}
});
可用性
iOS系统，Android系统
可提供的1.0.1及更高版本
openPhonesUI
打开系统通讯录界面，选择单个联系人，返回已选的联系人信息手机号码
openPhonesUI(params, callback(ret,err))
callback(ret,err)
ret:
- 类型：JSON对象
- 内部字段：
{
phone: '', //字符串类型；选择手机号码
}
示例代码
var DVContacts = api.require('DVContacts');
DVContacts.openPhonesUI(function(ret,err) {
api.alert({
msg: JSON.stringify(ret)
})
});
可用性
iOS系统，Android系统
可提供的1.0.4及更高版本