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

是否仍需要帮助? 请保持联络!
最后更新于 2024/10/10