UIChatBox

close hide closeBoard closeKeyboard insertValue setPlaceholder cancelRecord

论坛示例

为帮助用户更好更快的使用模块，论坛维护了一个，示例中包含示例代码、知识点讲解、注意事项等，供您参考。

模块概述

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

本模块的主要功能有：

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

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

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

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

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

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

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

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

功能详情参考接口参数。

模块预览图如下：

本模块源码已开源，地址为：https://github.com/apicloudcom/UIChatBox

模块接口

open

打开聊天输入框

open({parmas}, callback(ret))

params

placeholder：

  • 类型：字符串
  • 描述：（可选项）输入框的占位提示文本

autoFocus：

  • 类型：布尔
  • 描述：（可选项）输入框是否自动获取焦点，并弹出键盘
  • 默认值：false

maxRows：

  • 类型：数字
  • 描述：（可选项）输入框显示的最大行数（高度自适应）
  • 默认值：4

emotionPath：

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

emotionPath

texts：

  • 类型：JSON 对象
  • 描述：（可选项）聊天输入框模块可配置的文本
  • 内部字段：
  1. {
  2.     recordBtn: {                        //（可选项）JSON对象；录音按钮文字内容
  3.         normalTitle: '按住 说话',        //（可选项）字符串类型；按钮常态的标题，默认：'按住 说话'
  4.         activeTitle: '松开 结束'         //（可选项）字符串类型；按钮按下时的标题，默认：'松开 结束'
  5.     },
  6.     sendBtn: {                         //（可选项）JSON对象；发送按钮文字内容，在 iOS 平台上对键盘内按钮无效
  7.         title: '发送'                   //（可选项）字符串类型；按钮常态的标题，默认：'发送'
  8.     }
  9. }

styles：

  • 类型：JSON 对象
  • 描述：模块各部分的样式集合
  • 内部字段：
  1. {  
  2.     topDivider:{                        //(可选项)顶部分割线配置
  3.     width:3,                        //(可选项)顶部分割线的粗细，默认：0 
  4.     color:'#000'                    //(可选项)顶部分割线的颜色；默认：#000 ;支持图片设置(fs:// & widget://)
  5.     },
  6.     inputBar:{                          //（可选项）JSON对象；输入区域（输入框及两侧按钮）整体样式      
  7.         borderColor: '#d9d9d9',         //（可选项）字符串类型；输入框区域上下边框的颜色，支持 rgb，rgba，#；默认：'#d9d9d9'
  8.         bgColor: '#f2f2f2',             //（可选项）字符串类型；输入框区域的整体背景色，支持 rgb，rgba，#；默认：'#f2f2f2'
  9.     textColor:'#000',               //（可选项）字符串类型；输入文字的颜色；默认：#000，支持 rgb，rgba，#；默认：'#f2f2f2'
  10.     placeholderColor:'',            //（可选项）字符串类型；提示文字的颜色；默认：系统默认，支持 rgb，rgba，#；默认：'#f2f2f2'
  11.     textSize:16,                    //（可选项）数字类型；默认：16
  12.     textMarginLeft:5                //（可选项）数字类型；光标距离左边框的距离，默认：5
  13.     },
  14.     inputBox: {                         //（可选项）JSON对象；输入框样式
  15.         borderColor: '#B3B3B3',         //（可选项）字符串类型；输入框的边框颜色，支持 rgb，rgba，#；默认：'#B3B3B3'
  16.         bgColor: '#f2f2f2',             //（可选项）字符串类型；输入框的背景色，支持 rgb，rgba，#；默认：'#f2f2f2'
  17.         boardBgColor: '#f2f2f2',        //（可选项）字符串类型；面板的背景色(表情面板，附加面板)，支持 rgb，rgba，#；默认：'#f2f2f2'
  18.         topMargin:10,                   //（可选项）数字类型；输入框距离顶部的边距；默认：10
  19.     borderCorner:5,                 //(可选项)数字类型；默认：5
  20.     leftIcon:{                      //(可选项)JSON对象，输入框左侧图标  本参数仅支持android
  21.         size:20,                //(可选项)数字类型；icon的大小；默认：20
  22.         path:'widget://res/left_icon.jpg'//字符串类型；icon的路径；支持widget:// fs://
  23.     }
  24.     },
  25.     emotionBtn: {                       //（可选项）JSON对象；表情按钮样式；不传则不显示表情按钮
  26.         normalImg: 'widget://'          //（可选项）字符串类型；表情按钮常态的背景图片（本地路径，fs://、widget://）；默认：笑脸小图标,
  27.     },
  28.     extrasBtn: {                        //（可选项）JSON对象；附加功能按钮样式，不传则不显示附加功能按钮
  29.         normalImg: 'widget://'          //（可选项）字符串类型；附加功能按钮常态的背景图片（本地路径，fs://、widget://）
  30.     },
  31.     keyboardBtn: {                      //JSON对象；键盘按钮样式
  32.         normalImg: 'widget://'          //字符串类型；键盘按钮常态的背景图片（本地路径，fs://、widget://）；默认：键盘小图标
  33.     },
  34.     speechBtn: {                        //（可选项）JSON对象；输入框左侧按钮样式，不传则不显示左边的语音按钮
  35.         normalImg: 'widget://',         //字符串类型；左侧按钮常态的背景图片（本地路径，fs://、widget://）
  36.         activeImg:''                    //字符串类型；左侧按钮按下的背景图片（本地路径，fs://、widget://）
  37.     },
  38.     recordBtn: {                        //JSON对象；“按住 录音”按钮的样式
  39.         normalBg: '#c4c4c4',            //（可选项）字符串类型；按钮常态的背景，支持 rgb，rgba，#，图片路径（本地路径，fs://、widget://）；默认：'#c4c4c4'
  40.         activeBg: '#999999',            //（可选项）字符串类型；按钮按下时的背景，支持 rgb，rgba，#，图片路径（本地路径，fs://、widget://）；默认：'#999999'；normalBg 和 activeBg 必须保持一致，同为颜色值，或同为图片路径
  41.         color: '#000',                  //（可选项）字符串类型；按钮标题文字的颜色，支持 rgb，rgba，#，默认：'#000000'
  42.         size: 14                        //（可选项）数字类型；按钮标题文字的大小，默认：14
  43.    },
  44.    recordPanelBtn:{                     //JSON对象；录音面板样式
  45.      normalImg: '',        //（可选项）字符串类型；按钮常态的图片
  46.      activeImg: ''         //（可选项）字符串类型；按钮按下时的图片
  47.      width:100,           //（可选项）数字类型；按钮的宽度，默认：100
  48.      height:100           //（可选项）数字类型；按钮的高度，默认：100
  50.    },
  51.     indicator: {                        //（可选项）JSON对象；表情和附加功能面板的小圆点指示器样式，若不传则不显示该指示器
  52.         target: 'both',                 //（可选项）字符串类型；配置指示器的显示区域；默认：'both'
  53.                                         //取值范围：
  54.                                         //both（表情和附加功能面板皆显示）
  55.                                         //emotionPanel（表情面板显示）
  56.         color: '#c4c4c4',               //（可选项）字符串类型；指示器颜色；支持 rgb、rgba、#；默认：'#c4c4c4'
  57.         activeColor: '#9e9e9e'          //（可选项）字符串类型；当前指示器颜色；支持 rgb、rgba、#；默认：'#9e9e9e'
  58.     },
  59.     sendBtn: {                         //（可选项）JSON对象；发送按钮样式，本参数对 iOS 平台上的键盘内发送按钮无效
  60.         bg: '#4cc518',                 //（可选项）字符串类型；发送按钮背景颜色，支持 rgb、rgba、#、img；默认：#4cc518
  61.         titleColor: '#ffffff',          //（可选项）字符串类型；发送按钮标题颜色；默认：#ffffff
  62.         activeBg: '#46a91e',            //（可选项）字符串类型；发送按钮背景颜色，支持 rgb、rgba、#、img；默认：无
  63.         titleSize: 13                    //（可选项）数字类型；发送按钮标题字体大小；默认：13
  64.     }
  65. }

isShowSendBtn：

  • 类型：布尔
  • 描述：（可选项）表情键盘上的发送按钮是否显示 注意:本参数对 iOS 平台上的键盘内发送按钮无效 ，该参数仅支持iOS
  • 默认：true

disableSendMessage:

  • 类型：布尔类型
  • 描述：（可选项）是否禁言
  • 默认：false

extras：

  • 类型：JSON 对象
  • 描述：（可选项）点击附加功能按钮，打开的附加功能面板的按钮样式，配合 extrasBtn 一起使用，若 extrasBtn 参数内 normalImg 属性不传则此参数可不传
  1. {
  2.     titleSize: 10,                  //（可选项）数字类型；标题文字大小，默认：10
  3.     titleColor: '#a3a3a3',          //（可选项）字符串类型；标题文字颜色，支持 rgb、rgba、#；默认：'#a3a3a3'
  4.     isAdaptScreenSize:true          // (可选项) 布尔类型；附加功能按钮的样式是否自适应屏幕大小布局，改参数为false时，则每一行固定显示四个,若为true，则根据屏幕大小自动适配 默认：true
  5.     isCenterDisplay:false          // (可选项)布尔类型；附加功能按钮的样式是否居中显示，参数为false时，isAdaptScreenSize有效,若为true，则按钮居中显示； 默认：false
  6.     btns: [{                        //数组类型；附加功能按钮的样式
  7.         title: '图片',              //（可选项）字符串类型；附加功能按钮的标题内容                  
  8.         normalImg: '',              //（可选项）字符串类型；按钮常态的背景图片（本地路径，fs://、widget://）
  9.         activeImg: ''               //（可选项）字符串类型；按钮按下时的背景图片（本地路径，fs://、widget://）   
  10.     }]
  11. }

recordType：

  • 类型：字符串
  • 描述：（可选项）点击左边录音按钮所展示的类型
  • 默认：“按住 录音”按钮的样式
  • 取值范围：
    • pressRecord (“按住 录音”按钮的样式)
    • recordPanel (录音面板)

isClose：

  • 类型：布尔值
  • 描述：（可选项）点击空白区域是否关闭整个模块(包括键盘)
  • 默认：false

callback(ret)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.     eventType: 'show',  //字符串类型；回调的事件类型，
  3.                         //取值范围：
  4.                         //show（该模块打开成功）
  6.                         //clickExtras（用户点击附加功能面板内的按钮）
  7.                         //clickRecord（用户点击录音功能面板内的按钮）
  8.     index: 0,           //数字类型；当 eventType 为 clickExtras 时，此参数为用户点击附加功能按钮的索引，否则为 undefined
  9.     msg: ''             //字符串类型；当 eventType 为 send 时，此参数返回输入框的内容，否则返回 undefined
  10.     inputBarHeight:30   //数字类型；输入框及左右按钮整体区域的高度
  11. }

示例代码

  1. var UIChatBox = api.require('UIChatBox');
  2. UIChatBox.open({
  3.     placeholder: '',
  4.     maxRows: 4,
  5.     emotionPath: 'widget://res/img/emotion',
  6.     texts: {
  7.         recordBtn: {
  8.             normalTitle: '按住说话',
  9.             activeTitle: '松开结束'
  10.         },
  11.         sendBtn: {
  12.             title: 'send'
  13.         }
  14.     },
  15.     styles: {
  16.         inputBar: {
  17.             borderColor: '#d9d9d9',
  18.             bgColor: '#f2f2f2'
  19.         },
  20.         inputBox: {
  21.             borderColor: '#B3B3B3',
  22.             bgColor: '#FFFFFF'
  23.         },
  24.         emotionBtn: {
  25.             normalImg: 'widget://res/img/chatBox_face1.png'
  26.         },
  27.         extrasBtn: {
  28.             normalImg: 'widget://res/img/chatBox_add1.png'
  29.         },
  30.         keyboardBtn: {
  31.             normalImg: 'widget://res/img/chatBox_key1.png'
  32.         },
  33.         speechBtn: {
  34.             normalImg: 'widget://res/img/chatBox_key1.png'
  35.         },
  36.         recordBtn: {
  37.             normalBg: '#c4c4c4',
  38.             activeBg: '#999999',
  39.             color: '#000',
  40.             size: 14
  41.         },
  42.         indicator: {
  43.             target: 'both',
  44.             color: '#c4c4c4',
  45.             activeColor: '#9e9e9e'
  46.         },
  47.         sendBtn: {
  48.             titleColor: '#4cc518',
  49.             bg: '#999999',
  50.             activeBg: '#46a91e',
  51.             titleSize: 14
  52.         }
  53.     },
  54.     extras: {
  55.         titleSize: 10,
  56.         titleColor: '#a3a3a3',
  57.         btns: [{
  58.             title: '图片',
  59.             normalImg: 'widget://res/img/chatBox_album1.png',
  60.             activeImg: 'widget://res/img/chatBox_album2.png'
  61.         }, {
  62.             title: '拍照',
  63.             normalImg: 'widget://res/img/chatBox_cam1.png',
  64.             activeImg: 'widget://res/img/chatBox_cam2.png'
  65.         }]
  66.     }
  67. }, function(ret, err) {
  68.     if (ret) {
  69.         alert(JSON.stringify(ret));
  70.     } else {
  71.         alert(JSON.stringify(err));
  72.     }
  73. });

可用性

可提供的1.0.0及更高版本

close

关闭聊天输入框

close()

示例代码

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

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

show

显示聊天输入框

show()

示例代码

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

hide

隐藏聊天输入框

hide()

示例代码

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

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

popupKeyboard

弹出键盘

popupKeyboard()

示例代码

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

iOS系统，Android系统

可提供的1.0.0及更高版本

closeKeyboard

收起键盘

closeKeyboard()

示例代码

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

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

popupBoard

弹出表情、附加功能面板

popupBoard({params})

params

target:

  • 类型：字符串
  • 描述：操作的面板类型，取值范围如下：
    • emotion：表情面板
    • extras：附加功能面板
  • 默认值：emotion

示例代码

  1. var UIChatBox = api.require('UIChatBox');
  2.     target: 'extras'
  3. });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

closeBoard

收起表情、附加功能面板

closeBoard()

示例代码

  1. var UIChatBox = api.require('UIChatBox');
  2. UIChatBox.closeBoard();

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

value

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

params

msg：

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

callback(ret)

ret：

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

示例代码

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

insertValue

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

insertValue({params})

params

index：

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

msg：

  • 类型：字符串
  • 描述：（可选项）要插入的内容
  • 默认值：’’
  1. var UIChatBox = api.require('UIChatBox');
  2. UIChatBox.insertValue({
  3.     index: 10,
  4.     msg: '这里是插入的字符串'
  5. });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

addEventListener

事件监听

addEventListener({params}, callback(ret))

params

target：

  • 类型：字符串
  • 描述：事件的目标对象
  • 取值范围：
    • recordBtn（录音按钮，open 接口的 speechBtn 参数必须传值，否则事件监听无效）
    • inputBar（输入区域，输入框及两侧按钮区域）

name：

  • 类型：字符串
  • 描述：监听的事件类型
  • 取值范围：
    • 适用于 recordBtn 对象
      • press（按下录音按钮）
      • press_cancel（松开录音按钮）
      • move_out（按下录音按钮后，从按钮移出）
      • move_out_cancel（按下录音按钮后，从按钮移出并松开按钮）
      • move_in（move_out 事件后，重新移入按钮区域）
    • recordCanceled 主动取消录音事件
    • 适用于 inputBar 对象
      • move（输入框所在区域弹动事件）
      • change（输入框所在区域高度改变）
      • showRecord（用户点击左侧语音按钮）
      • showEmotion（用户点击表情按钮）
      • showExtras（用户点击右侧附加功能按钮，如果 open 时传了 extras 参数才会有此回调）
      • valueChanged（输入框内容改变事件）

callback(ret)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.     inputBarHeight: 60,    //数字类型；输入框及左右按钮整体区域的高度，仅当监听 inputBar 的 move 和 change 事件时本参数有值
  3.     panelHeight: 300 ,     //数字类型；输入框下边缘距离屏幕底部的高度，仅当监听 inputBar 的 move 和 change 事件时本参数有值
  4.     value: ''              //字符串类型；输入框当前内容，仅当 target 为 inputBar name 为 valueChanged 时有值
  5. }

示例代码

  1. //监听 recordBtn 按钮
  2. var UIChatBox = api.require('UIChatBox');
  3. UIChatBox.addEventListener({
  4.     target: 'recordBtn',
  5.     name: 'press'
  6. }, function(ret, err) {
  7.     if (ret) {
  8.         alert(JSON.stringify(ret));
  9.     } else {
  10.         alert(JSON.stringify(err));
  11.     }
  12. });
  14. //监听 inputBar 
  15. var UIChatBox = api.require('UIChatBox');
  16. UIChatBox.addEventListener({
  17.     target: 'inputBar',
  18.     name: 'move'
  19. }, function(ret, err) {
  20.     if (ret) {
  21.         alert(JSON.stringify(ret));
  22.     } else {
  23.         alert(JSON.stringify(err));
  24.     }
  25. });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

setPlaceholder

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

setPlaceholder({params})

params

placeholder：

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

示例代码

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

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

reloadExtraBoard

重新加载（刷新）附加功能面板，open时必须添加附加功能按钮及其面板参数

reloadExtraBoard({params})

params

extras：

  • 类型：JSON 对象
  • 描述：（可选项）点击附加功能按钮，打开的附加功能面板的按钮样式，配合 extrasBtn 一起使用，若 extrasBtn 参数内 normalImg 属性不传则此参数可不传
  1. {
  2.     titleSize: 10,                  //（可选项）数字类型；标题文字大小，默认：10
  3.     titleColor: '#a3a3a3',          //（可选项）字符串类型；标题文字颜色，支持 rgb、rgba、#；默认：'#a3a3a3'
  4.     btns: [{                        //数组类型；附加功能按钮的样式
  5.         title: '图片',               //（可选项）字符串类型；附加功能按钮的标题内容                  
  6.         normalImg: '',              //（可选项）字符串类型；按钮常态的背景图片（本地路径，fs://、widget://）
  7.         activeImg: ''               //（可选项）字符串类型；按钮按下时的背景图片（本地路径，fs://、widget://）   
  8.     }]
  9. }

示例代码

  1. var UIChatBox = api.require('UIChatBox');
  2. UIChatBox.reloadExtraBoard({
  3.     extras: {
  4.         titleSize: 10,
  5.         titleColor: '#a3a3a3',
  6.         btns: [{
  7.             title: '图片',
  8.             normalImg: 'widget://res/img/chatBox_album1.png',
  9.             activeImg: 'widget://res/img/chatBox_album2.png'
  10.         }, {
  11.             title: '拍照',
  12.             normalImg: 'widget://res/img/chatBox_cam1.png',
  13.             activeImg: 'widget://res/img/chatBox_cam2.png'
  14.         }, {
  15.             title: '拍照',
  16.             normalImg: 'widget://res/img/chatBox_cam1.png',
  17.             activeImg: 'widget://res/img/chatBox_cam2.png'
  18.         }, {
  19.             title: '拍照',
  20.             normalImg: 'widget://res/img/chatBox_cam1.png',
  21.             activeImg: 'widget://res/img/chatBox_cam2.png'
  22.         }, {
  23.             title: '拍照',
  24.             normalImg: 'widget://res/img/chatBox_cam1.png',
  25.             activeImg: 'widget://res/img/chatBox_cam2.png'
  26.         }, {
  27.             title: '拍照',
  28.             normalImg: 'widget://res/img/chatBox_cam1.png',
  29.             activeImg: 'widget://res/img/chatBox_cam2.png'
  30.         }, {
  31.             title: '拍照',
  32.             normalImg: 'widget://res/img/chatBox_cam1.png',
  33.             activeImg: 'widget://res/img/chatBox_cam2.png'
  34.         }, {
  35.             title: '拍照',
  36.             normalImg: 'widget://res/img/chatBox_cam1.png',
  37.             activeImg: 'widget://res/img/chatBox_cam2.png'
  38.         }, {
  39.             title: '拍照',
  40.             normalImg: 'widget://res/img/chatBox_cam1.png',
  41.             activeImg: 'widget://res/img/chatBox_cam2.png'
  42.         }]
  44. });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

cancelRecord

取消录音

cancelRecord()

示例代码

iOS系统，Android系统

可提供的1.0.0及更高版本