UIAddressBook

open

close

hide

show

reloadData

setSelected

getSelectedSync

setRect

概述

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/11/18