UIChatUnit

open giftsToolListener updateGiftInfo show popupKeyboard hideRecordPanel insertValue setPlaceHolder reset showRecordPanel setEnableAllBtns

概述

UIChatUnit 模块是一个聊天输入框模块，开发者可自定义该输入框的功能。通过 open 接口可在当前 window 底部打开一个输入框，该输入框的生命属于当前 window 所有。当输入框获取焦点后，会自动弹动到软键盘之上。开发者可通过监听输入框距离底部弹动的高度，来改变聊天对话界面的高度。

本模块的主要功能有：

1，自定义表情集：open 接口的 emotionPath 参数

2，自定义输入框最大自适应高度：open 接口的 maxRows 参数

3，输入框占位提示文字：open 接口的 placeholder 参数

4，自定义是否显示附件功能按钮：

5，自定义显示录音按钮：

6，手动弹出、关闭软键盘功能

7，输入框插入、获取当前文本

8，动态刷新附加功能面板

功能详情参考接口参数。

模块接口

open

打开聊天输入框

open({parmas}, callback(ret, err))

chatBox：

  • 类型：JSON 对象
  • 描述：（可选项）聊天输入框配置
  • 内部字段：

styles：

  • 类型：JSON 对象
  • 描述：（可选项）聊天输入框样式配置
  • 内部字段：
  2.     topDivider:{          //(可选项)顶部分割线配置
  3.     width:3,          //(可选项)顶部分割线的粗细，默认：3
  4.         color:'#000'      //(可选项)顶部分割线的颜色；默认：黑色，支持图片设置（fs:// & widget://）
  5.     },
  6.     bgColor: '#D1D1D1',   //（可选项）字符串类型；模块背景色配置，支持rgb、rgba、#；默认：#D1D1D1
  7.     margin: 10,           //（可选项）数字类型；输入框左右边距；默认：10
  8.     topMargin:5,          //（可选项）数字类型；输入框距离顶部的边距；默认：5
  9.     mask: {               //（可选项）JOSN 对象；聊天框以外区域的遮罩层配置，若不传则无遮罩层
  10.        bgColor:'rgba(0,0,0,0.5)',//（可选项）字符串类型；遮罩层背景色配置，支持rgb、rgba、#；默认：rgba(0,0,0,0.5)
  11.     },
  12.     inputBorder:{                  //(可选项)输入框边框设置              
  13.          color:'#FFF5F5F5',        //(可选项)输入框边框颜色；默认：#FFF5F5F5
  14.          width:1,                  //(可选项)输入框边框粗细；默认：1
  15.          radius:3                  //(可选项)输入框边框圆角大小；默认：3
  16.     },
  17.     record:{              //(可选项)录音页面设置
  18.       btnSize: 120,       //(可选项)录音按钮大小设置；默认：120
  19.       tipsColor:'#FFB0B0B0', //(可选项)录音提示文字颜色；默认：#FFB0B0B0
  20.       tipsSize:20            //(可选项)录音提示文字大小：默认：20
  21.     },
  22.     faceBtn:{            //(可选项)输入框右侧表情按钮配置
  23.       btnSize:24,        //(可选项)数字类型；按钮大小，默认：24  
  24.       selectedImg:'widget://image/keyboard.png',//(可选项)字符串类型；表情面板打开后按钮图片设置
  25.       normalImg:'widget://image/face.png'       //(可选项)字符串类型；表情面板关闭后图片设置
  26.     },
  27.     sendBtn:{            // （可选项）发送按钮设置
  28.     w: 40,           // （可选项）按钮的宽度，默认：40
  29.     h: 30,           // （可选项）按钮的高度，默认：30
  30.     corner:5,        // （可选项）按钮圆角大小，默认：0
  31.     titleSize:12,    // （可选项）按钮标题的大小，默认：12
  32.     titleColor:'#000',  // （可选项）按钮标题的颜色，默认：#000
  33.     bg:'#f5f5f5'      // （可选项）按钮背景颜色，默认：#f5f5f5
  34.     }      
  35. }

extrasBtnVisible:

  • 类型：布尔类型
  • 描述：附加按钮是否显示
  • 默认：true

giftConfig：

  • 类型：JSON 对象
  • 描述：（可选项）礼物页面配置
  • 内部字段：
  1. {
  2.     isGroupChat: false,  //（可选项）布尔类型；是否是群聊，默认：false，如果是群聊，点击礼物按钮显示（“选择收礼人”）
  3.     avaterIconPath:'fs://avaterIcon.jpg',//布尔类型；送礼人的头像 ***该参数只有在isGroupChat为false时有效***
  4.     nickText:'送给【昵称】' //布尔类型；收礼人的昵称 ***该参数只有在isGroupChat为false时有效***
  5. }

tools：

  • 类型：JSON 数组
  • 描述：聊天输入框下工具栏配置
  • 内部字段：
  1. [{
  2.     icon: '',  //字符串类型；常态下的图标，要求本地路径（fs://、widget://）
  3.     title:'录音',

emotionPath：

  • 类型：字符串
  • 描述：自定义表情文件夹（表情图片所在的文件夹，须同时包含一个与该文件夹同名的.json配置文件）的路径（本地路径，fs://、widget://）。.json文件内的 name 值必须与表情文件夹内表情图片名对应。另附：
  • .json配置文件格式如下：
  1. [
  2.    {"name": "Expression_11","text": "[尴尬]"},
  3.     {"name": "Expression_12","text": "[发怒]"},
  4.     {"name": "Expression_13","text": "[调皮]"},
  5.     {"name": "Expression_14","text": "[呲牙]"},
  6.     {"name": "Expression_15","text": "[惊讶]"},
  7.     {"name": "Expression_16","text": "[难过]"},
  8.     {"name": "Expression_17","text": "[酷]"},
  9.     {"name": "Expression_18","text": "[冷汗]"},
  10.     {"name": "Expression_19","text": "[抓狂]"},
  11.     {"name": "Expression_20","text": "[吐]"}
  12. ]

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.     eventType: 'show',  //字符串类型；回调的事件类型，
  3.                         //取值范围：
  4.                         //show：模块打开成功并显示在屏幕上
  5.                         //send：用户点击表情面板、键盘面板（在android 平台上表示输入框右边发送按钮）发送按钮
  6.     msg: ''             //字符串类型；当 eventType 为 send 时，此参数返回输入框的内容，否则无返回值
  7.     index: 0           // 数字类型；点击工具栏按钮回调
  8. }

示例代码

  1. var UIChatUnit = api.require('UIChatUnit');
  2. UIChatUnit.open({
  3.     chatBox: {
  4.         placeholder: '聊天内容',     
  5.         autoFocus: false,  
  6.         maxRows: 6     
  7.     },
  8.     styles: {
  9.         bgColor: '#D1D1D1',   
  10.         margin: 10,           
  11.         mask: {               
  12.            bgColor:'rgba(0,0,0,0.5)'
  13.         }             
  14.     },
  15.     tools: [{
  16.     icon: 'widget://res/record.png',  
  17.     title:'录音'},{
  18.     icon: 'widget://res/video.png',  
  19.     title:'视频'}
  20.     ],
  21.     emotions:['widget://res/emotions/basic','widget://res/emotions/append1','widget://res/emotions/append2']
  22. }, function(ret) {
  24.         api.alert({msg:JSON.stringify(ret)});
  25.     } 
  26. });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

recordPanelListener

录音面板监听

recordPanelListener(callback(ret))

callback(ret)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.     state:'press'       //字符串类型；录音按钮的状态
  3. }
  • state取值范围：
    • press 按下
    • release 抬起
    • cancel 取消
    • shortTime 按下时间不超过1秒时回调

示例代码

  1. var UIChatUnit = api.require('UIChatUnit');
  2. UIChatUnit.recordPanelListener(function(ret){
  3.     alert(JSON.stringify(ret));
  4. });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

giftsToolListener

点击选择收礼人监听 注意:仅在isGroupChat为true的情况下有效

giftsToolListener(callback(ret))

callback(ret)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.     eventType:'chooseUser'       //字符串类型；点击选的收礼人触发 (只有在isGroupChat为true的情况下有效)
  3. }

示例代码

  1. var UIChatUnit = api.require('UIChatUnit');
  2. UIChatUnit.giftsToolListener(function(ret){
  3.     alert(JSON.stringify(ret));
  4. });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

setGiftDatas

设置礼物数据

setGiftDatas({params}, callback(ret))

params

styles：

  • 类型：JSON 对象

  • 描述：（可选项）附加功能面板按钮样式配置

  • 内部字段：
  1. {
  2.     row: 2,            //（可选项）数字类型；每页显示按钮行数；默认：2
  3.     column: 4,         //（可选项）数字类型；每页显示按钮的列数；默认：4
  4.     iconSize: 30,      //（可选项）数字类型；按钮图标大小；默认：30
  5.     giftNameSize: 13,     //（可选项）数字类型；按钮下标题文字大小；默认：13
  6.     giftNameColor: '',     //（可选项）字符串类型；按钮下标题文字颜色；默认：#000
  7.     priceSize:10,          //（可选项）字符串类型；价格文字大小；默认：10
  8.     priceColor:''          //（可选项）字符串类型；价格颜色；默认：#eee
  9. }

buttons：

  • 类型：数组
  • 描述：附加功能面板按钮信息集合，可分页显示
  • 内部字段：

callback(ret)

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.      index: 0     //数字类型；用户点击按钮的索引（从零开始）
  3. }

示例代码

  1. var UIChatUnit = api.require('UIChatUnit');
  2. UIChatUnit.setGiftDatas({
  3.     styles: {
  4.         row: 2,         
  5.         column: 4,         
  6.         iconSize: 30,      
  7.         titleSize: 13,   
  8.         titleColor: ''     
  9.     },
  10.     buttons: [
  11.        {
  12.             normal: 'fs://UIChatField/append1.png',       
  13.             highlight: 'fs://UIChatField/append11.png',    
  14.             title: '电话'       
  15.        },{
  16.             normal: 'fs://UIChatField/append2.png',       
  17.             highlight: 'fs://UIChatField/append21.png',    
  18.             title: '收藏' 
  19.        },{
  20.             normal: 'fs://UIChatField/append3.png',       
  21.             highlight: 'fs://UIChatField/append31.png',    
  22.             title: '发红包' 
  23.        },{
  24.             normal: 'fs://UIChatField/append2.png',       
  25.             highlight: 'fs://UIChatField/append21.png',    
  26.             title: '收藏' 
  27.        },{
  28.             normal: 'fs://UIChatField/append3.png',       
  29.             highlight: 'fs://UIChatField/append31.png',    
  30.             title: '发红包' 
  31.        },{
  32.             normal: 'fs://UIChatField/append2.png',       
  33.             highlight: 'fs://UIChatField/append21.png',    
  34.             title: '收藏' 
  35.        },{
  36.             normal: 'fs://UIChatField/append3.png',       
  37.             highlight: 'fs://UIChatField/append31.png',    
  38.             title: '发红包' 
  39.        },{
  40.             normal: 'fs://UIChatField/append2.png',       
  41.             highlight: 'fs://UIChatField/append21.png',    
  42.             title: '收藏' 
  43.        },{
  44.             normal: 'fs://UIChatField/append3.png',       
  45.             highlight: 'fs://UIChatField/append31.png',    
  46.        },{
  47.             normal: 'fs://UIChatField/append2.png',       
  48.             highlight: 'fs://UIChatField/append21.png',    
  49.             title: '收藏' 
  50.        },{
  51.             normal: 'fs://UIChatField/append3.png',       
  52.             highlight: 'fs://UIChatField/append31.png',    
  53.             title: '发红包' 
  54.        },{
  55.             normal: 'fs://UIChatField/append2.png',       
  56.             highlight: 'fs://UIChatField/append21.png',    
  57.             title: '收藏' 
  58.        }
  60. }, function(ret) {
  61.    api.alert({msg:'点击了第'+ret.index+'个按钮'});
  62. });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

updateGiftInfo

更新礼物信息（在群聊情况下选择群成员返回后可使用该方法更新头像及昵称）

updateGiftInfo({params})

params

avaterPath：

  • 类型：字符串
  • 描述：（可选项）送礼人的头像(支持 widget:// & fs://)

nickText:

  • 类型：字符串
  • 描述：（可选项）收礼人的昵称

示例代码

  1. var UIChatUnit = api.require('UIChatUnit');
  2. UIChatUnit.updateGiftInfo({
  3.     avaterPath:'widget://avater.png',
  4.     nickText:'送给【昵称】'
  5. });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

close

关闭聊天输入框

close()

示例代码

  1. var UIChatUnit = api.require('UIChatUnit');
  2. UIChatUnit.close();

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

show

显示聊天输入框

show()

  1. var UIChatUnit = api.require('UIChatUnit');
  2. UIChatUnit.show();

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

hide

隐藏聊天输入框

hide()

示例代码

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

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

popupKeyboard

弹出键盘

popupKeyboard()

示例代码

  1. var UIChatUnit = api.require('UIChatUnit');
  2. UIChatUnit.popupKeyboard();

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

closeKeyboard

收起键盘

closeKeyboard()

示例代码

  1. var UIChatUnit = api.require('UIChatUnit');
  2. UIChatUnit.closeKeyboard();

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

hideRecordPanel

收起录音面板

hideRecordPanel()

示例代码

  1. var UIChatUnit = api.require('UIChatUnit');
  2. UIChatUnit.hideRecordPanel();

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

value

获取或设置聊天输入框的内容

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

params

msg：

  • 类型：字符串
  • 描述：（可选项）聊天输入框的内容，若不传则返回输入框的值

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.     status: true,        //布尔型；true||false
  3.     msg: ''              //字符串类型；输入框当前内容文本
  4. }

示例代码

  1. var UIChatUnit = api.require('UIChatUnit');
  2. UIChatUnit.value({
  3.     msg: '设置输入框的值'
  4. });
  6. //获取输入框的值
  7. UIChatUnit.value(function(ret, err) {
  8.     if (ret) {
  9.         alert(JSON.stringify(ret));
  10.     } else {
  11.         alert(JSON.stringify(err));
  12.     }
  13. });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

insertValue

向聊天输入框的指定位置插入内容

params

index：

  • 类型：数字
  • 描述：（可选项）待插入内容的起始位置。注意：中文，全角符号均占一个字符长度；索引从0开始，0表示插入到最前面，1表示插入到第一个字符后面，2表示插入到第二个字符后面，以此类推。
  • 默认值：当前输入框的值的长度

msg：

  • 类型：字符串
  • 描述：（可选项）要插入的内容
  • 默认值：’’

示例代码

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

chatBoxListener

添加输入框相关事件的监听

chatBoxListener({params}, callback(ret))

params

name：

  • 类型：字符串
  • 描述：监听的事件类型
  • 取值范围：
    • move：输入框弹动事件
    • change：输入框高度改变事件
    • valueChanged：输入框内容改变事件
    • At：@事件 注意：@功能是通过匹配 @\w+\s，所以务必在@XX后加一个空格

callback(ret)

ret：

  • 类型：JSON 对象
  • 描述：监听事件返回目标值，注意：模块分为三分部分：1，输入框（chatBox）及其所占区域；2，工具栏（tools）；3，键盘（及表情面包、附件功能面板、录音面板、图片选择面板）所占区域
  • 内部字段：
  1. {
  2.     chatBoxHeight: 60,     //数字类型；输入框所占区域的高度，仅当监听 move 和 change 事件时本参数有值
  3.     panelHeight: 300 ,     //数字类型；工具栏下边缘距离屏幕底部（键盘及表情面板、附件功能面板、录音面板、图片选择面板所占区域）的高度，仅当监听 move 和 change 事件时本参数有值
  4.     value: '',              //字符串类型；输入框当前内容，仅当 name 为 valueChanged 时有值
  5.     removedString:'@XXX'    //字符串类型；删除@user时返回；仅当name为 At且触发删除事件时回调
  6.     index:0 //数字类型；删除@XXX的索引；仅当name为 At且触发删除事件时回调
  7. }
  1. var UIChatUnit = api.require('UIChatUnit');
  2. UIChatUnit.chatBoxListener({
  3.         name:'move'
  4. }, function(ret){
  5.     alert(JSON.stringify(ret));
  6. });            
  7. UIChatUnit.chatBoxListener({
  8.            name:'change'
  9. }, function(ret){
  10.     alert(JSON.stringify(ret));
  11. });
  12. UIChatUnit.chatBoxListener({
  13.            name:'valueChanged'
  14. }, function(ret){
  15.     alert(JSON.stringify(ret));
  16. });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

setPlaceholder

重设聊天输入框的占位提示文本

setPlaceholder({params})

params

placeholder：

  • 类型：字符串
  • 描述：（可选项）占位提示文本，若不传或传空则表示清空占位提示内容

示例代码

  1. var UIChatUnit = api.require('UIChatUnit');
  2. UIChatUnit.setPlaceholder({
  3.     placeholder: '修改了占位提示内容'
  4. });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

clearText

清空输入框文本

clearText()

示例代码

  1. var UIChatUnit = api.require('UIChatUnit');
  2. UIChatUnit.clearText();

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

reset

重置模块

reset()

示例代码

  1. var UIChatUnit = api.require('UIChatUnit');
  2. UIChatUnit.reset();

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

showGiftPanel

显示礼物面板

showGiftPanel()

示例代码

  1. var UIChatUnit = api.require('UIChatUnit');
  2. UIChatUnit.showGiftPanel();

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

showRecordPanel

显示录音面板

showRecordPanel()

示例代码

  1. var UIChatUnit = api.require('UIChatUnit');
  2. UIChatUnit.showRecordPanel();

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

getCurrentVisiblePanel

获取当前可见的panel

callback(ret)

ret：

  • 类型：JSON 对象
  • 内部字段:
  • 取值范围：
    • record 录音面板
    • gift 礼物面板
    • emotion 表情面板
    • none 没有显示的面板
  1. {
  2.     panelName: "emotion",        //字符串；录音面板
  3. }

示例代码

  1. var UIChatUnit = api.require('UIChatUnit');
  2. UIChatUnit.getCurrentVisiblePanel(function(ret){
  3.     if(ret.panelName == 'none'){
  4.         // do something
  5.     }
  6. });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

setEnableAllBtns

设置所有按钮可用/不可用

Params

enable:

  • 类型：布尔类型
  • 描述：可用性

callback(ret)

ret：

  • 类型：JSON 对象
  • 内部字段:
  1. {
  2.    status: true        //布尔类型； 设置是否成功
  3. }

示例代码

  1. var UIChatUnit = api.require('UIChatUnit');
  2. UIChatUnit.setEnableAllBtns({
  3.     enable: false
  4. }, function(ret){
  5. });

iOS系统，Android系统