contacts
来自于：官方立即使用
select
add
delete
update
move
query
queryByKeyword
queryByPage
createGroup
deleteGroup
queryGroups
queryByGroupId
allContacts
概述
contacts 模块封装了系统通讯录的相关接口；可实现联系人的增、删、改、查的操作，创建、管理分组、移动联系人等功能；用于读取或管理通讯录联系人的数据。注意使用此模块云编译时请添加通讯录访问权限。
注意：本模块已停止更新，推荐使用 DVContacts*
select
打开系统通讯录界面，选择单个联系人，返回已选的联系人信息
select(callback(ret, err))
callback(ret, err)
ret：
- 类型：JSON 对象
- 内部字段：
{
status: true, //布尔型；true||false
id: 0, //数字类型；系统分配的联系人 id
lastName: '', //字符串类型；联系人姓氏，若该联系人此信息缺少则本字段为undefine
firstName: '', //字符串类型；联系人名字，若该联系人此信息缺少则本字段为undefine
middleName: '', //字符串类型；联系人中间名，若该联系人此信息缺少则本字段为undefine
prefix: '', //字符串类型；名称前缀，若该联系人此信息缺少则本字段为undefine
suffix: '', //字符串类型；名称后缀，若该联系人此信息缺少则本字段为undefine
fullName: '', //字符串类型；联系人全名，若该联系人此信息缺少则本字段为undefine
phones: [{'工作': '10086'}], //数组类型；联系人电话组成的数组
//内部字段：[{"标签": '号码'}]
email: '', //字符串类型；邮箱
company: '', //字符串类型；公司
title: '', //字符串类型；职位
address: {
City: '', //字符串类型；城市
Country: '', //字符串类型；国家
State: '', //字符串类型；省份
Street: '', //字符串类型；街道
ZIP: '100020' //字符串类型；邮编
},
note: '', //字符串类型；备注
groupId: 1, //数字类型；联系人在通讯录中所属分组 id
groupName: '' //字符串类型；所在分组的名字
}
err：
- 类型：JSON 对象
- 内部字段：
{
code: 0 //数字类型；
//错误码：
-1：（用户未授权本app访问通讯录）
0：（获取成功）
1：（用户取消）
}
示例代码
var contacts = api.require('contacts');
contacts.select(function(ret, err) {
if (ret) {
alert(JSON.stringify(ret));
} else {
alert(JSON.stringify(err));
}
});
可用性
iOS系统，Android系统
可提供的1.0.0及更高版本
add
向通讯录添加一个联系人，所有参数不可同时为空。
add({params}, callback(ret, err))
params
groupId：
- 类型：数字
- 描述：（可选项）分组 id，若不传则表示未分组
lastName：
- 类型：字符串
- 描述：（可选项）联系人姓氏
firstName：
- 类型：字符串
- 描述：（可选项）联系人名字
middleName：
- 类型：字符串
- 描述：（可选项）联系人中间名
prefix：
- 类型：字符串
- 描述：（可选项）联系人名称前缀
suffix：
- 类型：字符串
- 描述：（可选项）联系人名称后缀
phones：
- 类型：数组
- 描述：（可选项）联系人电话组成的数组
- 内部字段：
//数组类型；内部字段：[{"标签": '号码'}]
[{
'工作': '13512345678'
},{
'家庭': '13512345678'
}]
email：
- 类型：字符串
- 描述：（可选项）联系人邮箱
company：
- 类型：字符串
- 描述：（可选项）联系人公司
title：
- 类型：字符串
- 描述：（可选项）联系人职位
address：
- 类型：JSON 对象
- 描述：（可选项）联系人地址
- 内部字段：
{
City: '', //（可选项）字符串类型；城市；
Country: '', //（可选项）字符串类型；国家；
State: '', //（可选项）字符串类型；省份；
Street: '', //（可选项）字符串类型；街道；
ZIP: '' //（可选项）字符串类型；邮编；
}
note：
- 类型：字符串
- 描述：（可选项）联系人备注
callback(ret, err)
ret：
- 类型：JSON 对象
- 内部字段：
{
status: true, //布尔型；true||false
}
err：
- 类型：JSON 对象
- 内部字段：
{
code: 0 //数字类型；
//错误码：
-1：（用户未授权本app访问通讯录）
0：（添加成功）
1：（分组不存在）
}
示例代码
var contacts = api.require('contacts');
contacts.add({
groupId: 1,
lastName: '张',
firstName: '三丰',
middleName: '太极',
prefix: '他',
suffix: '牛',
phones: [{
'住宅': '12345678'
}, {
'工作': '87654321'
}],
email: 'zhengcuan@api.com',
company: '柚子科技',
title: '工程师',
address: {
Country: '中国',
State: '北京',
City: '北京市',
Street: '鸟巢街',
ZIP: '100000'
},
note: '无'
}, function(ret, err) {
if (ret) {
alert(JSON.stringify(ret));
} else {
alert(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 //数字类型；
//错误码：
-1：（用户未授权本app访问通讯录，Android 平台忽略此错误码）
0：（删除成功）
}
示例代码
var contacts = api.require('contacts');
contacts.delete({
ids: [1, 2]
}, function(ret, err) {
if (ret) {
alert(JSON.stringify(ret));
} else {
alert(JSON.stringify(err));
}
});
可用性
iOS系统，Android系统
可提供的1.0.0及更高版本
update
根据 id 更新通讯录的联系人信息
update({params}, callback(ret, err))
params
id：
- 类型：数字
- 描述：联系人 id
lastName：
- 类型：字符串
- 描述：（可选项）联系人的姓氏
firstName：
- 类型：字符串
- 描述：（可选项）联系人名字
middleName：
- 类型：字符串
- 描述：（可选项）联系人中间名
prefix：
- 类型：字符串
- 描述：（可选项）联系人名称前缀
suffix：
- 类型：字符串
- 描述：（可选项）联系人名称后缀
phones：
- 类型：数组
- 描述：（可选项）联系人电话组成的数组，注意：若本参数不为空，则重置已存在的所有电话及其标签
- 内部字段：
//数组类型；内部字段：[{"标签": '号码'}]
[{
'工作': '10086'
}]
email：
- 类型：字符串
- 描述：（可选项）联系人邮箱
company：
- 类型：字符串
- 描述：（可选项）联系人公司
title：
- 类型：字符串
- 描述：（可选项）联系人职位
address：
- 类型：JSON 对象
- 描述：（可选项）联系人地址
- 内部字段：
{
City: '', //（可选项）字符串类型；城市；
Country: '', //（可选项）字符串类型；国家；
State: '', //（可选项）字符串类型；省份；
Street: '', //（可选项）字符串类型；街道；
ZIP: '' //（可选项）字符串类型；邮编；
}
note：
- 类型：字符串
- 描述：（可选项）联系人备注
callback(ret, err)
ret：
- 类型：JSON 对象
- 内部字段：
{
status: true //布尔型；true||false
}
err：
- 类型：JSON 对象
- 内部字段：
{
code: 0 //数字类型；
//错误码：
-1：（用户未授权本应用访问通讯录）
0：（更新成功）
1：（联系人 id 不存在）
}
示例代码
var contacts = api.require('contacts');
contacts.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) {
alert(JSON.stringify(ret));
} else {
alert(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 //数字类型；
//错误码：
-1：（用户未授权本应用访问通讯录）
0：（移动成功）
1：（联系人 id 不存在）
2：（所传分组 id 不存在）
}
示例代码
var contacts = api.require('contacts');
contacts.move({
id: 10,
groupId: 20
}, function(ret, err) {
if (ret) {
alert(JSON.stringify(ret));
} else {
alert(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
contacts: [{
id: 1, //数字类型；联系人的 id
lastName: '', //字符串类型；联系人姓氏，若该联系人此信息缺少则本字段为undefine
firstName: '', //字符串类型；联系人名字，若该联系人此信息缺少则本字段为undefine
middleName: '', //字符串类型；联系人中间名，若该联系人此信息缺少则本字段为undefine
prefix: '', //字符串类型；名称前缀，若该联系人此信息缺少则本字段为undefine
suffix: '', //字符串类型；名称后缀，若该联系人此信息缺少则本字段为undefine
fullName: '', //字符串类型；联系人全名，若该联系人此信息缺少则本字段为undefine
phones: [{'工作', '123'}], //数组类型；联系人电话组成的数组
//内部字段：[{"标签":"号码"}]
email: '', //字符串类型；邮箱
company: '', //字符串类型；公司
title: '', //字符串类型；职位
address: {
City: '', //字符串类型；城市
Country: '', //字符串类型；国家
State: '', //字符串类型；省份
Street: '', //字符串类型；街道
ZIP: '' //字符串类型；邮编
},
note: '', //字符串类型；备注
groupId: 1, //数字类型；联系人所属分组的 id
groupName: '' //字符串类型；所在分组的名字
}]
}
err：
- 类型：JSON 对象
- 内部字段：
{
code: 0 //数字类型；
//错误码：
-1：（用户未授权本应用访问通讯录，Android 平台忽略此错误码）
0：（获取成功）
}
示例代码
var contacts = api.require('contacts');
contacts.query({
ids: [1, 2]
}, function(ret, err) {
if (ret) {
alert(JSON.stringify(ret));
} else {
alert(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
contacts: [{
id: 1, //数字类型；联系人的 id
lastName: '', //字符串类型；联系人姓氏，若该联系人此信息缺少则本字段为undefine
firstName: '', //字符串类型；联系人名字，若该联系人此信息缺少则本字段为undefine
middleName: '', //字符串类型；联系人中间名，若该联系人此信息缺少则本字段为undefine
prefix: '', //字符串类型；名称前缀，若该联系人此信息缺少则本字段为undefine
suffix: '', //字符串类型；名称后缀，若该联系人此信息缺少则本字段为undefine
fullName: '', //字符串类型；联系人全名，若该联系人此信息缺少则本字段为undefine
phones: [{'工作', '123'}], //数组类型；联系人电话组成的数组
//内部字段：[{"标签":"号码"}]
email: '', //字符串类型；邮箱
company: '', //字符串类型；公司
title: '', //字符串类型；职位
address: {
City: '', //字符串类型；城市
Country: '', //字符串类型；国家
State: '', //字符串类型；省份
Street: '', //字符串类型；街道
ZIP: '' //字符串类型；邮编
},
note: '', //字符串类型；备注
groupId: 1, //数字类型；联系人在通讯录所属分组的 id
groupName: '' //字符串类型；所在分组的名字
}]
}
err：
- 类型：JSON 对象
- 内部字段：
{
code: 0 //数字类型；
//错误码：
-1：（用户未授权本应用访问通讯录，Android 平台忽略此错误码）
0：（获取成功）
}
示例代码
var contacts = api.require('contacts');
contacts.queryByKeyword({
keyword: '孙'
}, function(ret, err) {
if (ret) {
alert(JSON.stringify(ret));
} else {
alert(JSON.stringify(err));
}
});
可用性
iOS系统，Android系统
可提供的1.0.0及更高版本
queryByPage
根据页码查找指定数量的联系人
queryByPage({params}, callback(ret, err))
params
count：
- 类型：数字
- 描述：（可选项）每页联系人的数量，若不传则返回全部联系人，不建议不传本参数
pageIndex：
- 类型：数字
- 描述：（可选项）联系人的分页索引
- 默认值：0
isSort：
- 类型：数字
- 描述：（可选项）是否排序返回
- 默认值：false
callback(ret, err)
ret：
- 类型：JSON 对象
- 内部字段：
{
status: true, //布尔型；true||false
total: 100, //数字类型；联系人的总数
pages: 10, //数字类型；联系人总页数
contacts: [{
id: 1, //数字类型；联系人的 id
lastName: '', //字符串类型；联系人姓氏，若该联系人此信息缺少则本字段为undefine
firstName: '', //字符串类型；联系人名字，若该联系人此信息缺少则本字段为undefine
middleName: '', //字符串类型；联系人中间名，若该联系人此信息缺少则本字段为undefine
prefix: '', //字符串类型；名称前缀，若该联系人此信息缺少则本字段为undefine
suffix: '', //字符串类型；名称后缀，若该联系人此信息缺少则本字段为undefine
fullName: '', //字符串类型；联系人全名，若该联系人此信息缺少则本字段为undefine
phones: [{'工作', '123'}], //数组类型；联系人电话组成的数组
//内部字段：[{"标签":"号码"}]
email: '', //字符串类型；邮箱
company: '', //字符串类型；公司
title: '', //字符串类型；职位
address: {
City: '', //字符串类型；城市
Country: '', //字符串类型；国家
State: '', //字符串类型；省份
Street: '', //字符串类型；街道
ZIP: '' //字符串类型；邮编
},
note: '', //字符串类型；备注
groupId: 1, //数字类型；联系人所属分组的 id
groupName: '' //字符串类型；所在分组的名字
}]
}
err：
- 类型：JSON 对象
- 内部字段：
{
code: 0 //数字类型；
//错误码：
-1：（用户未授权本应用访问通讯录，Android 平台忽略此错误码）
0：（获取成功）
}
示例代码
var contacts = api.require('contacts');
contacts.queryByPage({
count: 20,
pageIndex: 0
}, function(ret, err) {
if (ret) {
alert(JSON.stringify(ret));
} else {
alert(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 //数字类型；
//错误码：
-1：（用户未授权本应用访问通讯录，Android 平台忽略此错误码）
0：（创建成功）
}
示例代码
var contacts = api.require('contacts');
contacts.createGroup({
groupName: '同学'
}, function(ret, err) {
if (ret) {
alert(JSON.stringify(ret));
} else {
alert(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 //数字类型；
//错误码：
-1：（用户未授权本应用访问通讯录，Android 平台忽略此错误码）
0：（删除成功）
1：（分组不存在）
}
示例代码
var contacts = api.require('contacts');
contacts.deleteGroup({
groupId: 1
}, function(ret, err) {
if (ret) {
alert(JSON.stringify(ret));
} else {
alert(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 //数字类型；
//错误码：
-1：（用户未授权本应用访问通讯录，Android 平台忽略此错误码）
0：（获取成功）
}
示例代码
var contacts = api.require('contacts');
contacts.queryGroups(function(ret, err) {
if (ret) {
alert(JSON.stringify(ret));
} else {
alert(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
contacts: [{
id: 1, //数字类型；联系人的 id
lastName: '', //字符串类型；联系人姓氏，若该联系人此信息缺少则本字段为undefine
firstName: '', //字符串类型；联系人名字，若该联系人此信息缺少则本字段为undefine
middleName: '', //字符串类型；联系人中间名，若该联系人此信息缺少则本字段为undefine
prefix: '', //字符串类型；名称前缀，若该联系人此信息缺少则本字段为undefine
suffix: '', //字符串类型；名称后缀，若该联系人此信息缺少则本字段为undefine
fullName: '', //字符串类型；联系人全名，若该联系人此信息缺少则本字段为undefine
phones: [{'工作', '123'}], //数组类型；联系人电话组成的数组
//内部字段：[{"标签":"号码"}]
email: '', //字符串类型；邮箱
company: '', //字符串类型；公司
title: '', //字符串类型；职位
address: {
City: '', //字符串类型；城市
Country: '', //字符串类型；国家
State: '', //字符串类型；省份
Street: '', //字符串类型；街道
ZIP: '' //字符串类型；邮编
},
note: '', //字符串类型；备注
groupId: 1, //数字类型；联系人在通讯录所属分组的 id
groupName: '' //字符串类型；所在分组的名字
}]
}
err：
- 类型：JSON 对象
- 内部字段：
{
code: 0 //数字类型；
//错误码：
-1：（用户未授权本应用访问通讯录，Android 平台忽略此错误码）
0：（获取成功）
1：（分组不存在）
}
示例代码
var contacts = api.require('contacts');
contacts.queryByGroupId({
groupId: 1
}, function(ret, err) {
if (ret) {
alert(JSON.stringify(ret));
} else {
alert(JSON.stringify(err));
}
});
可用性
iOS系统，Android系统
可提供的1.0.0及更高版本
allContacts
注意:该接口仅适用于 iOS9 以上系统，iOS9 以下及 android 系统请使用 queryByPage 接口
获取所有联系人
allContacts(callback(ret, err))
callback(ret, err)
ret：
- 类型：JSON 对象
- 内部字段：
{
status: true, //布尔型；true||false
total: 100, //数字类型；联系人的总数
contacts: [{
lastName: '', //字符串类型；联系人姓氏，若该联系人此信息缺少则本字段不显示
firstName: '', //字符串类型；联系人名字，若该联系人此信息缺少则本字段不显示
middleName: '', //字符串类型；联系人中间名，若该联系人此信息缺少则本字段不显示
prefix: '', //字符串类型；名称前缀，若该联系人此信息缺少则本字段不显示
suffix: '', //字符串类型；名称后缀，若该联系人此信息缺少则本字段不显示
fullName: '', //字符串类型；联系人全名，若该联系人此信息缺少则本字段不显示
phones: [{'家庭':123}], //数组类型；联系人电话组成的数组 //内部字段：[{"家庭":"号码"}]
email: '', //字符串类型；邮箱，若该联系人此信息缺少则本字段不显示
company: '', //字符串类型；公司，若该联系人此信息缺少则本字段不显示
title: '', //字符串类型；职位，若该联系人此信息缺少则本字段不显示
address: {
City: '', //字符串类型；城市，若该联系人此信息缺少则本字段不显示
Country: '', //字符串类型；国家，若该联系人此信息缺少则本字段不显示
State: '', //字符串类型；省份，若该联系人此信息缺少则本字段不显示
Street: '', //字符串类型；街道，若该联系人此信息缺少则本字段不显示
ZIP: '' //字符串类型；邮编，若该联系人此信息缺少则本字段不显示
},
note: '', //字符串类型；备注，若该联系人此信息缺少则本字段不显示
}]
}
err：
- 类型：JSON 对象
- 内部字段：
{
code: 0 //数字类型；
//错误码：
-1：（用户未授权本应用访问通讯录，Android 平台忽略此错误码）
0：（获取成功）
}
示例代码
var contacts = api.require('contacts');
contacts.allContacts({
}, function(ret, err) {
if (ret) {
alert(JSON.stringify(ret));
} else {
alert(JSON.stringify(err));
}
});
可用性
iOS系统
可提供的1.0.0及更高版本