UIChatField

概述

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

本插件的主要功能有：

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

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

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

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

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

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

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

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

功能详情参考接口参数。

#插件接口

open

打开聊天输入框

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

params

chatBox：

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

{
    placeholder: '',       //（可选项）字符串类型；占位提示文本，不传则无占位符
    autoFocus: false,      //（可选项）布尔类型；是否在打开时自动获取焦点，并弹出键盘；默认：false
    maxRows: 6,            //（可选项）数字类型；显示的最大行数（高度自适应），超过最大行数则可上下滚动查看；默认：6
    placeholderColor:'',   //（可选项）字符串类型；占位提示文本颜色；默认：灰色
    textColor:'',          //（可选项）输入框文本颜色；默认：黑色
    inputBgColor:''        //（可选项）输入框背景颜色；默认：#FFF5F5F5
}

styles：

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

{
    topDivider:{          //(可选项)顶部分割线配置
    width:3,          //(可选项)顶部分割线的粗细，默认：3
        color:'#000'      //(可选项)顶部分割线的颜色；默认：黑色，支持图片设置（fs:// & widget://）
    },
    bgColor: '#D1D1D1',   //（可选项）字符串类型；插件背景色配置，支持rgb、rgba、#；默认：#D1D1D1
    margin: 10,           //（可选项）数字类型；输入框左右边距；默认：10
    topMargin:5,          //（可选项）数字类型；输入框距离顶部的边距；默认：5
    mask: {               //（可选项）JOSN 对象；聊天框以外区域的遮罩层配置，若不传则无遮罩层
       bgColor:'rgba(0,0,0,0.5)',//（可选项）字符串类型；遮罩层背景色配置，支持rgb、rgba、#；默认：rgba(0,0,0,0.5)
    },
    inputBorder:{                  //(可选项)输入框边框设置              
         color:'#FFF5F5F5',        //(可选项)输入框边框颜色；默认：#FFF5F5F5
         width:1,                  //(可选项)输入框边框粗细；默认：1
         radius:3                  //(可选项)输入框边框圆角大小；默认：3
    },
    record:{              //(可选项)录音页面设置
      btnSize: 120,       //(可选项)录音按钮大小设置；默认：120
      tipsColor:'#FFB0B0B0', //(可选项)录音提示文字颜色；默认：#FFB0B0B0
      tipsSize:20 ,           //(可选项)录音提示文字大小：默认：20
      imgPath:''          //（可选项）录音按钮背景图片的路径；支持（widget://和fs://）
    },
    faceBtn:{            //(可选项)输入框右侧表情按钮配置
      btnSize:24,        //(可选项)数字类型；按钮大小，默认：24  
      selectedImg:'widget://image/keyboard.png',//(可选项)字符串类型；表情面板打开后按钮图片设置
      normalImg:'widget://image/face.png'       //(可选项)字符串类型；表情面板关闭后图片设置
    }           
}

giftConfig：

类型：JSON 对象
描述：（可选项）礼物页面配置
内部字段：

{
    isGroupChat: false,  //（可选项）布尔类型；是否是群聊，默认：false，如果是群聊，点击礼物按钮显示（“选择收礼人”）
    avaterIconPath:'fs://avaterIcon.jpg',//布尔类型；送礼人的头像 ***该参数只有在isGroupChat为false时有效***
    nickText:'送给【昵称】' //布尔类型；收礼人的昵称 ***该参数只有在isGroupChat为false时有效***
}

tools：

类型：JSON 对象
描述：聊天输入框下工具栏配置
内部字段：

{
    h: 44,          //（可选项）数字类型；工具栏高度；默认：44
    iconSize: 30,   //（可选项）数字类型；工具栏每个按钮的图标大小；默认：30
    recorder: {     //（可选项）JSON 对象；录音按钮配置，若不传则工具栏无录音按钮，本功能需配合recorderListener 接口使用
       normal: '',  //字符串类型；常态下的图标，要求本地路径（fs、widget）
       selected: '' //字符串类型；选中后的图标，要求本地路径（fs、widget），同按下时高亮状态公用同一个图标
    },
    image: {        //（可选项）JSON 对象；选图片按钮配置，若不传则工具栏无选图按钮，本功能需配合imageListener 接口使用
       normal: '',  //字符串类型；常态下的图标，要求本地路径（fs、widget）
       selected: '' //字符串类型；选中后的图标，要求本地路径（fs、widget），同按下时高亮状态公用同一个图标
    },
    video: {        //（可选项）JSON 对象；录像按钮配置，若不传则工具栏无录像按钮，本功能需配合toolsListener 接口使用
       normal: '',  //字符串类型；常态下的图标，要求本地路径（fs、widget）
       selected: '' //字符串类型；选中后的图标，要求本地路径（fs、widget），同按下时高亮状态公用同一个图标
    },
    voiceChat: {       //（可选项）JSON 对象；语音通话按钮配置，若不传则工具栏无红包按钮，本功能需配合toolsListener 接口使用
       normal: '',  //字符串类型；常态下的图标，要求本地路径（fs、widget）
       selected: '' //字符串类型；选中后的图标，要求本地路径（fs、widget），同按下时高亮状态公用同一个图标
    },
    videoChat: {         //（可选项）JSON 对象；视频通话按钮配置，若不传则工具栏无表情按钮，本功能需配合 faceListener、addFace 接口以及 emotions 参数使用
       normal: '',  //字符串类型；常态下的图标，要求本地路径（fs、widget）
       selected: '' //字符串类型；选中后的图标，要求本地路径（fs、widget），同按下时高亮状态公用同一个图标
    },
    fileChoose: {       //（可选项）JSON 对象；文件选择按钮配置，若不传则工具栏无附加按钮，本功能需配合 setAppendButton 接口使用
       normal: '',  //字符串类型；常态下的图标，要求本地路径（fs、widget）
       selected: '' //字符串类型；选中后的图标，要求本地路径（fs、widget），同按下时高亮状态公用同一个图标
    },
    gifts: {       //（可选项）JSON 对象；礼物按钮配置，若不传则工具栏无附加按钮，本功能需配合 setAppendButton 接口使用
       normal: '',  //字符串类型；常态下的图标，要求本地路径（fs、widget）
       selected: '' //字符串类型；选中后的图标，要求本地路径（fs、widget），同按下时高亮状态公用同一个图标
    },
    location: {       //（可选项）JSON 对象；位置发送按钮配置，若不传则工具栏无附加按钮，本功能需配合 setAppendButton 接口使用
       normal: '',  //字符串类型；常态下的图标，要求本地路径（fs、widget）
       selected: '' //字符串类型；选中后的图标，要求本地路径（fs、widget），同按下时高亮状态公用同一个图标
    }
}

emotionPath：

类型：字符串
描述：自定义表情文件夹（表情图片所在的文件夹，须同时包含一个与该文件夹同名的.json配置文件）的路径（本地路径，fs://、widget://）。**.json文件内的 name 值必须与表情文件夹内表情图片名对应。**另附：表情文件夹资源示例
.json配置文件格式如下：

[
   {"name": "Expression_11","text": "[尴尬]"},
    {"name": "Expression_12","text": "[发怒]"},
    {"name": "Expression_13","text": "[调皮]"},
    {"name": "Expression_14","text": "[呲牙]"},
    {"name": "Expression_15","text": "[惊讶]"},
    {"name": "Expression_16","text": "[难过]"},
    {"name": "Expression_17","text": "[酷]"},
    {"name": "Expression_18","text": "[冷汗]"},
    {"name": "Expression_19","text": "[抓狂]"},
    {"name": "Expression_20","text": "[吐]"}
]

callback(ret, err)

ret：

类型：JSON 对象
内部字段：

{
    eventType: 'show',  //字符串类型；回调的事件类型，
                        //取值范围：
                        //show：插件打开成功并显示在屏幕上
                        //send：用户点击表情面板、键盘面板（在android 平台上表示输入框右边发送按钮）发送按钮
    msg: ''             //字符串类型；当 eventType 为 send 时，此参数返回输入框的内容，否则无返回值
}

示例代码

var UIChatField = api.require('UIChatField');
UIChatField.open({
    chatBox: {
        placeholder: '聊天内容',     
        autoFocus: false,  
        maxRows: 6     
    },
    styles: {
        bgColor: '#D1D1D1',   
        margin: 10,           
        mask: {               
           bgColor:'rgba(0,0,0,0.5)'
        }             
    },
    tools: {
        h: 44,          
        iconSize: 30,   
        recorder: {     
           normal: 'fs://UIChatTolls/recorder.png',  
           selected: 'fs://UIChatTolls/recorder1.png' 
        },
        image: {        
           normal: 'fs://UIChatTolls/image.png',  
           selected: 'fs://UIChatTolls/image1.png' 
        },
        video: {        
           normal: 'fs://UIChatTolls/video.png',  
           selected: 'fs://UIChatTolls/video1.png' 
        },
        packet: {       
           normal: 'fs://UIChatTolls/packet.png',  
           selected: 'fs://UIChatTolls/packet1.png' 
        },
        face: {         
           normal: 'fs://UIChatTolls/face.png',  
           selected: 'fs://UIChatTolls/face1.png' 
        },
        append: {       
           normal: 'fs://UIChatTolls/append.png',  
           selected: 'fs://UIChatTolls/append1.png'
        }
    },
    emotionPath:'widget://res/emotions/emotion'
}, function(ret) {
    if (ret) {
        api.alert({msg:JSON.stringify(ret)});
    } 
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

setToolbarListener

设置工具条监听事件

setToolbarListener(callback(ret))

callback(ret)

ret：

类型：JSON 对象
内部字段：

{
    eventType: 'record' //字符串类型；监听事件
    state:'press'       //字符串类型；录音按钮的状态（仅在eventType=record时回调）
}

eventType取值范围：
- record 点击录音按钮触发
- image 点击图片按钮触发
- video 点击视频按钮触发
- voiceChat 点击语音通话按钮触发
- videoChat 点击视频通话按钮触发
- fileChoose 点击文件选择按钮触发
- gift 点击礼物按钮触发
- location 点击位置按钮触发
- chooseUser 点击选的收礼人触发（只有在isGroupChat为true的情况下有效）
state取值范围：
- press 按下
- release 抬起
- cancel 取消
- shortTime 按下时间不超过1秒时回调

示例代码

var UIChatField = api.require('UIChatField');
UIChatField.setToolbarListener(function(ret){
    api.alert({msg: JSON.stringify(ret)});
});

setGiftDatas

设置礼物数据

setGiftDatas({params}, callback(ret))

params

styles：

类型：JSON 对象
描述：（可选项）附加功能面板按钮样式配置
内部字段：

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

buttons：

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

[{
    normal: '',       //字符串类型；按钮常态下的背景图标路径，要求本地路径（fs、widget）
    highlight: '',    //字符串类型；按钮被点击时高亮状态的背景图标路径，要求本地路径（fs、widget）
    giftName: '',     //字符串类型；按钮下边的礼物名称
    price:''          //字符串类型；礼物价格标签文本
}]

callback(ret)

ret：

类型：JSON 对象
内部字段：

{
     index: 0     //数字类型；用户点击按钮的索引（从零开始）
}

示例代码

var UIChatField = api.require('UIChatField');
UIChatField.setGiftDatas({
    styles: {
        row: 2,         
        column: 4,         
        iconSize: 30,      
        titleSize: 13,   
        titleColor: ''     
    },
    buttons: [
       {
            normal: 'fs://UIChatField/append1.png',       
            highlight: 'fs://UIChatField/append11.png',    
            title: '电话'       
       },{
            normal: 'fs://UIChatField/append2.png',       
            highlight: 'fs://UIChatField/append21.png',    
            title: '收藏' 
       },{
            normal: 'fs://UIChatField/append3.png',       
            highlight: 'fs://UIChatField/append31.png',    
            title: '发红包' 
       },{
            normal: 'fs://UIChatField/append2.png',       
            highlight: 'fs://UIChatField/append21.png',    
            title: '收藏' 
       },{
            normal: 'fs://UIChatField/append3.png',       
            highlight: 'fs://UIChatField/append31.png',    
            title: '发红包' 
       },{
            normal: 'fs://UIChatField/append2.png',       
            highlight: 'fs://UIChatField/append21.png',    
            title: '收藏' 
       },{
            normal: 'fs://UIChatField/append3.png',       
            highlight: 'fs://UIChatField/append31.png',    
            title: '发红包' 
       },{
            normal: 'fs://UIChatField/append2.png',       
            highlight: 'fs://UIChatField/append21.png',    
            title: '收藏' 
       },{
            normal: 'fs://UIChatField/append3.png',       
            highlight: 'fs://UIChatField/append31.png',    
            title: '发红包' 
       },{
            normal: 'fs://UIChatField/append2.png',       
            highlight: 'fs://UIChatField/append21.png',    
            title: '收藏' 
       },{
            normal: 'fs://UIChatField/append3.png',       
            highlight: 'fs://UIChatField/append31.png',    
            title: '发红包' 
       },{
            normal: 'fs://UIChatField/append2.png',       
            highlight: 'fs://UIChatField/append21.png',    
            title: '收藏' 
       }
    ]
}, function(ret) {
   api.alert({msg:'点击了第'+ret.index+'个按钮'});
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

updateGiftInfo

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

updateGiftInfo({params})

params

avaterPath：

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

nickText:

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

示例代码

var UIChatField = api.require('UIChatField');
UIChatField.updateGiftInfo({
    avaterPath:'widget://avater.png',
    nickText:'送给【昵称】'
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

close

关闭聊天输入框

close()

示例代码

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

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

show

显示聊天输入框

show()

示例代码

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

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

hide

隐藏聊天输入框

hide()

示例代码

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

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

popupKeyboard

弹出键盘

popupKeyboard()

示例代码

var UIChatField = api.require('UIChatField');
UIChatField.popupKeyboard();

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

closeKeyboard

收起键盘

closeKeyboard()

示例代码

var UIChatField = api.require('UIChatField');
UIChatField.closeKeyboard();

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

hideRecordPanel

收起录音面板

hideRecordPanel()

示例代码

var UIChatField = api.require('UIChatField');
UIChatField.hideRecordPanel();

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

value

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

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

params

msg：

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

callback(ret, err)

ret：

类型：JSON 对象
内部字段：

{
    status: true,        //布尔型；true||false
    msg: ''              //字符串类型；输入框当前内容文本
}

示例代码

var UIChatField = api.require('UIChatField');
//设置输入框的值
UIChatField.value({
    msg: '设置输入框的值'
});

//获取输入框的值
UIChatField.value(function(ret, err) {
    if (ret) {
        api.alert({msg: JSON.stringify(ret)});
    } else {
        api.alert({msg: JSON.stringify(err)});
    }
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

insertValue

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

insertValue({params})

params

index：

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

msg：

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

示例代码

var UIChatField = api.require('UIChatField');
UIChatField.insertValue({
    index: 10,
    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，键盘（及表情面包、附件功能面板、录音面板、图片选择面板）所占区域
内部字段：

{
    chatBoxHeight: 60,     //数字类型；输入框所占区域的高度，仅当监听 move 和 change 事件时本参数有值
    panelHeight: 300 ,     //数字类型；工具栏下边缘距离屏幕底部（键盘及表情面板、附件功能面板、录音面板、图片选择面板所占区域）的高度，仅当监听 move 和 change 事件时本参数有值
    value: '',              //字符串类型；输入框当前内容，仅当 name 为 valueChanged 时有值
    removedString:'@XXX'    //字符串类型；删除@user时返回；仅当name为 At且触发删除事件时回调
    index:0 //数字类型；删除@XXX的索引；仅当name为 At且触发删除事件时回调
}

示例代码

var UIChatField = api.require('UIChatField');
UIChatField.chatBoxListener({
        name:'move'
}, function(ret){
    api.alert({msg: JSON.stringify(ret)});
});			
UIChatField.chatBoxListener({
           name:'change'
}, function(ret){
    api.alert({msg: JSON.stringify(ret)});
});
UIChatField.chatBoxListener({
           name:'valueChanged'
}, function(ret){
    api.alert({msg: JSON.stringify(ret)});
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

setPlaceholder

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

setPlaceholder({params})

params

placeholder：

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

示例代码

var UIChatField = api.require('UIChatField');
UIChatField.setPlaceholder({
    placeholder: '修改了占位提示内容'
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

clearText

清空输入框文本

clearText()

示例代码

var UIChatField = api.require('UIChatField');
UIChatField.clearText();

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

reset

重置插件

reset()

示例代码

var UIChatField = api.require('UIChatField');
UIChatField.reset();

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

showGiftPanel

显示礼物面板

showGiftPanel()

示例代码

var UIChatField = api.require('UIChatField');
UIChatField.showGiftPanel();

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

getCurrentVisiblePanel

获取当前可见的panel

callback(ret)

ret：

类型：JSON 对象
内部字段:
取值范围：
- record 录音面板
- gift 礼物面板
- emotion 表情面板
- none 没有显示的面板

{
    panelName: "emotion",        //字符串；录音面板
}

示例代码

var UIChatField = api.require('UIChatField');
UIChatField.getCurrentVisiblePanel(function(ret){
    if(ret.panelName == 'none'){
        // do something
    }
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

setEnableAllBtns

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

Params

enable:

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

callback(ret)

ret：

类型：JSON 对象
内部字段:

{
   status: true        //布尔类型； 设置是否成功
}

示例代码

var UIChatField = api.require('UIChatField');
UIChatField.setEnableAllBtns({
    enable: false
}, function(ret){
    api.alert({msg: JSON.stringify(ret)});
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

cancelRecord

取消录音

callback(ret)

ret：

类型：JSON 对象
内部字段:

{
   eventType: 'cancelRecord'        //字符串；返回事件类型；暂仅返回 "cancelRecord"
}

示例代码

var UIChatField = api.require('UIChatField');
UIChatField.cancelRecord(function(ret){
    api.alert({msg: JSON.stringify(ret)});
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

addMaskViewClickListener

点击遮罩层事件监听

callback()

示例代码

var UIChatField = api.require('UIChatField');
UIChatField.addMaskViewClickListener(function(ret){
    api.alert({msg:'点击遮罩层'});
});

可用性

iOS 系统

可提供的1.0.8及更高版本

是否仍需要帮助？请保持联络！

最后更新于 2024/04/24