contact

来自于：官方

openContact addContact deleteContact updateContact queryContact addGroup queryContactByKey queryGroups queryContactByGroupId updateGroupName deleteGroup

概述

contact 模块封装了系统通讯录的相关接口，通过此模块可实现对系统通讯录的联系人增、删、改、查操作，将底层负责的访问通讯录代码简单成一个个小接口，让开发者轻松访问通讯录。本模块停止更新，已有优化升级版本 DVContacts

openContact

打开系统通讯录界面

openContact(callback(ret, err))

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.     status:true                 //操作成功状态值
  3.     id:                         //联系人id
  4.     name:                       //联系人姓名，由通讯录里该联系人的姓和名组成
  5.     phones:                     //联系人电话组成的数组，内部字段:[{"标签":"号码"}]
  6.     email:                      //邮箱
  7.     company:                    //公司
  8.     title:                      //职位
  9.     address：
  10.     {
  11.         City:                   //城市
  12.         Country:                //国家
  13.         CountryCode:            //国家缩写
  14.         State:                  //省份
  15.         Street:                 //街道
  16.         ZIP:                    //邮编
  17.     }
  18.     note:                       //备注
  19.     groupId:                    //联系人在通讯录中所属分组的id（为空时表示未分组）
  20.     groupName:                  //所在分组的名字（为空时表示未分组）
  21. }

err：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.     msg               //报错信息
  3. }

示例代码

  1. var contact = api.require('contact');
  2. contact.openContact(function(ret, err) {
  3.     if (ret.status) {
  4.         var array = ret.phones;
  5.         var firstnum = array[0];
  6.         var secondnum = array[1];
  7.         var thirdnum = array[2];
  8.     } else {
  9.         api.alert({ msg: '用户取消' });
  10.     }
  11. });

补充说明

获取联系人信息

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

addContact

往通讯录添加一个联系人

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

params

lastName：

  • 类型：字符串
  • 默认值：未命名
  • 描述：（可选项）联系人姓

firstName：

  • 类型：字符串
  • 默认值：未命名
  • 描述：（可选项）联系人名

groupId：

  • 类型：数字
  • 默认值：无
  • 描述：（可选项）分组id
  • 备注：若不传则表示未分组

phones：

  • 类型：JSON数组对象
  • 默认值：无
  • 描述：（可选项）联系人电话JSON对象组成的数组对象
  • 内部字段：
  1. [{
  2.     label:'',
  3.     phone:''
  4. }]

email：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）联系人邮箱

company：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）联系人公司

title：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）联系人职位

address：

  • 类型：JSON 对象
  • 默认值：无
  • 描述：（可选项）联系人地址组成的JSON对象
  • 内部字段：
  1.     {
  2.         City:                   //（可选项）城市，字符串类型，默认空
  3.         Country:                //（可选项）国家，字符串类型，默认空
  4.         CountryCode:            //（可选项）国家缩写，字符串类型，默认空
  5.         State:                  //（可选项）省份，字符串类型，默认空
  6.         Street:                 //（可选项）街道，字符串类型，默认空
  7.         ZIP:                    //（可选项）邮编，字符串类型，默认空
  8.     }

note：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）联系人备注

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.     status:true           //操作成功状态值
  3. }

示例代码

  1. var contact = api.require('contact');
  2. contact.addContact({
  3.     groupId: 1,
  4.     firstName: '张',
  5.     lastName: '三',
  6.     phones: [{ label: '住宅', phone: '123' }, { label: '工作', phone: '456' }],
  7.     address: {
  8.         Country: '中国',
  9.         State: '北京',
  10.         City: '北京市',
  11.         Street: '鸟巢街',
  12.         ZIP: '100000'
  13.     },
  14.     email: 'zhengcuan.sun@api.com',
  15.     company: '柚子科技',
  16.     title: '工程师',
  17.     note: '无'
  18. }, function(ret, err) {
  19.     if (ret.status) {
  20.         api.alert({ msg: '添加成功' });
  21.     } else {
  22.         api.alert({ msg: err.msg });
  23.     }
  24. });

补充说明

添加一个联系人

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

deleteContact

从通讯录删除多个联系人

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

params

ids：

  • 类型：数组
  • 默认值：无
  • 描述：要删除的联系人的id（数字）组成的数组

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.     status:true           //操作成功状态值
  3. }

示例代码

  1. var contact = api.require('contact');
  2. contact.deleteContact({
  3.     ids: [1, 2]
  4. }, function(ret, err) {
  5.     if (ret.status) {
  6.         api.alert({ msg: '删除成功' });
  7.     } else {
  8.         api.alert({ msg: '删除失败' });
  9.     }
  10. });

补充说明

删除指定联系人信息

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

updateContact

修改通讯录里的一个联系人

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

params

id：

  • 类型：数字
  • 默认值：无
  • 描述：要修改的联系人的id

groupId：

  • 类型：数字
  • 默认值：原值
  • 描述：（可选项）要修改的联系人的分组id
  • 备注：若不传或传空则不移动分组，若id为存在合法值则移动该联系人

lastName：

  • 类型：字符串
  • 默认值：原值
  • 描述：（可选项）联系人的姓

firstName：

  • 类型：字符串
  • 默认值：原值
  • 描述：（可选项）联系人名

phones：

  • 类型：JSON 对象数组
  • 默认值：原值
  • 描述：（可选项）联系人电话组成的JSON对象数组
  • 备注：若不传则不修改此属性
  • 内部字段：[{ “标签”:”号码” }]

email：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）联系人邮箱

company：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）联系人公司

title：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）联系人职位

address：

  • 类型：JSON 对象
  • 默认值：无
  • 描述：（可选项）联系人地址组成的JSON对象
  • 内部字段：
  1.     {
  2.         City:                   //（可选项）城市，字符串类型，默认空
  3.         Country:                //（可选项）国家，字符串类型，默认空
  4.         CountryCode:            //（可选项）国家缩写，字符串类型，默认空
  5.         State:                  //（可选项）省份，字符串类型，默认空
  6.         Street:                 //（可选项）街道，字符串类型，默认空
  7.         ZIP:                    //（可选项）邮编，字符串类型，默认空
  8.     }

note：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）联系人备注

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.     status:true           //操作成功状态值
  3. }

示例代码

  1. var contact = api.require('contact');
  2. contact.updateContact({
  3.     id: 1,
  4.     firstName: '张',
  5.     lastName: '三',
  6.     phones: [{ label: '住宅', phone: '124' }, { label: '工作', phone: '346' }],
  7.     address: {
  8.         Country: '',
  9.         State: '',
  10.         City: '',
  11.         Street: '',
  12.         ZIP: ''
  13.     },
  14.     email: '',
  15.     company: '',
  16.     title: '',
  17.     note: ''
  18. }, function(ret, err) {
  19.     if (ret.status) {
  20.         api.alert({ msg: '修改成功' });
  21.     } else {
  22.         api.alert({ msg: err.msg });
  23.     }
  24. });

补充说明

修改指定联系人信息

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

queryContact

从通讯录查找联系人

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

params

ids：

  • 类型：数组对象
  • 默认值；无
  • 描述：（可选项）要查找的联系人的id（数字）组成的数组
  • 备注：若不传则返回全部联系人信息

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. contacts:                       //数组对象
  2. [{
  3.     status:true                 //操作成功状态值
  4.     id：                        //联系人的id
  5.     name：                      //联系人名字，由通讯录里联系人的姓和名组成
  6.     phones：                    //联系人电话组成的数组，内部字段:[{"标签":"号码"}]
  7.     email：                     //邮箱
  8.     company：                   //公司
  9.     title：                     //职位
  10.     address：
  11.     {
  12.         City:                   //城市
  13.         Country:                //国家
  14.         CountryCode:            //国家缩写
  15.         State:                  //省份
  16.         Street:                 //街道
  17.         ZIP:                    //邮编
  18.     }
  19.     note：                      //备注
  20.     groupId：                   //联系人在通讯录中所属分组的id（为空时表示未分组）
  21.     groupName：                 //所在分组的名字（为空时表示未分组）
  22. }]

示例代码

  1. var contact = api.require('contact');
  2. contact.queryContact({
  3.     ids: [1]
  4. }, function(ret, err) {
  5.     if (ret.status) {
  6.         var array = ret.contacts;
  7.         var first = array[0];
  8.         var arrayPho = first.phones;
  9.         var firstnum = arrayPho[0];
  10.         var secondnum = arrayPho[1];
  11.         var thirdnum = arrayPho[2];
  12.     } else {
  13.         api.alert({ msg: '获取失败' });
  14.     }
  15. });

补充说明

获取指定联系人信息

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

addGroup

创建分组

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

params

name：

  • 类型：字符串
  • 默认值；无
  • 描述：分组名

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.     status:true               //操作成功状态值
  3.     id：                      //创建成功返回分组的id
  4. }

示例代码

  1. var contact = api.require('contact');
  2. contact.addGroup({
  3.     name: '同学'
  4. }, function(ret, err) {
  5.     if (ret.status) {
  6.         api.alert({ msg: '分组创建完成' + '*' + ret.id });
  7.     } else {
  8.         api.alert({ msg: err.msg });
  9.     }
  10. });

补充说明

创建分组

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

queryContactByKey

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

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

params

key：

  • 类型：字符串
  • 默认值；无
  • 描述：要查询的关键字

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. contacts:                       //数组对象
  2. [{
  3.     status:true                 //操作成功状态值
  4.     id：                        //联系人的id
  5.     name：                      //联系人名字，由通讯录里联系人的姓和名组成
  6.     phones：                    //联系人电话组成的数组，内部字段:[{"标签":"号码"}]
  7.     email：                     //邮箱
  8.     company：                   //公司
  9.     title：                     //职位
  10.     address：
  11.     {
  12.         City:                   //城市
  13.         Country:                //国家
  14.         CountryCode:            //国家缩写
  15.         State:                  //省份
  16.         Street:                 //街道
  17.         ZIP:                    //邮编
  18.     }
  19.     note：                      //备注
  20.     groupId：                   //联系人在通讯录中所属分组的id（为空时表示未分组）
  21.     groupName：                 //所在分组的名字（为空时表示未分组）
  22. }]

示例代码

  1. var contact = api.require('contact');
  2. contact.queryContactByKey({
  3.     key: '孙'
  4. }, function(ret, err) {
  5.     if (ret.status) {
  6.         var array = ret.contacts;
  7.         var first = array[0];
  8.         var arrayPho = first.phones;
  9.         var firstnum = arrayPho[0];
  10.         var secondnum = arrayPho[1];
  11.         var thirdnum = arrayPho[2];
  12.     } else {
  13.         api.alert({ msg: '获取失败' });
  14.     }
  15. });

补充说明

根据关键字获取联系人信息

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

queryGroups

获取所有分组信息

queryGroups(callback(ret, err))

callback(ret, err)

ret：

  • 类型：JSON数组对象
  • 内部字段：
  1. {
  2.     groups:                 //分组名所组成的数组
  3.     [{
  4.         name:               //分组名
  5.         id:                 //分组的id 
  6.     }]
  7. }

示例代码

  1. var contact = api.require('contact');
  2. contact.queryGroups(function(ret, err) {
  3.     if (ret.status) {
  4.         var array = ret.groups;
  5.         var first = array[0];
  6.     } else {
  7.         api.alert({ msg: err.msg });
  8.     }
  9. });

补充说明

获取所有分组信息

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

queryContactByGroupId

查找一个分组内的联系人

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

params

id：

  • 类型：字符串对象
  • 默认值；无
  • 描述：（可选项）要查找的分组的id
  • 备注：若不传则则返回全部联系人信息

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.     status:true                 //操作成功状态值
  3.     id:                         //联系人id
  4.     name:                       //联系人姓名，由通讯录里该联系人的姓和名组成
  5.     phones:                     //联系人电话组成的数组，内部字段:[{"标签":"号码"}]
  6.     email:                      //邮箱
  7.     company:                    //公司
  8.     title:                      //职位
  9.     address：
  10.     {
  11.         City:                   //城市
  12.         Country:                //国家
  13.         CountryCode:            //国家缩写
  14.         State:                  //省份
  15.         Street:                 //街道
  16.         ZIP:                    //邮编
  17.     }
  18.     note:                       //备注
  19.     groupId:                    //联系人在通讯录中所属分组的id（为空时表示未分组）
  20.     groupName:                  //所在分组的名字（为空时表示未分组）
  21. }

示例代码

  1. var contact = api.require('contact');
  2. contact.findContact({
  3.     id: 1
  4. }, function(ret, err) {
  5.     if (ret.status) {
  6.         var array = ret.names;
  7.         var first = array[0];
  8.         var arrayPho = first.phones;
  9.         var firstnum = arrayPho[0];
  10.         var secondnum = arrayPho[1];
  11.         var thirdnum = arrayPho[2];
  12.     } else {
  13.         api.alert({ msg: err.msg });
  14.     }
  15. });

补充说明

获取指定分子内联系人信息

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

updateGroupName

修改分组名

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

params

id：

  • 类型：数字
  • 默认值；无
  • 描述：要修改的分组的id

name：

  • 类型：字符串
  • 默认值；无
  • 描述：要修改成为的分组名

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.     status:true           //操作成功状态值
  3. }

示例代码

  1. var contact = api.require('contact');
  2. contact.updateGroupName({
  3.     id: 1,
  4.     name: '同学'
  5. }, function(ret, err) {
  6.     if (ret.status) {
  7.         api.alert({ msg: '分组修改完成' });
  8.     } else {
  9.         api.alert({ msg: err.msg });
  10.     }
  11. });

补充说明

目前iOS暂不支持此接口，可通过删除分组，然后再创建来实现此功能

可用性

Android系统

可提供的1.0.0及更高版本

deleteGroup

删除分组

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

params

id：

  • 类型：数字
  • 默认值；无
  • 描述：要删除的分组的id

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.     status:           //操作成功状态值
  3. }

示例代码

  1. var contact = api.require('contact');
  2. contact.deleteGroup({
  3.     id: 1
  4. }, function(ret, err) {
  5.     if (ret.status) {
  6.         api.alert({ msg: '分组删除完成' });
  7.     } else {
  8.         api.alert({ msg: err.msg });
  9.     }
  10. });

补充说明

删除分组

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本