当前文档适用于 LayIM PC 端版本,如果你正在了解的并非该版本,请选择对应的版本阅读:
LayIM 是基于 layui 的一款用于开发网页端聊天系统的纯静态 UI 界面解决方案,采用 HTML、CSS、JavaScript 编写,其包含的只是一套前端源代码素材和相关的模拟示例,不具备后台程序以数据库存储等功能。因此实际使用时,需要自己开发后端语言或对接云服务平台(如:融云、环信等)。
文件引入方面,和 PC 版类似:
./layui/css/layui.css
./layui/layui.js
一个最直接的例子是:
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<title>LayIM移动版测试</title>
<link rel="stylesheet" href="./layui/css/layui.css" media="all">
</head>
<body>
<script src=./layui/layui.js"></script>
<script>
//以下为最新版写法
layui.config({
base: '../dist/layim-assets/lib/'
,layimAssetsPath: '../dist/layim-assets/' //layim 资源文件所在目录
,version: true
}).extend({
'layer-mobile': 'layer-mobile'
,'zepto': 'zepto'
,'upload-mobile': 'upload-mobile'
,'layim-mobile': 'layim-mobile'
}).use('layim-mobile', function(){
var layim = layui['layim-mobile'] //WebIM
,layer = layui['layer-mobile']; //弹层
//基础配置
layim.config({
init: {
//设置我的基础信息
mine: {
"username": "佟丽娅" //我的昵称
,"id": 123 //我的ID
,"avatar": "http://tp4.sinaimg.cn/1345566427/180/5730976522/0" //我的头像
}
//好友列表数据
,friend: [] //见下文:init数据格式
}
});
//创建一个会话
layim.chat({
id: 111111
,name: '许闲心'
,type: 'kefu' //friend、group等字符,如果是group,则创建的是群聊
,avatar: 'http://tp1.sinaimg.cn/1571889140/180/40030060651/1'
});
});
</script>
</body>
</html>
除了模块加载有所不同外,LayIM本身的接口书写方式与PC版完全一致,但没有PC版那么丰富。下文进一步讲解
一个你必须认识的方法:layim.config(options)
控制着许多重要的配置,基本上一个完整LayIM实例的构成由它而开始,它允许你自由设定以下参数:
//以下为最新版写法
layui.config({
base: '../dist/layim-assets/lib/'
,layimAssetsPath: '../dist/layim-assets/' //layim 资源文件所在目录
,version: true
}).extend({
'layer-mobile': 'layer-mobile'
,'zepto': 'zepto'
,'upload-mobile': 'upload-mobile'
,'layim-mobile': 'layim-mobile'
}).use('layim-mobile', function(){
var layim = layui['layim-mobile'] //WebIM
,layer = layui['layer-mobile']; //弹层
//基础配置
layim.config({
init: {} //获取主面板列表信息,下文会做进一步介绍
//上传图片接口(返回的数据格式见下文)
,uploadImage: {
url: '' //接口地址
,type: 'post' //默认post
}
//上传文件接口(返回的数据格式见下文)
,uploadFile: {
url: '' //接口地址
,type: 'post' //默认post
}
//扩展“更多”的自定义列表,下文会做进一步介绍(如果无需扩展,剔除该项即可)
,moreList: [{
alias: 'find'
,title: '发现'
,iconUnicode: '' //图标字体的unicode,可不填
,iconClass: '' //图标字体的class类名
}]
//扩展工具栏,下文会做进一步介绍(如果无需扩展,剔除该项即可)
,tool: [{
alias: 'code' //工具别名
,title: '代码' //工具名称
,iconUnicode: '' //工具图标,参考图标文档,可不填
,iconClass: '' //图标字体的class类名
}]
});
});
layim.config(options)的更多可选配置项见下表:
可选项 | 默认值 | 类型 | 用途 |
---|---|---|---|
brief | false | boolean | 是否简约模式,如果设为 true,则主面板不会显示。一般可用于客服 |
title | 我的IM | string | 设置主面板头部名称 |
chatTitleColor | #36373C | string | 设置会话顶部标题的颜色 |
isNewFriend | true | boolean | 是否在联系人面板开启新的朋友 |
tabIndex | 0 | number | 用户设定初始打开的Tab项下标 |
isgroup | false | boolean | 是否在联系人面板开启群聊 |
notice | false | boolean | 是否开启桌面消息提醒,即在浏览器之外的提醒 |
voice | default.wav | string/boolean | 设定消息提醒的声音文件(所在目录:./layui/css/modules/layim/voice/) 若不开启,设置 false 即可 |
maxLength | 3000 | number | 可允许的消息最大字符长度 |
copyright | false | boolean | 是否授权。如果非授权获得,或将LayIM应用在第三方,建议保留,即不设置。 |
较之PC版,实在要简单太多了,如:
//直接赋值列表数据
//里面的字段格式 同 上文的 data 中的格式
init: {
//设置我的基础信息
mine: {
"username": "佟丽娅" //我的昵称
,"id": 123 //我的ID
,"avatar": "http://tp4.sinaimg.cn/1345566427/180/5730976522/0" //我的头像
,"sign": "我的签名"
}
//好友列表,同PC版本
,"friend": [{
"groupname": "前端码屌" //好友分组名
,"id": 1 //分组ID
,"list": [{ //分组下的好友列表
"username": "贤心" //好友昵称
,"id": "100001" //好友ID
,"avatar": "a.jpg" //好友头像
,"sign": "这些都是测试数据,实际使用请严格按照该格式返回" //好友签名
,"status": "online" //若值为offline代表离线,online或者不填为在线
}, …… ]
}, …… ]
}
通过layim.config来设定uploadImage参数可进行图片上传,假设你进行了下述配置
,uploadImage: {
url: ''
}
那么当点击聊天面板上传图片时,将会向uploadImage的url发送HTTP请求,进行图片上传。我们会给你传递一个name="file"的文件表单域,你接受即可。该接口所返回的信息(response)应该严格按照下述的JSON格式:
{
"code": 0 //0表示成功,其它表示失败
,"msg": "" //失败信息
,"data": {
"src": "http://cdn.xxx.com/upload/images/a.jpg" //图片url
}
}
通过layim.config来设定uploadImage参数可进行文件上传,事实上跟图片上传非常类似有木有?假设你进行了下述配置
,uploadFile: {
url: ' ''
}
那么当点击聊天面板上传文件时,将会向uploadFile的url发送HTTP请求,进行文件上传。我们会给你传递一个name="file"的文件表单域,你接受即可。该接口所返回的信息(response)应该严格按照下述的JSON格式:
{
"code": 0 //0表示成功,其它表示失败
,"msg": "" //失败信息
,"data": {
"src": "http://cdn.xxx.com/upload/file/LayIM.zip" //文件url
,"name": 'LayIM.zip' //文件名
}
}
你可以对底部导航“更多”中的列表做任意扩展,已便丰富IM的操作以及跳转到其它页面。首先在你layim.config中设定好要扩展的图标、名等信息,如:
layim.config({
//可同时配置多个
moreList: [{
alias: 'find'
,title: '发现'
,iconUnicode: '' //图标字体的unicode,可不填
,iconClass: '' //图标字体的class类名
},{
alias: 'share'
,title: '分享'
,iconUnicode: '' //图标字体的unicode,可不填
,iconClass: '' //图标字体的class类名
}]
})
上述配置只是显示更多列表,点击列表时所触发的动作还需要获取 moreList事件来实现:
//事件·点击更多列表
layim.on('moreList', function(obj){
switch(obj.alias){ //alias即为上述配置对应的alias
case 'find': //发现
layer.msg('自定义发现动作');
break;
case 'share':
layim.panel({
title: 'share' //分享
,tpl: '<div style="padding: 10px;">自定义模版,{{d.data.test}}</div>' //模版
,data: { //数据
test: '123'
}
});
break;
}
});
你可以对聊天面板的工具栏区域进行扩展,以便实现更丰富的聊天内容。首先在你layim.config中设定好要扩展的图标、名称等信息,如:
layim.config({
//可同时配置多个
tool: [{
alias: 'code' //工具别名
,title: '代码' //工具名称
,iconUnicode: '' //图标字体的unicode,可不填
,iconClass: '' //图标字体的class类名
}]
})
那么在工具栏中将会出现一个代码的图标,如何在点击它时实现你想要的功能呢?很简单,你只需要:
···
//事件·自定义工具栏点击,以上述扩展的工具为例
layim.on(‘tool(code)’, function(insert, send, obj){ //事件中的tool为固定字符,而code则为过滤器,对应的是工具别名(alias)
layer.prompt({
title: ‘插入代码’
,formType: 2
,shade: 0
}, function(text, index){
layer.close(index);
insert(text); //将内容插入到编辑器,主要由insert完成
//send(); //自动发送
console.log(this); //获取当前工具的DOM对象
console.log(obj); //获得当前会话窗口的DOM对象、基础信息
});
});
···
LayIM会在本地存储每个会话的最新 20 条记录。但一般服务端也要存储存储一份,为了避免联调的复杂性,我们并不内置更多聊天记录的展示。但你可以通过事件方法来实现:
//事件·查看更多记录
layim.on('chatlog', function(data, ul){
console.log(data); //得到当前会话对象的基本信息
console.log(ul); //得到当前聊天列表所在的ul容器,比如可以借助他来实现往上插入更多记录
//弹出一个更多聊天记录面板
layim.panel({
title: '与 '+ data.username +' 的聊天记录' //标题
,tpl: '这里是模版,{{d.data.test}}' //模版
,data: { //数据
test: 'Hello'
}
});
});
方法:layim.on(event, callback)
用于 LayIM 事件。接受两个参数。第一个参数event即事件名,第二个参数callback即事件回调。
事件名:sendMessage,每当你发送一个消息,都可以通过该事件获取到。回调参数接受一个object类型的值,携带发送的聊天信息。如:
layim.on('sendMessage', function(res){
var mine = res.mine; //包含我发送的消息及我的信息
//mine的结构如下:
{
avatar: "avatar.jpg" //我的头像
,content: "你好吗" //消息内容
,id: "100000" //我的id
,mine: true //是否我发送的消息
,username: "纸飞机" //我的昵称
}
var to = res.to; //对方的信息
//to的结构如下:
{
avatar: "avatar.jpg"
,id: "100001"
,name: "贤心"
,sign: "这些都是测试数据,实际使用请严格按照该格式返回"
,type: "friend" //聊天类型,一般分friend和group两种,group即群聊
,username: "贤心"
}
//获取到上述消息后,就可以轻松地发送socket了,如:
socket.send({
type: 'chatMessage' //随便定义,用于在服务端区分消息类型
,data: res
});
});
事件并非 layim 提供,而是 WebSocket 提供。
检测到WebSocket事件后,执行layim的内置方法:layim.getMessage(options)
即可显示消息到聊天面板(如果消息所指定的聊天面板没有打开,则会进入本地的消息队列中,直到指定的聊天面板被打开,方可显示。),这是一个对你有用的例子:
//收到的聊天消息事件,假设你服务端emit的事件名为:chatMessage
socket.onmessage = function(res){
res = JSON.parse(res);
if(res.emit === 'chatMessage'){
layim.getMessage(res.data); //res.data即你发送消息传递的数据(阅读:获取发送的消息事件)
}
};
//如果是来自于用户的聊天消息,它必须接受以下字段
layim.getMessage({
username: "纸飞机" //消息来源用户名
,avatar: "http://tp1.sinaimg.cn/1571889140/180/40030060651/1" //消息来源用户头像
,id: "100000" //聊天窗口来源ID(如果是私聊,则是用户id,如果是群聊,则是群组id)
,type: "friend" //聊天窗口来源类型,从发送消息传递的to里面获取
,content: "嗨,你好!本消息系离线消息。" //消息内容
,mine: false //是否我发送的消息,如果为true,则会显示在右方
,timestamp: 1467475443306 //服务端动态时间戳
});
//如果是来自于系统的聊天面板的消息
layim.getMessage({
system: true //系统消息
,id: 1111111 //聊天窗口ID
,type: "friend" //聊天窗口类型
,content: '对方已掉线'
});
事件名:chatChange,坦白而言,似乎没什么卵用。不过有总比没有好。该事件返回一个object类型的参数,携带当前聊天面板的容器、基础信息等。
layim.on('chatChange', function(data){
console.log(data);
});
事件名:newFriend
LayIM并不内置新朋友界面,所以这需要你自己来实现这一套功能,你可以选择跳转或者弹出界面
//事件·点击“新的朋友”
layim.on('newFriend', function(){
//弹出面板
layim.panel({
title: '新的朋友' //标题
,tpl: '<div style="padding: 10px;">自定义模版,{{d.data.test}}</div>' //模版,基于laytpl语法
,data: { //数据
test: '么么哒'
}
});
//也可以直接跳转页面,如:
//location.href = './newfriend'
});
事件名:back
如果你只是弹出一个会话界面(不显示主面板),那么可通过事件返回,跳转到上一页面
//事件·返回
layim.on('back', function(){
//比如返回到上一页面(而不是界面):
history.back();
//或者做一些其他的事
});
事件名:detail
LayIM并不内置“聊天信息”界面,但你可以通过接口很轻松地自定义一个,一般适用于查看群组成员或者对方的个人信息
//事件·点击“新的朋友”
layim.on('detail', function(data){
//console.log(data); //获取当前会话对象,包含了很多所需要的信息
//以查看群组信息(如成员)为例
$.get('abc.com/detail/', {id: data.id}, function(res){
//弹出面板
layim.panel({
title: data.name + ' 聊天信息' //标题
,tpl: '<div style="padding: 10px;">自定义模版,{{d.data.test}}</div>' //模版,基于laytpl语法
,data: { //数据
rows: res.rows //假设rows为群组成员
}
});
});
});
方法名:layim.chat(options),是否似曾相识,没错,我们见过文档最开始的“客服姐姐”用的就是该方法。它允许你自定义任意模式的聊天窗口,先看例子吧:
//自定义私聊类型
layim.chat({
name: '在线客服一' //名称
,type: 'friend' //聊天类型
,avatar: 'http://tp1.sinaimg.cn/5619439268/180/40030060651/1' //头像
,id: 111 //定义唯一的id方便你处理信息
});
//自定义群聊类型
layim.chat({
name: '我的群' //名称
,type: 'group' //聊天类型
,avatar: 'http://tp1.sinaimg.cn/5619439268/180/40030060651/1' //头像
,id: 222 //定义唯一的id方便你处理信息
});
该方法结合brief: true(简约模式),可以免去较为复杂的数据配置。轻量地建立一个聊天面板。拥有较大的平台实用性。可以预见的是,它应该会成为LayIM一个露脸率最高的存在。想象一下吧,对你而言是否如此?
方法名:layim.panel(options)
一个相当实用的存在。你可以借助它像原生客户端一样弹出新的界面,而不是跳页。它提供了强大的模板引擎机制,使得你在编写模版时,可以更自由灵活。该方法可接受以下参数:
layim.panel({
title: '界面标题'
,tpl: '<div style="padding: 10px;">自定义模版,{{d.data.rows}}</div>'
,data: { //数据
test: '么么哒'
}
});
方法名:layim.showNew(alias, status)
用于主动显示和销毁导航以及列表的动态标志,参数 alias 表示:导航或者列表的别名,status表示:显示或隐藏(true or false)
layim.showNew('List', true); //标注“联系人”新动态
layim.showNew('More', true); //标注“更多”新动态
layim.showNew('Friend', true); //标注“新的朋友”新动态
layim.showNew('Group', true); //标注“群聊”新动态
layim.showNew('alias', true); //标注“自定义列表”的新动态,alias对应的是你layim.config时拓展的moreList参数中的alias值
另外,底部导航的“消息”的新动态标志,由LayIM自动控制,无需你手工操作。
方法名:layim.setChatStatus(str),可用于显示:对方输入状态、在线离线状态等,如:
//每次窗口打开或切换,即更新对方的状态
layim.on('chatChange', function(res){
var type = res.data.type;
if(type === 'friend'){
layim.setChatStatus('在线'); //模拟标注好友在线状态
}
});
方法名:layim.addList(options),当你的 WebSocket 事件获取到有好友或者群新增时,需让LayIM的主面板同步添加的信息,可用该方法。先看看例子:
//事件·添加列表的socket事件,假设你服务端emit的事件名为:addList
socket.onmessage = function(res){
if(res.emit === 'addList'){
layim.addList(res.data); //如果是在iframe页,如LayIM设定的add面板,则为 parent.layui.layim.addList(data);
}
};
//需要特别注意的是回调返回的res
//如果添加的是好友,res的结构必须是这样的
{
type: 'friend' //列表类型,只支持friend和group两种
,avatar: "a.jpg" //好友头像
,username: '冲田杏梨' //好友昵称
,groupid: 2 //所在的分组id
,id: "1233333312121212" //好友id
,sign: "本人冲田杏梨将结束AV女优的工作" //好友签名
}
//如果添加的是群组,res的结构必须是这样的
{
type: 'group' //列表类型,只支持friend和group两种
,avatar: "a.jpg" //群组头像
,groupname: 'Angular开发' //群组名称
,id: "12333333" //群组id
}
方法名:layim.removeList(options)
当你的 WebSocket 获取到有好友或者群删除事件时,需让 LayIM 的主面板同步删除的信息,可用该方法。它的调用非常简单,只需要传两个 key:
layim.removeList({
type: 'friend' //或者group
,id: 1238668 //好友或者群组ID
});
//如果是在iframe页,如LayIM设定的add面板,则为:
parent.layui.layim.removeList({
type: 'friend' //或者group
,id: 1238668 //好友或者群组ID
});
方法名:layim.setFriendStatus(id, type)
layim.setFriendStatus(11111, 'online'); //设置指定好友在线,即头像取消置灰
layim.setFriendStatus(11111, 'offline'); //设置指定好友在线,即头像置灰
方法名:layim.cache(),获取LayIM的cache信息,包含一些基础配置信息、我的用户信息、好友/群列表信息、本地数据库信息等。该方法始终会获取到最新的cache,可以打印
//输出的信息不妨在你的Chrome控制台看看(需在引有LayIM的页面中),在此就不做列举了
console.log(layim.cache())
将下面的样式,放入你的页面或公共CSS文件即可:
body .layim-title{display: none;}
body .layim-chat-main, body .layim-content, body .layui-layim{top: 0}