/ Title: contacts Description: contacts /

来自于：官方

概述

contacts 模块封装了系统通讯录的相关接口；可实现联系人的增、删、改、查的操作，创建、管理分组、移动联系人等功能；用于读取或管理通讯录联系人的数据。contacts 模块是 contact 模块的优化版。注意在 Android 平台上使用此模块云编译时请添加通讯录访问权限

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

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
    groups: [{
        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及更高版本