喧喧浏览器端 Mini 版
喧喧浏览器端 Mini 版用于将喧喧嵌入到其他页面进行显示,在任意页面通过调用 JS 显示一个喧喧聊天窗口供用户使用。
开发环境搭建
基础开发环境搭建参考喧喧官方客户端环境搭建文档。
如果是第一次搭建开发环境,需要将喧喧官方项目源码拷贝到 xuanxuan/
文件夹下,如果安装有 git,只需要执行:
$ git clone https://github.com/easysoft/xuanxuan.git
如果不是第一次搭建开发环境,但需要同步官方项目源码,只需要执行:
$ git pull
打包
在命令行窗口执行:
$ npm run package
最终生成的部署包在 relase/xuanxuan-mini-*
文件夹下。
前端使用方法
参考一下步骤进行使用(假设最终部署包目录名称为 xxc-mini
):
第一步:在页面引入相关资源
<script src="./xxc-mini/xxc-mini.js"></script>
第二步:启动喧喧弹出界面
使用 startXuanxuan(options)
方法启动弹出界面,其中 options
为启动参数。所有可用的参数如下示例:
startXuanxuan({
// 喧喧页面地址,默认为 ‘./index.html’
web: './index.html',
// 要登录的服务器地址,必填项
server: 'https://demo.ranzhi.net',
// 要登录的账户,必填项
account: 'demo8',
// token,可以为密码 md5值,必填项
token: 'e10adc3949ba59abbe56e057f20f883e',
// 要开聊的聊天 GID,必填项
cgid: '4134e746-f808-ed24-eec9-ac5afe139b56',
// 聊天窗口 id,确保每个聊天窗口 id 值唯一性,如果指定为 null,则会自动创建一个,默认为 null
id: null,
// 是否禁用添加自带的样式,默认为 false,如果为 true 则需要自己设置窗口框架样式
noStyle: false,
// 界面所使用的语言
lang: 'zh-cn',
// 窗口宽度,默认 600px
width: '600px',
// 窗口高度,默认 500px
height: '500px',
// 是否在创建窗口后立即显示窗口,默认为 true
autoShow: true,
// 关闭按钮上显示的提示文本,默认为 “关闭”
closeText: '关闭',
// 折叠按钮上显示的提示文本,默认为 “收起”
collapseText: '收起',
// 展开按钮上显示的提示文本,默认为 “展开”
expandText: '展开',
// 点击关闭按钮是否提示,默认为 `true`
closeConfirm: true,
// 当用户点击关闭按钮时的提示文本,默认为 “要退出聊天吗?”
closeConfirmText: '要退出聊天吗?',
// 对话框上确定按钮上的文本,默认为 “确定”
confirmBtnText: '确定',
// 对话框上取消按钮上的文本,默认为 “取消”
cancelBtnText: '取消',
// 展开按钮上显示的内容,可以为 HTML,默认为 “↑”
expandBtnHtml: '↑',
// 折叠按钮上显示的内容,可以为 HTML,默认为 “–”
collapseBtnHtml: '–',
// 关闭按钮上显示的内容,可以为 HTML,默认为 "×"
closeBtnHtml: '×',
// 聊天窗口 iframe 元素父级元素上添加的类名,默认为 ‘’
className: '',
// 要注入到聊天 iframe 窗口内的 CSS 样式,默认为 null,仅在同域下可用
injectCss: null,
// 设置运行时配置,默认为 null
config: null,
// 当用户重复登录时是否自动退出,默认为 false
exitOnKickoff: false,
// 当聊天iframe窗口加载完成时回调函数,默认为 null,仅在同域下可用
onLoad: function() {
console.log('onLoad');
},
// 当聊天界面渲染完成时回调函数,默认为 null,仅在同域下可用
onReady: function() {
console.log('onReady');
},
// 当接收到消息时的事件回调函数,默认为 null,仅在同域下可用
onNotice: function(notice) {
console.log('notice', notice);
},
// 当用户登录完成事件回调函数,默认为 null,仅在同域下可用
// 参数 user 为当前登录的用户信息
onUserLogin: function(user) {
console.log('login', user);
},
// 当用户退出事件回调函数,默认为 null,仅在同域下可用
// 参数 user 为当前退出的用户信息
// 参数 reason 退出原因,例如 'KICKOFF' 为重复登录导致退出
// 在此回调函数内返回 `'exit'` 则退出当前聊天窗口
onUserLogout: function(user, reason) {
console.log('logout', user, reason);
if (reason === 'KICKOFF') {
// 返回 'exit' 则直接退出聊天并关闭弹窗
return 'exit';
}
},
});
startXuanxuan
方法调用后会返回一个对象,该对象上有如下方法:
element
: 聊天窗口iframe元素父级元素;id
: 聊天窗口元素 ID;exit()
: 关闭聊天窗口并退出;hide()
: 隐藏聊天窗口;show()
: 显示聊天窗口;minimize()
: 最小化(收起)聊天窗口;maximize
: 展开聊天窗口;toggleMinimize()
: 切换折叠或展开聊天窗口;contentWindow
:聊天窗口内部window
对象(仅在同域下可用)。
例如要在创建窗口后不自动显示,先最小化后再显示可以这样:
var xxc = startXuanxuan({
web: './index.html',
server: 'https://demo.ranzhi.net',
account: 'demo8',
token: 'e10adc3949ba59abbe56e057f20f883e',
cgid: '4134e746-f808-ed24-eec9-ac5afe139b56',
// 是否在创建窗口后立即显示窗口
autoShow: false
});
xxc.minimize();
xxc.show();
运行时配置
允许通过 config
配置项来重置应用运行时配置,所有可以重置的运行时配置参考 https://github.com/easysoft/xuanxuan/tree/master/xxc/app/config
例如自定义 Emojione 图片 CDN 地址:
startXuanxuan({
config: {
media: {
'emojione.imagePathPNG': '//cdn.jsdelivr.net/emojione/assets/4.0/png/128/'
}
}
});
也可以通过 config 配置项的 lang
字段覆盖界面语言项,例如重新设置输入框上用户不在线时的提示文本:
startXuanxuan({
config: {
lang: {
'zh-cn': {
'chat.sendbox.placeholder.memberIsOffline': '{0} 不在线,稍后再聊了'
}
}
},
});
所有可以配置的语言项参考 https://github.com/easysoft/xuanxuan/blob/master/xxc/app/lang/zh-cn.json