更新：2021-3-8 4:43:49 阅读：672

# LayIM WAP版 前端文档

当前文档适用于 LayIM WAP 端版本

> LayIM 是基于 layui 的一款用于开发网页端聊天系统的纯静态 UI 界面解决方案，采用 HTML、CSS、JavaScript 编写，其包含的只是一套前端源代码素材和相关的模拟示例，不具备后台程序以数据库存储等功能。因此实际使用时，需要自己开发后端语言或对接云服务平台（如：融云、环信等）。

- 开始使用
- 初始化配置
- init数据格式
- 上传图片/文件
- 扩展更多列表
- 扩展工具栏
- 更多聊天记录
- 富文本内容格式（参考pc版）
- WebSocket（参考pc版）
- 监听发送的消息
- 监听接受的消息
- 监听聊天窗口切换
- 监听点击新的朋友
- 监听面板返回
- 监听查看聊天信息
- 自定义聊天窗口
- 弹出一个新面板
- 标注和隐藏新动态
- 更新当前会话状态
- 添加好友/群到主面板
- 移除主面板的好友/群
- 好友置灰和取消
- 获取缓存
- 剔除头部栏

## 开始使用

文件引入方面，和 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应用在第三方，建议保留，即不设置。

## init数据格式

较之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}

- 