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.                                    //内部字段：[{"标签": '邮箱'}]     
  18.         url: [{'':''},{'':''}],    //数组类型；URL组成的数组
  19.                                    //内部字段：[{"标签": 'url'}]
  20.         address: [{'':{             //数组类型； 地址组成的数组
  21.             City: '',                //字符串类型；城市
  22.             Country: '',             //字符串类型；国家
  23.             State: '',               //字符串类型；省份
  24.             Street: '',              //字符串类型；街道
  25.             ZIP: '100020'            //字符串类型；邮编
  26.         }}],
  27.          dates: [{'':{             //数组类型； 日期组成的数组
  28.             year: '',                //字符串类型；年；没有设置返回0
  29.             month: '',             //字符串类型；月
  30.             day: '',               //字符串类型；日
  31.         }}],
  32.         contactRelation: [{'':''},{'':''}], //数组类型；关系人组成的数组
  33.                                            //内部字段：[{"标签": '关系人'}]
  34.          socialProfiles: [{'':''},{'':''}], //数组类型；社交资料组成的数组
  35.                                            //内部字段：[{"标签": '社交资料'}]
  36.          instantMessageAddresses: [{'':''},{'':''}], //数组类型；即时信息组成的数组
  37.                                            //内部字段：[{"标签": '即时信息'}]                                   
  39.         note: '',                    //字符串类型；备注
  40. }

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.                                    //内部字段：[{"标签": '邮箱'}]     
  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.                                            //内部字段：[{"标签": '即时信息'}]                                   
  41.         note: '',                    //字符串类型；备注
  43.     }]
  44. }

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.                                 }]
  66. }, function(ret, err) {
  67.     if (ret) {
  68.         alert(JSON.stringify(ret));
  69.     } else {
  70.         alert(JSON.stringify(err));
  71.     }
  72. });

可用性

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.                                    //内部字段：[{"标签": '邮箱'}]     
  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.                                            //内部字段：[{"标签": '即时信息'}]                                   
  41.         note: '',                    //字符串类型；备注
  43.     }]
  44. }

err：

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

示例代码

  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.                                    //内部字段：[{"标签": '邮箱'}]     
  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.                                            //内部字段：[{"标签": '即时信息'}]                                   
  41.         note: '',                    //字符串类型；备注
  43.     }]
  44. }

err：

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

示例代码

  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.                                    //内部字段：[{"标签": '邮箱'}]     
  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.                                            //内部字段：[{"标签": '即时信息'}]                                   
  41.         note: '',                    //字符串类型；备注
  43.     }]
  44. }

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.                                    //内部字段：[{"标签": '邮箱'}]     
  21.         url: [{'':''},{'':''}],    //数组类型；URL组成的数组
  22.                                    //内部字段：[{"标签": 'url'}]
  23.         address: [{'':{             //数组类型； 地址组成的数组
  24.             City: '',                //字符串类型；城市
  25.             Country: '',             //字符串类型；国家
  26.             State: '',               //字符串类型；省份
  27.             Street: '',              //字符串类型；街道
  28.             ZIP: '100020'            //字符串类型；邮编
  29.         }}],
  30.          dates: [{'':{             //数组类型； 日期组成的数组
  31.             year: '',                //字符串类型；年；没有设置返回0
  32.             month: '',             //字符串类型；月
  33.             day: '',               //字符串类型；日
  34.         }}],
  35.         contactRelation: [{'':''},{'':''}], //数组类型；关系人组成的数组
  36.                                            //内部字段：[{"标签": '关系人'}]
  37.          socialProfiles: [{'':''},{'':''}], //数组类型；社交资料组成的数组
  38.                                            //内部字段：[{"标签": '社交资料'}]
  39.          instantMessageAddresses: [{'':''},{'':''}], //数组类型；即时信息组成的数组
  40.                                            //内部字段：[{"标签": '即时信息'}]                                   
  42.         note: '',                    //字符串类型；备注
  44.     }]
  45.   }

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及更高版本