UIAddressBook

概述

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

列表条目(cell)布局如下图所示:

图片说明

open

打开列表

open({params}, callback(ret))

params

rect:

  • 类型:JSON 对象
  • 描述:(可选项)插件的位置及尺寸
  • 内部字段:
{
    x: 0,   //(可选项)数字类型;插件左上角的 x 坐标(相对于所属的 Window 或 Frame);默认:0
    y: 0,   //(可选项)数字类型;插件左上角的 y 坐标(相对于所属的 Window 或 Frame);默认:0
    w: 320, //(可选项)数字类型;插件的宽度;默认:所属的 Window 或 Frame 的宽度
    h: 200  //(可选项)数字类型;插件的高度;默认:w * 2.0/3.0
}

bgColor:

  • 类型:JSON 对象
  • 描述:背景颜色
  • 内部字段:
{
    viewBgColor: '#303652',   //(可选项)字符串类型;父视图背景颜色;默认:“#303652”
    cellBgColor: '#4b5475',   //(可选项)字符串类型;每一行的背景颜色;默认:“#4b5475”
    headBgColor: '#303652'//(可选项)字符串类型;每一组头部的背景颜色;默认:“#303652”
}

contacts:

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

checkBox:

  • 类型:布尔
  • 描述:(可选项)是否显示复选框
  • 默认:false

singleCheck:

  • 类型:布尔
  • 描述:(可选项)是否显示为单选
  • 默认:false

bounces:

  • 类型:布尔
  • 描述:(可选项)列表是否有弹动效果
  • 默认:false

coverInfo:

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

manage:

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

moreIcon:

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

fixedOn:

  • 类型:字符串
  • 描述:(可选项)插件视图添加到指定 frame 的名字(只指 frame,传 window 无效)
  • 默认:插件依附于当前 window

callback(ret)

ret:

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

示例代码

var UIAddressBook = api.require('UIAddressBook');
UIAddressBook.open({
    rect:{
       x: 0,
       y: 44,
       w: api.frameWidth,
       h: api.frameHeight - 104
    },
    contacts:[{     
           id:'1',              
           name: '张小明',        
           sex: 'male',  		
           img: 'widget://image/head.png', 
           isGroupOwner: true
        },{
           id:'2',              
           name: '孙小红',        
           sex: 'fmale',  		
           img: 'widget://image/head.png', 
           isGroupOwner: false
        },{
           id:'3',              
           name: '李小刚',        
           sex: 'ufo',  		
           img: 'widget://image/head.png', 
           isGroupOwner: false
        }],
    fixedOn: api.frameName
}, function(ret) {
    if (ret) {
        api.alert({msg: JSON.stringify(ret)});
    } 
});

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

close

关闭列表插件

close()

示例代码

var UIAddressBook = api.require('UIAddressBook');
UIAddressBook.close();

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

hide

隐藏列表插件,并没有从内存里清除

hide()

示例代码

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

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

show

显示已隐藏的列表插件

show()

示例代码

var UIAddressBook = api.require('UIAddressBook');
UIAddressBook.show();

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

reloadData

刷新列表数据

reloadData({params})

params

contacts:

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

示例代码

var UIAddressBook = api.require('UIAddressBook');
UIAddressBook.reloadData({
    contacts:[{     
           id:'1',              
           name: '张明',        
           sex: 'ufo',  		
           img: 'widget://image/head.png', 
           isGroupOwner: false
        },{
           id:'2',              
           name: '孙红',        
           sex: 'male',  		
           img: 'widget://image/head.png', 
           isGroupOwner: true
        },{
           id:'3',              
           name: '李刚',        
           sex: 'fmale',  		
           img: 'widget://image/head.png', 
           isGroupOwner: false
        }]
});

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

setSelected

设置选中的联系人

setSelected({params})

params

selected:

  • 类型:布尔
  • 描述:(可选项)设置/取消选中状态
  • 默认:true(设置为选中状态)

contacts:

  • 类型:数组
  • 描述:要设置为选中状态的联系人id组成的数组
  • 参数示例:['191','192','193']

示例代码

var UIAddressBook = api.require('UIAddressBook');
UIAddressBook.reloadData({
    contacts:['191','192','193']
});

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

getSelectedSync

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

getSelectedSync()

##return

ret:

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

示例代码

var UIAddressBook = api.require('UIAddressBook');
var ret = UIAddressBook.getSelectedSync();
api.api.alert({msg: JSON.stringify(ret)});

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

setRect

设置列表尺寸

setRect({params})

params

rect:

  • 类型:JSON 对象
  • 描述:(可选项)插件的位置及尺寸
  • 内部字段:
{
    x: 0,         //(可选项)数字类型;插件左上角的 x 坐标(相对于所属的 Window 或 Frame);默认:原值
    y: 0,         //(可选项)数字类型;插件左上角的 y 坐标(相对于所属的 Window 或 Frame);默认:原值
    w: 320,       //(可选项)数字类型;插件的宽度;默认:原值
    h: 300        //(可选项)数字类型;插件的高度;默认:原值
}

animation:

  • 类型:布尔
  • 描述:(可选项)改变 rect 时,是否带动画效果,暂仅支持 iOS 平台
  • 默认:false

示例代码

var UIAddressBook = api.require('UIAddressBook');
UIAddressBook.setRect({
    rect: {
        x: 0,
        y: 0,
        w: '320',
        h: '400'
    },
    animation: true
});

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

附录

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

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