UIAddressBook

open hide reloadData getSelectedSync

概述

UIAddressBook 展示了一个联系人列表。开发者只需传入数据源，模块会自动将联系人排序，展示出来。列表右侧字母导航条会自动随联系人数量调整。

列表条目（cell）布局如下图所示:

open

打开列表

open({params}, callback(ret))

rect：

  • 类型：JSON 对象
  • 描述：（可选项）模块的位置及尺寸
  • 内部字段：

contacts：

  • 类型：数组对象
  • 描述：列表数据源
  • 内部字段：
  2.        id:'123'，           //字符串类型；id          
  3.        name: '小明',         //字符串类型；条目的标题，不传则不显示
  4.        sex: 'male',          //字符串类型；性别（'male':男，'fmale':女，'ufo':'火星人'）
  5.        img: 'widget://image/head.png'       //字符串类型；头像地址，支持（http://,https://,fs://,widget://）
  6.        role: 1,     //数字类型；是否为群主，默认为1，当role为0时，为群主
  7.        phones:[{'工作', '123123'},{'家庭', '12123133'},{'个人', '1123123'}], //JSON数组类型；联系人的手机号数组
  8.        defaultSel: false           //（可选项）布尔类型；设置默认选中状态，仅当checkBox 为 true 时有效。本参数为 true 时只返回点击事件（eventType 为 defaultSel）而不改变该条目选中状态；默认：false,
  9.        tel1:'1234567890'    //联系人手机号
  10.        userType:0            //数字类型；用户类型（0：进群，1：未进群），默认：0
  11. }]

checkBox：

  • 类型：布尔
  • 描述：（可选项）是否显示复选框
  • 默认：false

singleCheck：

  • 类型：布尔
  • 描述：（可选项）是否显示为单选

bounces：

  • 类型：布尔
  • 描述：（可选项）列表是否有弹动效果
  • 默认：false

coverInfo：

  • 类型：布尔
  • 描述：（可选项）是否遮盖部分信息，该状态时，遮盖姓，以及联系方式第三位以后，最多四位 字符
  • 默认：false

manage：

  • 类型：布尔
  • 描述：（可选项）是否为成员管理，当为成员管理状态时，群主标志位于姓名之后，userType参 数为1时，在更多按钮前显示未进群标志
  • 默认：false

moreIcon：

  • 类型：字符串类型
  • 描述：（可选项）更多按钮图标地址，仅支持本地路径（fs://和widget://）

fixedOn：

  • 类型：字符串
  • 描述：（可选项）模块视图添加到指定 frame 的名字（只指 frame，传 window 无效）
  • 默认：模块依附于当前 window

callback(ret)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.    eventType: 'show', //字符串类型；交互事件类型，取值范围如下：
  3.                       //show：模块打开，数据排序成功显示在屏幕事件
  4.                       //click：用户点击事件，当 checkBox 参数为 true 时，本事件识别为 select
  5.                       //select:点击复选框事件
  6.                       //defaultSel:点击被默认设置为选中项的条目的回调事件
  7.                       //more:点击更多按钮事件，当 checkBox 参数为 true 时，本事件识别为 select
  8.                       //scrollUp:向上滑动事件
  9.                       //scrollDown:向下滑动事件
  10.    contacts: []       //JSON 数组；所选条目的联系人信息，内容同传入的数据一致，仅当 eventType 为 select，且 singleCheck 为 false 时有值
  11.    contact: {}       //JSON 对象；点击条目的联系人信息，内容同传入的数据一致，当 eventType 为 click，more 或者eventType 为 select，且singleCheck为 true 时有值
  12. }

示例代码

  1. var UIAddressBook = api.require('UIAddressBook');
  2. UIAddressBook.open({
  3.     rect:{
  4.        x: 0,
  5.        y: 44,
  6.        w: api.frameWidth,
  8.     },
  9.     contacts:[{     
  10.            id:'1',              
  11.            name: '张小明',        
  12.            sex: 'male',          
  13.            img: 'widget://image/head.png', 
  14.            isGroupOwner: true
  15.         },{
  16.            id:'2',              
  17.            name: '孙小红',        
  18.            sex: 'fmale',          
  19.            img: 'widget://image/head.png', 
  20.            isGroupOwner: false
  21.         },{
  22.            id:'3',              
  23.            name: '李小刚',        
  24.            sex: 'ufo',          
  25.            img: 'widget://image/head.png', 
  26.            isGroupOwner: false
  27.         }],
  28. }, function(ret) {
  29.     if (ret) {
  30.         alert(JSON.stringify(ret));
  31.     } 
  32. });

可用性

iOS系统，Android系统

close

关闭列表模块

close()

示例代码

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

hide

隐藏列表模块，并没有从内存里清除

hide()

示例代码

  1. var UIAddressBook = api.require('UIAddressBook');
  2. UIAddressBook.hide();

iOS系统，Android系统

可提供的1.0.0及更高版本

show

显示已隐藏的列表模块

show()

示例代码

  2. UIAddressBook.show();

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

reloadData

刷新列表数据

reloadData({params})

params

contacts：

  • 类型：数组对象
  • 描述：列表数据源
  • 内部字段：
  1. [{     
  2.        id:'123'，           //字符串类型；id          
  3.        name: '小明',         //字符串类型；条目的标题，不传则不显示
  4.        sex: 'male',          //字符串类型；性别（'male':男，'fmale':女，'ufo':'火星人'）
  5.        img: 'widget://image/head.png'       //字符串类型；头像地址，支持（http://,https://,fs://,widget://）
  6.        role: 1,     //数字类型；是否为群主，默认为1，当role为0时，为群主
  7.        phones:[{'工作', '123123'},{'家庭', '12123133'},{'个人', '1123123'}], //JSON数组类型；联系人的手机号数
  8.        defaultSel: false           //（可选项）布尔类型；设置默认选中状态，仅当checkBox 为 true 时有效，当为 true 时只返回点击事件（eventType 为 defaultSel）而不改变该条目选中状态；默认：false
  9. }]

示例代码

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

setSelected

setSelected({params})

params

selected：

  • 类型：布尔
  • 描述：（可选项）设置/取消选中状态
  • 默认：true（设置为选中状态）

contacts：

  • 类型：数组
  • 描述：要设置为选中状态的联系人id组成的数组
  • 参数示例：[‘191’,’192’,’193’]
  1. var UIAddressBook = api.require('UIAddressBook');
  2. UIAddressBook.reloadData({
  3.     contacts:['191','192','193']
  4. });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

getSelectedSync

获取所有当前选中的联系人信息，同步接口

getSelectedSync()

return

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.    contacts: [{}]     //数组类型；被选中的联系人的信息组成的数组，内部字段通open时传入的一致
  3. }

示例代码

  1. var UIAddressBook = api.require('UIAddressBook');
  2. var ret = UIAddressBook.getSelectedSync();
  3. api.alert(JSON.stringify(ret));

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

setRect

设置列表尺寸

setRect({params})

params

rect：

  • 类型：JSON 对象
  • 描述：（可选项）模块的位置及尺寸
  • 内部字段：

animation：

  • 类型：布尔
  • 描述：（可选项）改变 rect 时，是否带动画效果，暂仅支持 iOS 平台
  • 默认：false

示例代码

  1. var UIAddressBook = api.require('UIAddressBook');
  2. UIAddressBook.setRect({
  3.     rect: {
  4.         x: 0,
  5.         y: 0,
  6.         w: '320',
  7.         h: '400'
  8.     },
  10. });

iOS系统，Android系统

可提供的1.0.0及更高版本

附录

当设置为单选状态时，并将其中一个用户设置为设置默认选中状态，此时如果再次设置选中联系人时（包括默认选中状态的联系人），那么需要显示只有一个默认选中的状态，还是设置一个除此之外的联系人？ 这个问题在android和ios上存在争议，因为技术人员觉得该问题影响可以忽略，则暂时略过，如果以后有强烈的需求要改动，再改动。