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