DVContacts

来自于:APICloud立即使用

openContactsUI allContacts add delete update query queryByKeyword createGroup deleteGroup queryGroups queryByGroupId move deleteFromGroup queryByPage

概述

DVContacts 模块封装了系统通讯录的相关接口;可实现联系人的增、删、改、查的操作,创建、管理分组、移动联系人等功能;用于读取或管理通讯录联系人的数据。
【安卓邮箱支持字段:家庭、工作、个人、其他】
【安卓电话支持字段:家庭、手机、单位、主要、工作电话、工作传真、家庭传真、传呼机、其他】
【安卓地址支持字段:家庭、工作、其他】
【安卓活动日期支持字段:生日、自定义】
【安卓活动日期支持字段:父亲、母亲、 父母、助理、兄弟、子女、朋友、经理、合作伙伴、介绍人、亲属、姐妹、配偶、同居伴侣、自定义】
【安卓即时通讯支持字段:AIM、雅虎、Skype、QQ、ICQ、Jabber、环聊、自定义】

注意使用此模块云编译时请添加通讯录访问权限。

注意:本模块 iOS 平台上最低适配系统版本为 iOS 9.0

openContactsUI

打开系统通讯录界面,选择单个联系人,返回已选的联系人信息

openContactsUI(params, callback(ret,err))

callback(ret,err)

ret:

  • 类型:JSON对象
  • 内部字段:
  1. {
  2. status: true, //布尔型;true||false
  3. id: 0, //数字类型;系统分配的联系人 id
  4. image: '', //字符类型;图片的沙河路径
  5. lastName: '', //字符串类型;联系人姓氏,若该联系人此信息缺少则本字段为undefine
  6. firstName: '', //字符串类型;联系人名字,若该联系人此信息缺少则本字段为undefine
  7. middleName: '', //字符串类型;联系人中间名,若该联系人此信息缺少则本字段为undefine
  8. prefix: '', //字符串类型;名称前缀,若该联系人此信息缺少则本字段为undefine
  9. suffix: '', //字符串类型;名称后缀,若该联系人此信息缺少则本字段为undefine
  10. fullName: '', //字符串类型;联系人全名,若该联系人此信息缺少则本字段为undefine
  11. company: '', //字符串类型;公司
  12. title: '', //字符串类型;职位
  13. phones: [{'':''},{'':''}], //数组类型;联系人电话组成的数组
  14. //内部字段:[{"标签": '号码'}]
  15. emails: [{'':''},{'':''}], //数组类型;邮箱组成的数组
  16. //内部字段:[{"标签": '邮箱'}]
  17. url: [{'':''},{'':''}], //数组类型;URL组成的数组
  18. //内部字段:[{"标签": 'url'}]
  19. address: [{'':{ //数组类型; 地址组成的数组
  20. City: '', //字符串类型;城市
  21. Country: '', //字符串类型;国家
  22. State: '', //字符串类型;省份
  23. Street: '', //字符串类型;街道
  24. ZIP: '100020' //字符串类型;邮编
  25. }}],
  26. dates: [{'':{ //数组类型; 日期组成的数组
  27. year: '', //字符串类型;年;没有设置返回0
  28. month: '', //字符串类型;月
  29. day: '', //字符串类型;日
  30. }}],
  31. contactRelation: [{'':''},{'':''}], //数组类型;关系人组成的数组
  32. //内部字段:[{"标签": '关系人'}]
  33. socialProfiles: [{'':''},{'':''}], //数组类型;社交资料组成的数组
  34. //内部字段:[{"标签": '社交资料'}]
  35. instantMessageAddresses: [{'':''},{'':''}], //数组类型;即时信息组成的数组
  36. //内部字段:[{"标签": '即时信息'}]
  37. note: '', //字符串类型;备注
  38. }

err:

  • 类型:JSON 对象
  • 内部字段:
  1. {
  2. code: 0 //数字类型;
  3. //错误码:
  4. -1:(用户未授权本app访问通讯录)
  5. 0:(获取成功)
  6. 1:(用户取消)
  7. }

示例代码

  1. var DVContacts = api.require('DVContacts');
  2. DVContacts.openContactsUI(function(ret,err) {
  3. if (ret) {
  4. alert(JSON.stringify(ret));
  5. } else {
  6. alert(JSON.stringify(err));
  7. }
  8. });

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

allContacts

获取所有联系人

allContacts(params, callback(ret,err))

callback(ret,err)

ret:

  • 类型:JSON对象
  • 内部字段:
  1. {
  2. status: true, //布尔型;true||false
  3. total: 100, //数字类型;联系人的总数
  4. contacts: [
  5. id: 0, //数字类型;系统分配的联系人 id
  6. image: '', //字符类型;图片的沙河路径
  7. lastName: '', //字符串类型;联系人姓氏,若该联系人此信息缺少则本字段为undefine
  8. firstName: '', //字符串类型;联系人名字,若该联系人此信息缺少则本字段为undefine
  9. middleName: '', //字符串类型;联系人中间名,若该联系人此信息缺少则本字段为undefine
  10. prefix: '', //字符串类型;名称前缀,若该联系人此信息缺少则本字段为undefine
  11. suffix: '', //字符串类型;名称后缀,若该联系人此信息缺少则本字段为undefine
  12. fullName: '', //字符串类型;联系人全名,若该联系人此信息缺少则本字段为undefine
  13. company: '', //字符串类型;公司
  14. title: '', //字符串类型;职位
  15. phones: [{'':''},{'':''}], //数组类型;联系人电话组成的数组
  16. //内部字段:[{"标签": '号码'}]
  17. emails: [{'':''},{'':''}], //数组类型;邮箱组成的数组
  18. //内部字段:[{"标签": '邮箱'}]
  19. url: [{'':''},{'':''}], //数组类型;URL组成的数组
  20. //内部字段:[{"标签": 'url'}]
  21. address: [{'':{ //数组类型; 地址组成的数组
  22. City: '', //字符串类型;城市
  23. Country: '', //字符串类型;国家
  24. State: '', //字符串类型;省份
  25. Street: '', //字符串类型;街道
  26. ZIP: '100020' //字符串类型;邮编
  27. }}],
  28. dates: [{'':{ //数组类型; 日期组成的数组
  29. year: '', //字符串类型;年;没有设置返回0
  30. month: '', //字符串类型;月
  31. day: '', //字符串类型;日
  32. }}],
  33. contactRelation: [{'':''},{'':''}], //数组类型;关系人组成的数组
  34. //内部字段:[{"标签": '关系人'}]
  35. socialProfiles: [{'':''},{'':''}], //数组类型;社交资料组成的数组
  36. //内部字段:[{"标签": '社交资料'}]
  37. instantMessageAddresses: [{'':''},{'':''}], //数组类型;即时信息组成的数组
  38. //内部字段:[{"标签": '即时信息'}]
  39. note: '', //字符串类型;备注
  40. }]
  41. }

err:

  • 类型:JSON 对象
  • 内部字段:
  1. {
  2. code: 0, //数字类型;
  3. //错误码:
  4. 0:(用户未授权本应用访问通讯录,Android 平台忽略此错误码)
  5. 1:(读取错误)
  6. msg: '' //字符串类型;错误信息
  7. }

示例代码

  1. var DVContacts = api.require('DVContacts');
  2. DVContacts.allContacts(function(ret,err) {
  3. if (ret) {
  4. alert(JSON.stringify(ret));
  5. } else {
  6. alert(JSON.stringify(err));
  7. }
  8. });

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

add

向通讯录添加一个联系人,所有参数不可同时为空。添加

add({params}, callback(ret, err))

params

image:

  • 类型:字符串
  • 描述:(可选项)联系人头像,支持widget://、fs://

lastName:

  • 类型:字符串
  • 描述:(可选项)联系人姓氏

firstName:

  • 类型:字符串
  • 描述:(可选项)联系人名字

middleName:

  • 类型:字符串
  • 描述:(可选项)联系人中间名

prefix:

  • 类型:字符串
  • 描述:(可选项)联系人名称前缀

suffix:

  • 类型:字符串
  • 描述:(可选项)联系人名称后缀

company:

  • 类型:字符串
  • 描述:(可选项)联系人公司

title:

  • 类型:字符串
  • 描述:(可选项)联系人职位

phones:

  • 类型:数组
  • 描述:(可选项)联系人电话组成的数组
  • 内部字段:
  1. //数组类型;内部字段:[{"标签": '号码'}]
  2. //标签:iPhone、手机、主要、家庭传真、工作传真、传呼机、其他
  3. [{
  4. 'iPhone': '13512345678'
  5. },{
  6. '手机': '13512345678'
  7. }]

address:

  • 类型:数组对象
  • 描述:(可选项)联系人地址
  • 内部字段:
  1. //标签:家庭、工作、其他
  2. [{'工作':{
  3. City: '', //(可选项)字符串类型;城市;
  4. Country: '', //(可选项)字符串类型;国家;
  5. State: '', //(可选项)字符串类型;省份;
  6. Street: '', //(可选项)字符串类型;街道;
  7. ZIP: '' //(可选项)字符串类型;邮编;
  8. }},
  9. {'家庭':{
  10. City: '', //(可选项)字符串类型;城市;
  11. Country: '', //(可选项)字符串类型;国家;
  12. State: '', //(可选项)字符串类型;省份;
  13. Street: '', //(可选项)字符串类型;街道;
  14. ZIP: '' //(可选项)字符串类型;邮编;
  15. }}]

url:

  • 类型:数组对象
  • 描述:(可选项)URL
  • 内部字段:
  1. //数组类型;内部字段:[{"标签": 'url'}]
  2. //标签:家庭、工作、其他、主页
  3. [{
  4. '工作': 'www.apicloud.com'
  5. },{
  6. '家庭': 'www.apicloud.com'
  7. }]

emails:

  • 类型:数组对象
  • 描述:(可选项)邮箱
  • 内部字段:
  1. //数组类型;内部字段:[{"标签": '邮箱'}]
  2. //标签:家庭、工作、其他、iCloud、主页
  3. [{
  4. '工作': '13512345678@163.com'
  5. },{
  6. '家庭': '13512345678@163.com'
  7. }]

dates:

  • 类型:数组对象
  • 描述:(可选项)日期
  • 内部字段:
  1. //标签:纪念日、其他
  2. [{'纪念日':{ //数组类型; 日期组成的数组
  3. year: 2018, //数字类型;年;没有设置返回0
  4. month: 7, //数字类型;月
  5. day: 27, //数字类型;日
  6. }},
  7. {'其他':{ //数组类型; 日期组成的数组
  8. year: 2018, //数字类型;年;没有设置返回0
  9. month: 7, //数字类型;月
  10. day: 27, //数字类型;日
  11. }}]

contactRelation:

  • 类型:数组对象
  • 描述:(可选项)关联人
  • 内部字段:
  1. //数组类型;内部字段:[{"标签": '关联人'}]
  2. //标签:父亲、母亲、父母、兄弟、姐妹、子女、朋友、配偶、伴侣、助理、上司、儿子(此标签仅支持 iOS 11.0及以上)、女儿此标签仅支持 iOS 11.0及以上)
  3. [{
  4. '父亲': ''
  5. },{
  6. '母亲': ''
  7. }]

socialProfiles:

  • 类型:数组对象
  • 描述:(可选项)社交资料
  • 内部字段:
  1. //数组类型;内部字段:[{"标签": '社交资料'}]
  2. //标签:新浪微博、Twitter、Facebook、Flickr、领英、Myspace
  3. [{
  4. 'Twitter': ''
  5. },{
  6. 'Facebook': ''
  7. }]

instantMessageAddresses:

  • 类型:数组对象
  • 描述:(可选项)即时信息
  • 内部字段:
  1. //数组类型;内部字段:[{"标签": '即时信息'}]
  2. //标签:QQ、Skype、MSN、GoogleTalk、Facebook、AIM、Yahoo、ICQ、Jabber、GaduGadu
  3. [{
  4. 'QQ': ''
  5. },{
  6. 'ICQ': ''
  7. }]

note:

  • 类型:字符串
  • 描述:(可选项)联系人备注

callback(ret, err)

ret:

  • 类型:JSON 对象
  • 内部字段:
  1. {
  2. status: true, //布尔型;true||false
  3. }

err:

  • 类型:JSON 对象
  • 内部字段:
  1. {
  2. code: 0, //数字类型;
  3. //错误码:
  4. 0:(用户未授权本应用访问通讯录,Android 平台忽略此错误码)
  5. 1:(添加错误)
  6. msg: '' //字符串类型;错误信息
  7. }

示例代码

  1. var VDVContacts = api.require('DVContacts');
  2. DVContacts.add({
  3. lastName: '张',
  4. firstName: '三丰',
  5. middleName: '太极',
  6. prefix: '他',
  7. suffix: '牛',
  8. company: '柚子科技',
  9. title: '工程师',
  10. note: '无',
  11. phones:[{
  12. '工作': '13512345678'
  13. },{
  14. '家庭': '13512345678'
  15. }],
  16. address:[{'工作':{
  17. City: '', //(可选项)字符串类型;城市;
  18. Country: '', //(可选项)字符串类型;国家;
  19. State: '', //(可选项)字符串类型;省份;
  20. Street: '', //(可选项)字符串类型;街道;
  21. ZIP: '' //(可选项)字符串类型;邮编;
  22. }},
  23. {'家庭':{
  24. City: '', //(可选项)字符串类型;城市;
  25. Country: '', //(可选项)字符串类型;国家;
  26. State: '', //(可选项)字符串类型;省份;
  27. Street: '', //(可选项)字符串类型;街道;
  28. ZIP: '' //(可选项)字符串类型;邮编;
  29. }}],
  30. url:[{
  31. '工作': 'www.apicloud.com'
  32. },{
  33. '家庭': 'www.apicloud.com'
  34. }],
  35. emails:[{
  36. '工作': '13512345678@163.com'
  37. },{
  38. '家庭': '13512345678@163.com'
  39. }],
  40. dates:[{'纪念日':{ //数组类型; 日期组成的数组
  41. year: '', //字符串类型;年;没有设置返回0
  42. month: '', //字符串类型;月
  43. day: '', //字符串类型;日
  44. }},
  45. {'其他':{ //数组类型; 日期组成的数组
  46. year: '', //字符串类型;年;没有设置返回0
  47. month: '', //字符串类型;月
  48. day: '', //字符串类型;日
  49. }}],
  50. contactRelation:[{
  51. '父亲': ''
  52. },{
  53. '母亲': ''
  54. }],
  55. socialProfiles:[{
  56. 'Twitter': ''
  57. },{
  58. 'Facebook': ''
  59. }],
  60. instantMessageAddresses:[{
  61. 'QQ': ''
  62. },{
  63. 'ICQ': ''
  64. }]
  65. }, function(ret, err) {
  66. if (ret) {
  67. alert(JSON.stringify(ret));
  68. } else {
  69. alert(JSON.stringify(err));
  70. }
  71. });

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

delete

从通讯录删除一个或多个联系人

delete({params}, callback(ret, err))

params

ids:

  • 类型:数组, 数组元素为整型
  • 描述:联系人的 id 组成的数组,若传入的 id 不存在,则忽略此id

callback(ret, err)

ret:

  • 类型:JSON 对象
  • 内部字段:
  1. {
  2. status: true //布尔型;true||false
  3. }

err:

  • 类型:JSON 对象
  • 内部字段:
  1. {
  2. code: 0, //数字类型;
  3. //错误码:
  4. 0:(用户未授权本应用访问通讯录,Android 平台忽略此错误码)
  5. 1:(删除错误)
  6. msg: '' //字符串类型;错误信息
  7. }

示例代码

  1. var DVContacts = api.require('DVContacts');
  2. DVContacts.delete({
  3. ids: [1, 2]
  4. }, function(ret, err) {
  5. if (ret) {
  6. alert(JSON.stringify(ret));
  7. } else {
  8. alert(JSON.stringify(err));
  9. }
  10. });

可用性

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:

  • 类型:数组
  • 描述:(可选项)联系人电话组成的数组
  • 内部字段:
  1. //数组类型;内部字段:[{"标签": '号码'}]
  2. //标签:iPhone、手机、主要、家庭传真、工作传真、传呼机、其他
  3. [{
  4. 'iPhone': '13512345678'
  5. },{
  6. '手机': '13512345678'
  7. }]

address:

  • 类型:数组对象
  • 描述:(可选项)联系人地址
  • 内部字段:
  1. //标签:家庭、工作、其他
  2. {'工作':{
  3. City: '', //(可选项)字符串类型;城市;
  4. Country: '', //(可选项)字符串类型;国家;
  5. State: '', //(可选项)字符串类型;省份;
  6. Street: '', //(可选项)字符串类型;街道;
  7. ZIP: '' //(可选项)字符串类型;邮编;
  8. },
  9. '家庭':{
  10. City: '', //(可选项)字符串类型;城市;
  11. Country: '', //(可选项)字符串类型;国家;
  12. State: '', //(可选项)字符串类型;省份;
  13. Street: '', //(可选项)字符串类型;街道;
  14. ZIP: '' //(可选项)字符串类型;邮编;
  15. }}

url:

  • 类型:数组对象
  • 描述:(可选项)URL
  • 内部字段:
  1. //数组类型;内部字段:[{"标签": 'url'}]
  2. //标签:家庭、工作、其他、主页
  3. [{
  4. '工作': 'www.apicloud.com'
  5. },{
  6. '家庭': 'www.apicloud.com'
  7. }]

emails:

  • 类型:数组对象
  • 描述:(可选项)邮箱
  • 内部字段:
  1. //数组类型;内部字段:[{"标签": '邮箱'}]
  2. //标签:家庭、工作、其他、iCloud、主页
  3. [{
  4. '工作': '13512345678@163.com'
  5. },{
  6. '家庭': '13512345678@163.com'
  7. }]

dates:

  • 类型:数组对象
  • 描述:(可选项)日期
  • 内部字段:
  1. //标签:纪念日、其他
  2. {'纪念日':{ //数组类型; 日期组成的数组
  3. year: 2018, //数字类型;年;没有设置返回0
  4. month: 7, //数字类型;月
  5. day: 27, //数字类型;日
  6. },
  7. '其他':{ //数组类型; 日期组成的数组
  8. year: 2018, //数字类型;年;没有设置返回0
  9. month: 7, //数字类型;月
  10. day: 27, //数字类型;日
  11. }}

contactRelation:

  • 类型:数组对象
  • 描述:(可选项)关联人【仅ios支持】
  • 内部字段:
  1. //数组类型;内部字段:[{"标签": '关联人'}]
  2. //标签:父亲、母亲、父母、兄弟、姐妹、子女、朋友、配偶、伴侣、助理、上司、儿子(此标签仅支持 iOS 11.0及以上)、女儿此标签仅支持 iOS 11.0及以上)
  3. [{
  4. '父亲': ''
  5. },{
  6. '母亲': ''
  7. }]

socialProfiles:

  • 类型:数组对象
  • 描述:(可选项)社交资料【仅ios支持】
  • 内部字段:
  1. //数组类型;内部字段:[{"标签": '社交资料'}]
  2. //标签:新浪微博、Twitter、Facebook、Flickr、领英、Myspace
  3. [{
  4. 'Twitter': ''
  5. },{
  6. 'Facebook': ''
  7. }]

instantMessageAddresses:

  • 类型:数组对象
  • 描述:(可选项)即时信息
  • 内部字段:
  1. //数组类型;内部字段:[{"标签": '即时信息'}]
  2. //标签:QQ、Skype、MSN、GoogleTalk、Facebook、AIM、Yahoo、ICQ、Jabber、GaduGadu
  3. [{
  4. 'QQ': ''
  5. },{
  6. 'ICQ': ''
  7. }]

note:

  • 类型:字符串
  • 描述:(可选项)联系人备注

callback(ret, err)

ret:

  • 类型:JSON 对象
  • 内部字段:
  1. {
  2. status: true //布尔型;true||false
  3. }

err:

  • 类型:JSON 对象
  • 内部字段:
  1. {
  2. code: 0, //数字类型;
  3. //错误码:
  4. 0:(用户未授权本应用访问通讯录)
  5. 1:(更新错误)
  6. msg: '' //字符串类型;错误信息
  7. }

示例代码

  1. var DVContacts = api.require('DVContacts');
  2. DVContacts.update({
  3. id: 1,
  4. lastName: '李',
  5. firstName: '四',
  6. middleName: 'Cloud',
  7. prefix: 'API',
  8. suffix: '柚子',
  9. phones: [{
  10. '住宅': '12345678'
  11. }, {
  12. '工作': '87654321'
  13. }],
  14. email: 'zhengcuan@api.com',
  15. company: '柚子科技',
  16. title: '工程师',
  17. address: {
  18. Country: '中国',
  19. State: '北京',
  20. City: '北京市',
  21. Street: '鸟巢街',
  22. ZIP: '100000'
  23. },
  24. note: '无'
  25. }, function(ret, err) {
  26. if (ret) {
  27. alert(JSON.stringify(ret));
  28. } else {
  29. alert(JSON.stringify(err));
  30. }
  31. });

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

query

根据联系人 id 查找联系人

query({params}, callback(ret, err))

params

ids:

  • 类型:数组
  • 描述:联系人 id 组成的数组,若 id 不存在则不处理

callback(ret, err)

ret:

  • 类型:JSON 对象
  • 内部字段:
  1. {
  2. status: true, //布尔型;true||false
  3. total: 100, //数字类型;联系人的总数
  4. contacts: [
  5. id: 0, //数字类型;系统分配的联系人 id
  6. image: '', //字符类型;图片的沙河路径
  7. lastName: '', //字符串类型;联系人姓氏,若该联系人此信息缺少则本字段为undefine
  8. firstName: '', //字符串类型;联系人名字,若该联系人此信息缺少则本字段为undefine
  9. middleName: '', //字符串类型;联系人中间名,若该联系人此信息缺少则本字段为undefine
  10. prefix: '', //字符串类型;名称前缀,若该联系人此信息缺少则本字段为undefine
  11. suffix: '', //字符串类型;名称后缀,若该联系人此信息缺少则本字段为undefine
  12. fullName: '', //字符串类型;联系人全名,若该联系人此信息缺少则本字段为undefine
  13. company: '', //字符串类型;公司
  14. title: '', //字符串类型;职位
  15. phones: [{'':''},{'':''}], //数组类型;联系人电话组成的数组
  16. //内部字段:[{"标签": '号码'}]
  17. emails: [{'':''},{'':''}], //数组类型;邮箱组成的数组
  18. //内部字段:[{"标签": '邮箱'}]
  19. url: [{'':''},{'':''}], //数组类型;URL组成的数组
  20. //内部字段:[{"标签": 'url'}]
  21. address: [{'':{ //数组类型; 地址组成的数组
  22. City: '', //字符串类型;城市
  23. Country: '', //字符串类型;国家
  24. State: '', //字符串类型;省份
  25. Street: '', //字符串类型;街道
  26. ZIP: '100020' //字符串类型;邮编
  27. }}],
  28. dates: [{'':{ //数组类型; 日期组成的数组
  29. year: '', //字符串类型;年;没有设置返回0
  30. month: '', //字符串类型;月
  31. day: '', //字符串类型;日
  32. }}],
  33. contactRelation: [{'':''},{'':''}], //数组类型;关系人组成的数组
  34. //内部字段:[{"标签": '关系人'}]
  35. socialProfiles: [{'':''},{'':''}], //数组类型;社交资料组成的数组
  36. //内部字段:[{"标签": '社交资料'}]
  37. instantMessageAddresses: [{'':''},{'':''}], //数组类型;即时信息组成的数组
  38. //内部字段:[{"标签": '即时信息'}]
  39. note: '', //字符串类型;备注
  40. }]
  41. }

err:

  • 类型:JSON 对象
  • 内部字段:
  1. {
  2. code: 0, //数字类型;
  3. //错误码:
  4. 0:(用户未授权本应用访问通讯录,Android 平台忽略此错误码)
  5. 1:(获取错误)
  6. msg: '' //字符串类型;错误信息
  7. }

示例代码

  1. var DVContacts = api.require('DVContacts');
  2. DVContacts.query({
  3. ids: [1, 2]
  4. }, function(ret, err) {
  5. if (ret) {
  6. alert(JSON.stringify(ret));
  7. } else {
  8. alert(JSON.stringify(err));
  9. }
  10. });

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

queryByKeyword

根据关键字从通讯录查找联系人

queryByKeyword({params}, callback(ret, err))

params

keyword:

  • 类型:字符串
  • 描述:要查询的关键字 注意:仅搜索 lastName 和 firstName 包含的关键字

callback(ret, err)

ret:

  • 类型:JSON 对象
  • 内部字段:
  1. {
  2. status: true, //布尔型;true||false
  3. total: 100, //数字类型;联系人的总数
  4. contacts: [
  5. id: 0, //数字类型;系统分配的联系人 id
  6. image: '', //字符类型;图片的沙河路径
  7. lastName: '', //字符串类型;联系人姓氏,若该联系人此信息缺少则本字段为undefine
  8. firstName: '', //字符串类型;联系人名字,若该联系人此信息缺少则本字段为undefine
  9. middleName: '', //字符串类型;联系人中间名,若该联系人此信息缺少则本字段为undefine
  10. prefix: '', //字符串类型;名称前缀,若该联系人此信息缺少则本字段为undefine
  11. suffix: '', //字符串类型;名称后缀,若该联系人此信息缺少则本字段为undefine
  12. fullName: '', //字符串类型;联系人全名,若该联系人此信息缺少则本字段为undefine
  13. company: '', //字符串类型;公司
  14. title: '', //字符串类型;职位
  15. phones: [{'':''},{'':''}], //数组类型;联系人电话组成的数组
  16. //内部字段:[{"标签": '号码'}]
  17. emails: [{'':''},{'':''}], //数组类型;邮箱组成的数组
  18. //内部字段:[{"标签": '邮箱'}]
  19. url: [{'':''},{'':''}], //数组类型;URL组成的数组
  20. //内部字段:[{"标签": 'url'}]
  21. address: [{'':{ //数组类型; 地址组成的数组
  22. City: '', //字符串类型;城市
  23. Country: '', //字符串类型;国家
  24. State: '', //字符串类型;省份
  25. Street: '', //字符串类型;街道
  26. ZIP: '100020' //字符串类型;邮编
  27. }}],
  28. dates: [{'':{ //数组类型; 日期组成的数组
  29. year: '', //字符串类型;年;没有设置返回0
  30. month: '', //字符串类型;月
  31. day: '', //字符串类型;日
  32. }}],
  33. contactRelation: [{'':''},{'':''}], //数组类型;关系人组成的数组
  34. //内部字段:[{"标签": '关系人'}]
  35. socialProfiles: [{'':''},{'':''}], //数组类型;社交资料组成的数组
  36. //内部字段:[{"标签": '社交资料'}]
  37. instantMessageAddresses: [{'':''},{'':''}], //数组类型;即时信息组成的数组
  38. //内部字段:[{"标签": '即时信息'}]
  39. note: '', //字符串类型;备注
  40. }]
  41. }

err:

  • 类型:JSON 对象
  • 内部字段:
  1. {
  2. code: 0, //数字类型;
  3. //错误码:
  4. 0:(用户未授权本应用访问通讯录,Android 平台忽略此错误码)
  5. 1:(获取错误)
  6. msg: '' //字符串类型;错误信息
  7. }

示例代码

  1. var DVContacts = api.require('DVContacts');
  2. DVContacts.queryByKeyword({
  3. keyword: '王'
  4. }, function(ret, err) {
  5. if (ret) {
  6. alert(JSON.stringify(ret));
  7. } else {
  8. alert(JSON.stringify(err));
  9. }
  10. });

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

createGroup

创建分组

createGroup({params}, callback(ret, err))

params

groupName:

  • 类型:字符串
  • 描述:分组名

callback(ret, err)

ret:

  • 类型:JSON 对象
  • 内部字段:
  1. {
  2. status: true, //布尔型;true||false
  3. groupId: 1 //创建成功返回的分组 id
  4. }

err:

  • 类型:JSON 对象
  • 内部字段:
  1. {
  2. code: 0, //数字类型;
  3. //错误码:
  4. 0:(用户未授权本应用访问通讯录,Android 平台忽略此错误码)
  5. 1:创建失败
  6. msg: '' //字符串类型;错误信息
  7. }

示例代码

  1. var DVContacts = api.require('DVContacts');
  2. DVContacts.createGroup({
  3. groupName: '同学'
  4. }, function(ret, err) {
  5. if (ret) {
  6. alert(JSON.stringify(ret));
  7. } else {
  8. alert(JSON.stringify(err));
  9. }
  10. });

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

deleteGroup

删除分组,只删除分组,不删除其中的联系人

deleteGroup({params}, callback(ret, err))

params

groupId:

  • 类型:字符
  • 描述:分组 id

callback(ret, err)

ret:

  • 类型:JSON 对象
  • 内部字段:
  1. {
  2. status: true //布尔型;true||false
  3. }

err:

  • 类型:JSON 对象
  • 内部字段:
  1. {
  2. code: 0, //数字类型;
  3. //错误码:
  4. 0:(用户未授权本应用访问通讯录,Android 平台忽略此错误码)
  5. 1:(删除失败)
  6. msg: '' //字符串类型;错误信息
  7. }

示例代码

  1. var DVContacts = api.require('DVContacts');
  2. DVContacts.deleteGroup({
  3. groupId: ''
  4. }, function(ret, err) {
  5. if (ret) {
  6. alert(JSON.stringify(ret));
  7. } else {
  8. alert(JSON.stringify(err));
  9. }
  10. });

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

queryGroups

获取所有分组信息

queryGroups(callback(ret, err))

callback(ret, err)

ret:

  • 类型:JSON 对象
  • 内部字段:
  1. {
  2. status: true, //布尔型;true||false
  3. groups: [{
  4. name: '', //字符串类型;分组名
  5. id: 1 //数字类型;分组 id
  6. }]
  7. }

err:

  • 类型:JSON 对象
  • 内部字段:
  1. {
  2. code: 0, //数字类型;
  3. //错误码:
  4. 0:(用户未授权本应用访问通讯录,Android 平台忽略此错误码)
  5. 1:(获取失败)
  6. msg: '' //字符串类型;错误信息
  7. }

示例代码

  1. var DVContacts = api.require('DVContacts');
  2. DVContacts.queryGroups(function(ret, err) {
  3. if (ret) {
  4. alert(JSON.stringify(ret));
  5. } else {
  6. alert(JSON.stringify(err));
  7. }
  8. });

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

queryByGroupId

根据分组 id 查找联系人

queryByGroupId({params}, callback(ret, err))

params

groupId:

  • 类型:数字
  • 描述:(可选项)要查找的分组 id

callback(ret, err)

ret:

  • 类型:JSON 对象
  • 内部字段:
  1. {
  2. status: true, //布尔型;true||false
  3. total: 100, //数字类型;联系人的总数
  4. contacts: [
  5. id: 0, //数字类型;系统分配的联系人 id
  6. image: '', //字符类型;图片的沙河路径
  7. lastName: '', //字符串类型;联系人姓氏,若该联系人此信息缺少则本字段为undefine
  8. firstName: '', //字符串类型;联系人名字,若该联系人此信息缺少则本字段为undefine
  9. middleName: '', //字符串类型;联系人中间名,若该联系人此信息缺少则本字段为undefine
  10. prefix: '', //字符串类型;名称前缀,若该联系人此信息缺少则本字段为undefine
  11. suffix: '', //字符串类型;名称后缀,若该联系人此信息缺少则本字段为undefine
  12. fullName: '', //字符串类型;联系人全名,若该联系人此信息缺少则本字段为undefine
  13. company: '', //字符串类型;公司
  14. title: '', //字符串类型;职位
  15. phones: [{'':''},{'':''}], //数组类型;联系人电话组成的数组
  16. //内部字段:[{"标签": '号码'}]
  17. emails: [{'':''},{'':''}], //数组类型;邮箱组成的数组
  18. //内部字段:[{"标签": '邮箱'}]
  19. url: [{'':''},{'':''}], //数组类型;URL组成的数组
  20. //内部字段:[{"标签": 'url'}]
  21. address: [{'':{ //数组类型; 地址组成的数组
  22. City: '', //字符串类型;城市
  23. Country: '', //字符串类型;国家
  24. State: '', //字符串类型;省份
  25. Street: '', //字符串类型;街道
  26. ZIP: '100020' //字符串类型;邮编
  27. }}],
  28. dates: [{'':{ //数组类型; 日期组成的数组
  29. year: '', //字符串类型;年;没有设置返回0
  30. month: '', //字符串类型;月
  31. day: '', //字符串类型;日
  32. }}],
  33. contactRelation: [{'':''},{'':''}], //数组类型;关系人组成的数组
  34. //内部字段:[{"标签": '关系人'}]
  35. socialProfiles: [{'':''},{'':''}], //数组类型;社交资料组成的数组
  36. //内部字段:[{"标签": '社交资料'}]
  37. instantMessageAddresses: [{'':''},{'':''}], //数组类型;即时信息组成的数组
  38. //内部字段:[{"标签": '即时信息'}]
  39. note: '', //字符串类型;备注
  40. }]
  41. }

err:

  • 类型:JSON 对象
  • 内部字段:
  1. {
  2. code: 0, //数字类型;
  3. //错误码:
  4. 0:(用户未授权本应用访问通讯录,Android 平台忽略此错误码)
  5. 1:(获取失败)
  6. msg: '' //字符串类型;错误信息
  7. }

示例代码

  1. var DVContacts = api.require('DVContacts');
  2. DVContacts.queryByGroupId({
  3. groupId: 1
  4. }, function(ret, err) {
  5. if (ret) {
  6. alert(JSON.stringify(ret));
  7. } else {
  8. alert(JSON.stringify(err));
  9. }
  10. });

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

move

根据 id 移动联系人至指定分组

move({params}, callback(ret, err))

params

id:

  • 类型:字符
  • 描述:联系人 id

groupId:

  • 类型:字符
  • 描述:联系人的分组 id;若分组不存在则不移动分组

callback(ret, err)

ret:

  • 类型:JSON 对象
  • 内部字段:
  1. {
  2. status: true //布尔型;true||false
  3. }

err:

  • 类型:JSON 对象
  • 内部字段:
  1. {
  2. code: 0, //数字类型;
  3. //错误码:
  4. 0:(用户未授权本应用访问通讯录)
  5. 1:(移动失败)
  6. msg: '' //字符串类型;错误信息
  7. }

示例代码

  1. var DVContacts = api.require('DVContacts');
  2. DVContacts.move({
  3. id: '10',
  4. groupId: '20'
  5. }, function(ret, err) {
  6. if (ret) {
  7. alert(JSON.stringify(ret));
  8. } else {
  9. alert(JSON.stringify(err));
  10. }
  11. });

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

deleteFromGroup

根据 id 从指定分组删除

deleteFromGroup({params}, callback(ret, err))

params

id:

  • 类型:字符
  • 描述:联系人 id

groupId:

  • 类型:字符
  • 描述:联系人的分组 id;若分组不存在则不从分组删除

callback(ret, err)

ret:

  • 类型:JSON 对象
  • 内部字段:
  1. {
  2. status: true //布尔型;true||false
  3. }

err:

  • 类型:JSON 对象
  • 内部字段:
  1. {
  2. code: 0, //数字类型;
  3. //错误码:
  4. 0:(用户未授权本应用访问通讯录)
  5. 1:(删除失败)
  6. msg: '' //字符串类型;错误信息
  7. }

示例代码

  1. var DVContacts = api.require('DVContacts');
  2. DVContacts.deleteFromGroup({
  3. id: '10',
  4. groupId: '20'
  5. }, function(ret, err) {
  6. if (ret) {
  7. alert(JSON.stringify(ret));
  8. } else {
  9. alert(JSON.stringify(err));
  10. }
  11. });

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

queryByPage

根据页码查找指定数量的联系人

queryByPage({params}, callback(ret, err))

params

count:

  • 类型:数字
  • 描述:(可选项)每页联系人的数量,若不传则返回全部联系人,不建议不传本参数

pageIndex:

  • 类型:数字
  • 描述:(可选项)联系人的分页索引
  • 默认值:0

callback(ret, err)

ret:

  • 类型:JSON 对象
  • 内部字段:
  1. {
  2. status: true, //布尔型;true||false
  3. total: 100, //数字类型;联系人的总数
  4. pages: 10, //数字类型;联系人总页数
  5. contacts: [
  6. id: 0, //数字类型;系统分配的联系人 id
  7. image: '', //字符类型;图片的沙河路径
  8. lastName: '', //字符串类型;联系人姓氏,若该联系人此信息缺少则本字段为undefine
  9. firstName: '', //字符串类型;联系人名字,若该联系人此信息缺少则本字段为undefine
  10. middleName: '', //字符串类型;联系人中间名,若该联系人此信息缺少则本字段为undefine
  11. prefix: '', //字符串类型;名称前缀,若该联系人此信息缺少则本字段为undefine
  12. suffix: '', //字符串类型;名称后缀,若该联系人此信息缺少则本字段为undefine
  13. fullName: '', //字符串类型;联系人全名,若该联系人此信息缺少则本字段为undefine
  14. company: '', //字符串类型;公司
  15. title: '', //字符串类型;职位
  16. phones: [{'':''},{'':''}], //数组类型;联系人电话组成的数组
  17. //内部字段:[{"标签": '号码'}]
  18. emails: [{'':''},{'':''}], //数组类型;邮箱组成的数组
  19. //内部字段:[{"标签": '邮箱'}]
  20. url: [{'':''},{'':''}], //数组类型;URL组成的数组
  21. //内部字段:[{"标签": 'url'}]
  22. address: [{'':{ //数组类型; 地址组成的数组
  23. City: '', //字符串类型;城市
  24. Country: '', //字符串类型;国家
  25. State: '', //字符串类型;省份
  26. Street: '', //字符串类型;街道
  27. ZIP: '100020' //字符串类型;邮编
  28. }}],
  29. dates: [{'':{ //数组类型; 日期组成的数组
  30. year: '', //字符串类型;年;没有设置返回0
  31. month: '', //字符串类型;月
  32. day: '', //字符串类型;日
  33. }}],
  34. contactRelation: [{'':''},{'':''}], //数组类型;关系人组成的数组
  35. //内部字段:[{"标签": '关系人'}]
  36. socialProfiles: [{'':''},{'':''}], //数组类型;社交资料组成的数组
  37. //内部字段:[{"标签": '社交资料'}]
  38. instantMessageAddresses: [{'':''},{'':''}], //数组类型;即时信息组成的数组
  39. //内部字段:[{"标签": '即时信息'}]
  40. note: '', //字符串类型;备注
  41. }]
  42. }

err:

  • 类型:JSON 对象
  • 内部字段:
  1. {
  2. code: 0 //数字类型;
  3. //错误码:
  4. -1:(用户未授权本应用访问通讯录,Android 平台忽略此错误码)
  5. 0:(获取成功)
  6. }

示例代码

  1. var DVContacts = api.require('DVContacts');
  2. DVContacts.queryByPage({
  3. count: 20,
  4. pageIndex: 0
  5. }, function(ret, err) {
  6. if (ret) {
  7. alert(JSON.stringify(ret));
  8. } else {
  9. alert(JSON.stringify(err));
  10. }
  11. });

可用性

iOS系统,Android系统

可提供的1.0.1及更高版本