webim【LayIM】开发者文档
在WebIM似乎已被打入冷宫的今天,LayIM正试图重新为网页带来一些社交想象。作为一款Web即时通讯前端解决方案(服务端需自写),LayIM提供了全方位接口支撑,竭力以最灵便的方式接入到你的实际项目中。并始终坚持极简的体验,拉近你的用户在web间的距离。我们也将推出LayIM在Node.js端的集成方案,以供服务端层面的参考。
LayIM兼容除IE6/7以外的所有浏览器,如果你的网站仍需兼容ie6/7,那么强烈建议你说服你的老板或者客户。
模块加载名称:layim,官网地址:layim.layui.com
开始使用
LayIM基于layui模块体系,因此你获得的其实是一个包含LayIM的layui框架,不同的是,开源版的layui并不包含LayIM。捐赠后,将您获得的压缩包解压,将layui整个目录文件放入你的项目后,不用再对其代码做任何修改(方便下次升级)。然后您只需引入下述两个文件即可。
假如你将layui放入你的/static/目录中,并且你的html页面在根目录,那么一个最直接的例子是:
通过上述方式,便可成功加载layim。当然,你仅仅只是看到了一个"客服姐姐"的聊天面板,这等同于:Hello World!
向“客服姐姐”问好后就忘了它吧,这份文档才刚刚开始。
初始化配置
一个你必须认识的方法:layim.config(options)
控制着许多重要的配置,基本上一个完整LayIM实例的构成由它而开始,它允许你自由设定以下参数:
上面的参数中,brief、skin、min、isgroup、chatLog、copyright等参数都是非必填项,本身具有默认值。而对于init(初始化接口)、members(查看群员接口)、uploadImage(上传图片接口)、uploadFile(上传文件接口)所返回的数据格式,下面将逐一展示
init数据格式
通过layim.config来设定init参数可获得我的信息、好友列表、群组列表,假设你进行了下述配置
那么该接口所返回的信息(response)应该严格按照下述的JSON格式:
Demo:getList.json
members数据格式
通过layim.config来设定members参数可获取群员列表,假设你进行了下述配置
那么当点击群聊面板查看成员时,将会向members的url发送Ajax请求,并自动传递一个id参数(群组id)。该接口所返回的信息(response)应该严格按照下述的JSON格式:
Demo:getMembers.json
uploadImage数据格式
通过layim.config来设定uploadImage参数可进行图片上传,假设你进行了下述配置
那么当点击聊天面板上传图片时,将会向uploadImage的url发送HTTP请求,进行图片上传。我们会给你传递一个name="file"的文件表单域,你接受即可。该接口所返回的信息(response)应该严格按照下述的JSON格式:
uploadFile数据格式
通过layim.config来设定uploadImage参数可进行文件上传,事实上跟图片上传非常类似有木有?假设你进行了下述配置
那么当点击聊天面板上传文件时,将会向uploadFile的url发送HTTP请求,进行文件上传。我们会给你传递一个name="file"的文件表单域,你接受即可。该接口所返回的信息(response)应该严格按照下述的JSON格式:
接入WebSocket
万万不可畏惧它的存在,除非你真的想用Ajax轮询去解决消息I/O。WebSocket会使得你的消息接受和传递变得极其轻松,最重要的一点是,性能卓绝。WebSocket的建立非常简单:
});服务端层面,不用害怕,事情也远没有那么复杂。我们会抽空给出Node.js的官方集成案例。但对于其它服务端语言,以下已经成功接入LayIM的案例对你也许会有一定帮助:
你的服务端语言没有列举在上面?额。。。那一定是你的语言太冷门了,自己去网搜资料吧。
查看更多聊天记录
为了避免联调的复杂性,我们并不内置更多聊天记录的展示。而是弹出一个聊天记录的layer窗口,这意味着你可以随意发挥聊天记录的页面。通过layim.config配置chatLog来指向聊天记录的URL。假设你进行了下述设定:
那么,我们会在chatLog所对应的URL后面动态追加当前聊天窗口的ID(即好友或群组ID)和类型,如:/chat/log?id=123&type=friend
请注意:当你自建一个更多聊天记录的动态页面时,我们建议您通过Ajax来获取聊天记录,因为LayIM发送的内容,可能包含链接、图片等多媒体信息,它们需要 parent.layui.layim.content(content)方法来解析
查找好友/群
同样为了避免联调的复杂性,我们并不内置查找好友/群功能。而是弹出一个layer窗口,这意味着你可以随意发挥该查找页面。通过layim.config配置find来指向查找的页面URL。如:
事件监听
方法:layim.on(event, callback)
用于LayIM事件监听。接受两个参数。第一个参数event即事件名,第二个参数callback即事件回调。
ready事件
事件名:ready,用于监听LayIM初始化就绪。由于主面板的渲染,需建立在init接口请求完毕的基础上,而一些操作必须等到主面板渲染完毕后才能操作,所以这个时候就可以放入ready事件的回调体中来执行。其回调接受一个object类型的参数,携带一些基础配置信息、我的用户信息、好友/群列表信息、本地数据库信息等,调用方式:
监听在线状态切换
事件名:online,看到主面板你的昵称后的icon么,没错,就是它。当前支持“在线”、“隐身”两种状态切换。分别以online和hide的string类型的值传递给回调参数。如:
监听发送的消息
事件名:sendMessage,每当你发送一个消息,都可以通过该事件监听到。回调参数接受一个object类型的值,携带发送的聊天信息。如:
监听接受的消息
事件的监听并非layim提供,而是WebSocket提供。
检测到WebSocket事件后,执行layim的内置方法:layim.getMessage(options)
即可显示消息到聊天面板(如果消息所指定的聊天面板没有打开,则会进入本地的消息队列中,直到指定的聊天面板被打开,方可显示。),这是一个对你有用的例子:
监听查看群员
事件名:members,在群聊面板中查看全部成员时触发,该事件返回获取群员接口(即layim.config中的members)的response信息。
监听聊天窗口的切换
事件名:chatChange,坦白而言,似乎没什么卵用。不过有总比没有好。该事件返回一个object类型的参数,携带当前聊天面板的容器、基础信息等。
自定义一个聊天窗口
方法名:layim.chat(options),是否似曾相识,没错,我们见过文档最开始的“客服姐姐”用的就是该方法。它允许你自定义任意模式的聊天窗口,先看例子吧:
//自定义在线客服 //自定义群聊(对于想搞一个临时性的房间,貌似是挺有意思的)该方法结合brief: true(简约模式),可以免去较为复杂的数据配置。轻量地建立一个聊天面板。拥有较大的平台实用性。可以预见的是,它应该会成为LayIM一个露脸率最高的存在。想象一下吧,对你而言是否如此?
初始最小化聊天界面
方法名:layim.setChatMin(),如果你在初始的状态下不想展开聊天面板(譬如悬浮的在线客服),那么该方法会派上用场,使用很简单,就不过多啰嗦了。
添加好友/群到主面板
方法名:layim.addList(options),当你的WebSocket监听到有好友或者群新增时,需让LayIM的主面板同步添加的信息,可用该方法。先看看例子:
//如果添加的是群组,res的结构必须是这样的 });从主面板移除好友/群
方法名:layim.removeList(options),当你的WebSocket监听到有好友或者群删除时,需让LayIM的主面板同步删除的信息,可用该方法。它的调用非常简单,只需要传两个key:
获取列表元素
LayIM的好友/群的列表所在元素,附带唯一的id,由固定前缀“layim-”+动态的type和id字符拼接而成,如id="layim-friend10000",通过查找id选择器获得该元素后,你就可以对其进行头像置灰等处理了。
获取cache数据
方法名:layim.cache(),获取LayIM的cache信息,返回的信息结构和ready事件获得的信息一样,不同的是,改方法始终会获取到最新的cache。
无需接口的功能
LayIM有许多功能是无需接口来处理的,在此特别列举几个比较常见的:
#历史会话:LayIM会自动记录你每次打开的聊天窗口到本地数据库(localStorage)、所以这一块无需通过接口去渲染。
#主面板的展开状态、#好友分组的展开状态、#皮肤的选择:同样都会记录到本地数据库
#搜索好友/群组:LayIM内部会按照关键字检索出搜索结果。
#消息提醒:LayIM内置强大的消息提醒机制,你只需要监听消息,并获取消息,LayIM将为您处理好一切。
#聊天记录:LayIM为您的每个对话存储最新的50条记录到本地,当你下次打开时,仍然会初始化渲染这些内容。但我们仍然建议你的服务端也存储一份记录,因为“查看更多聊天记录”已经不再属于LayIM管辖
#更多亮点:潜藏在LayIM的每一处细节。
关于版权
LayIM目前并非开源产品(以后也许会开源),因此如果你是通过捐赠渠道获得LayIM,可以通过layer.config设定copyright: true来剔除LayIM主面板的关于信息,这就表示你已经过授权。当然,如果你想友好地保留,我们也是非常欢迎的。如果你通过非捐赠渠道获得LayIM,我们并不会进行追究,但是请勿进行销售,这是唯一的红线吧。
另外,再次强调一点:LayIM虽然并不开源,但layui是完全免费且开源的。LayIM是我们为数不多的接受收费的产品。因为一定资金的来源,是对我们整个开发流可持续发展的有力保障。仍然是那句话,如果你对LayIM的“收费”表示厌恶,请忽视它的存在。即便是没有一个人为LayIM买单,我们仍然会坚持初衷,即:通过极简的体验,拉近你的用户在web间的距离。
LayIM的作者是贤心一人,版权最终解释权归他所有。
Layui - 用心与你沟通
本文链接:webim框架【layim】一个纯前端webim插件http://www.51xuediannao.com/js/jquery/layim.html