layui

文章的主要简介

1. 核心方法
2. 各内置模块

核心方法

• layui.define([mods], callback)
  通过该方法可定义一个 Layui模块。参数mods是可选的，用于声明该模块所依赖的模块。callback即为模块加载完毕的回调函数，它返回一个exports参数，用于输出该模块的接口。
• config
• layui.use([mods], callback)
  Layui的内置模块并非默认就加载的，他必须在你执行该方法后才会加载。它的参数跟上述的 define方法完全一样。
  另外请注意，mods里面必须是一个合法的模块名，不能包含目录。如果需要加载目录，建议采用extend建立别名

个人觉得：所有对模块方法都定义在这里面，主要触发相应的操作，就在这里面找（包括渲染，监听，事件等等）

• layui.extend(options)
  拓展一个模块别名，如：layui.extend({test: ‘/res/js/test’})
• layui.onevent(modName, events, callback)
  自定义模块事件，属于比较高级的应用。有兴趣的同学可以阅读layui.js源码以及form模块
• layui.event(modName, events, params)
  执行自定义模块事件，搭配onevent使用
• render(options) (渲染时调用，等于use的回调函数)
  通过核心方法：laydate.render(options) 来设置基础参数
• layer.open(options) - 原始核心方法
  基本上是露脸率最高的方法，不管是使用哪种方式创建层，都是走layer.open()，创建任何类型的弹层都会返回一个当前层索引，上述的options即是基础参数，另外，该文档统一采用options作为基础参数的标识例子：

var index = layer.open({
  content: 'test'
});
//拿到的index是一个重要的凭据，它是诸如layer.close(index)等方法的必传参数。       
 

• done方法（个人觉得是成功后的回调）

各内置模块

1. 弹出层layer.
   1)ayer.ready(callback) - 初始化就绪
   由于我们的layer内置了轻量级加载器，所以你根本不需要单独引入css等文件。但是加载总是需要过程的。当你在页面一打开就要执行弹层时，你最好是将弹层放入ready方法中，如：

//页面一打开就执行弹层
layer.ready(function(){
  layer.msg('很高兴一开场就见到你');
}); 

2)layer.open(options) - 原始核心方法
基本上是露脸率最高的方法，不管是使用哪种方式创建层，都是走layer.open()，创建任何类型的弹层都会返回一个当前层索引，上述的options即是基础参数，另外，该文档统一采用options作为基础参数的标识例子：

var index = layer.open({
  content: 'test'
});
//拿到的index是一个重要的凭据，它是诸如layer.close(index)等方法的必传参数。

3)其他方法：
①success - 层弹出后的成功回调方法（即弹出层显示后会触发这个函数）
类型：Function，默认：null

当你需要在层创建完毕时即执行一些语句，可以通过该回调。success会携带两个参数，分别是当前层DOM当前层索引。如：

layer.open({
  content: '测试回调',
  success: function(layero, index){
    console.log(layero, index);
  }
});        
       

2. laydate
   1)通过核心方法：laydate.render(options) 来设置基础参数，也可以通过方法：laydate.set(options) 来设定全局基础参数.
   2)事实上，执行核心方法 laydate.render(options) 会返回一个当前实例对象。其中包含一些成员属性和方法，比如：hint方法

var ins1 = laydate.render({
  elem: '#test'
  ,change: function(value, date, endDate){
    ins1.hint(value); //在控件上弹出value值
  }
});

3)format - 自定义格式
类型：String，默认值：yyyy-MM-dd
通过日期时间各自的格式符和长度，来设定一个你所需要的日期格式。layDate 支持的格式如下：官方文档

//自定义日期格式
laydate.render({ 
  elem: '#test'
  ,format: 'yyyy年MM月dd日' //可任意组合
});

4)回调
①控件初始打开的回调
控件在打开时触发，回调返回一个参数：初始的日期时间对象

laydate.render({
  elem: '#test'
  ,ready: function(date){
    console.log(date); //得到初始的日期时间对象：{year: 2017, month: 8, date: 18, hours: 0, minutes: 0, seconds: 0}
  }
});

②日期时间被切换后的回调
年月日时间被切换时都会触发。回调返回三个参数，分别代表：生成的值、日期时间对象、结束的日期时间对象

laydate.render({
  elem: '#test'
  ,change: function(value, date, endDate){
    console.log(value); //得到日期生成的值，如：2017-08-18
    console.log(date); //得到日期时间对象：{year: 2017, month: 8, date: 18, hours: 0, minutes: 0, seconds: 0}
    console.log(endDate); //得结束的日期时间对象，开启范围选择（range: true）才会返回。对象成员同上。
  }
});
     

③控件选择完毕后的回调
点击日期、清空、现在、确定均会触发。回调返回三个参数，分别代表：生成的值、日期时间对象、结束的日期时间对象

laydate.render({
  elem: '#test'
  ,done: function(value, date, endDate){
    console.log(value); //得到日期生成的值，如：2017-08-18
    console.log(date); //得到日期时间对象：{year: 2017, month: 8, date: 18, hours: 0, minutes: 0, seconds: 0}
    console.log(endDate); //得结束的日期时间对象，开启范围选择（range: true）才会返回。对象成员同上。
  }
});

3. 数据表格
   1）三种初始化渲染方式
   ①方法渲染
   其实这是“自动化渲染”的手动模式，本质类似，只是“方法级渲染”将基础参数的设定放在了JS代码中，且原始的 table 标签只需要一个 选择器：

var table = layui.table;
 
//执行渲染
table.render({
  elem: '#demo' //指定原始表格元素选择器（推荐id选择器）
  ,height: 315 //容器高度
  ,cols: [{}] //设置表头
  //,…… //更多参数参考右侧目录：基本参数选项
});

②自动渲染
所谓的自动渲染，即：在一段 table 容器中配置好相应的参数，由 table 模块内部自动对其完成渲染，而无需你写初始的渲染方法。其特点在上文也有阐述。你需要关注的是以下三点：
步骤一： 带有 class=“layui-table” 的

标签。
步骤二：对标签设置属性 lay-data="" 用于配置一些基础参数
步骤三： 在

标签中设置属性lay-data=""用于配置表头信息

按照上述的规范写好table原始容器后，只要你加载了layui 的 table 模块，就会自动对其建立动态的数据表格。下面是一个示例：

  

    

      
ID
      
用户名
      
性别
      
城市
      
签名
      
积分
      
评分
      
职业
      
财富
    
  

2）异步数据接口
①parseData

table.render({
  elem: '#demp'
  ,url: ''
  ,parseData: function(res){ //res 即为原始返回的数据
    return {
      "code": res.status, //解析接口状态
      "msg": res.message, //解析提示文本
      "count": res.total, //解析数据长度
      "data": res.data.item //解析数据列表
    };
  }
  //,…… //其他参数
}); 

②request
用于对分页请求的参数：page、limit重新设定名称，如：

table.render({
  elem: '#demp'
  ,url: ''
  ,request: {
    pageName: 'curr' //页码的参数名称，默认：page
    ,limitName: 'nums' //每页数据量的参数名，默认：limit
  }
  //,…… //其他参数
});  
那么请求数据时的参数将会变为：?curr=1&nums=30

③response
table 组件默认规定的数据格式为：

默认规定的数据格式layui.code
{
  "code": 0,
  "msg": "",
  "count": 1000,
  "data": [{}, {}]
} 

如果你想重新规定返回的数据格式，那么可以借助 response 参数，如：

table.render({
  elem: '#demp'
  ,url: ''
  ,response: {
    statusName: 'status' //规定数据状态的字段名称，默认：code
    ,statusCode: 200 //规定成功的状态码，默认：0
    ,msgName: 'hint' //规定状态信息的字段名称，默认：msg
    ,countName: 'total' //规定数据总数的字段名称，默认：count
    ,dataName: 'rows' //规定数据列表的字段名称，默认：data
  } 
  //,…… //其他参数
}); 

那么上面所规定的格式为：

重新规定的数据格式layui.code
{
  "status": 200,
  "hint": "",
  "total": 1000,
  "rows": []
} 

④done - 数据渲染完的回调
无论是异步请求数据，还是直接赋值数据，都会触发该回调。你可以利用该回调做一些表格以外元素的渲染。

table.render({ //其它参数在此省略
  done: function(res, curr, count){
    //如果是异步请求数据方式，res即为你接口返回的信息。
    //如果是直接赋值的方式，res即为：{data: [], count: 99} data为当前页数据、count为数据总长度
    console.log(res);
    
    //得到当前页码
    console.log(curr); 
    
    //得到数据总量
    console.log(count);
  }
});

④表格重载
|

语法 说明 适用场景

table.reload(ID, options) 参数 ID 即为基础参数id对应的值，见：设定容器唯一ID
参数 options 即为各项基础参数 所有渲染方式
tableIns.reload(options) 参数同上
tableIns 可通过 var tableIns = table.render() 得到 仅限方法级渲染 | |

示例1：自动化渲染的重载layui.code
【HTML】
 …… 
 
【JS】
table.reload('idTest', {
  url: '/api/table/search'
  ,where: {} //设定异步数据接口的额外参数
  //,height: 300
});

示例2：方法级渲染的重载layui.code
//所获得的 tableIns 即为当前容器的实例
var tableIns = table.render({
  elem: '#id'
  ,cols: [] //设置表头
  ,url: '/api/data' //设置异步接口
  ,id: 'idTest'
}); 
 
//这里以搜索为例
tableIns.reload({
  where: { //设定异步数据接口的额外参数，任意设
    aaaaaa: 'xxx'
    ,bbb: 'yyy'
    //…
  }
  ,page: {
    curr: 1 //重新从第 1 页开始
  }
});
//上述方法等价于
table.reload('idTest', {
  where: { //设定异步数据接口的额外参数，任意设
    aaaaaa: 'xxx'
    ,bbb: 'yyy'
    //…
  }
  ,page: {
    curr: 1 //重新从第 1 页开始
  }
}); //只重载数据

⑤事件监听
语法：table.on(‘event(filter)’, callback); 注：event为内置事件名，filter为容器lay-filter设定的值
table模块在Layui事件机制中注册了专属事件，如果你使用layui.onevent()自定义模块事件，请勿占用table名。目前所支持的所有事件见下文

默认情况下，事件所监听的是全部的table模块容器，但如果你只想监听某一个容器，使用事件过滤器即可。
假设原始容器为：

那么你的事件监听写法如下：

//以复选框事件为例
table.on('checkbox(test)', function(obj){
  console.log(obj)
});
``

⑥监听头部工具栏事件
点击头部工具栏区域设定了属性为 lay-event="" 的元素时触发（该事件为 layui 2.4.0 开始新增）。如：

原始容器

 
工具栏模板：

 

//JS 调用：
table.render({
  elem: '#demo'
  ,toolbar: '#toolbarDemo'
  //,…… //其他参数
});
 
//监听事件
table.on('toolbar(test)', function(obj){
  var checkStatus = table.checkStatus(obj.config.id);
  switch(obj.event){
    case 'add':
      layer.msg('添加');
    break;
    case 'delete':
      layer.msg('删除');
    break;
    case 'update':
      layer.msg('编辑');
    break;
  };
});

⑦监听复选框选择
点击复选框时触发，回调函数返回一个object参数，携带的成员如下：

table.on('checkbox(test)', function(obj){
  console.log(obj.checked); //当前是否选中状态
  console.log(obj.data); //选中行的相关数据
  console.log(obj.type); //如果触发的是全选，则为：all，如果触发的是单选，则为：one
});

⑧监听单元格编辑
单元格被编辑，且值发生改变时触发，回调函数返回一个object参数，携带的成员如下：

table.on('edit(test)', function(obj){ //注：edit是固定事件名，test是table原始容器的属性 lay-filter="对应的值"
  console.log(obj.value); //得到修改后的值
  console.log(obj.field); //当前编辑的字段名
  console.log(obj.data); //所在行的所有相关数据  
});

⑨监听行单双击事件
点击或双击行时触发。该事件为 layui 2.4.0 开始新增

//监听行单击事件
table.on('row(test)', function(obj){
  console.log(obj.tr) //得到当前行元素对象
  console.log(obj.data) //得到当前行数据
  //obj.del(); //删除当前行
  //obj.update(fields) //修改当前行数据
});
 
//监听行双击事件
table.on('rowDouble(test)', function(obj){
  //obj 同上
});

4. 表单
   1）参数
   ①输入框
   required：注册浏览器所规定的必填字段
   lay-verify：注册form模块需要验证的类型
   class=“layui-input”：layui.css提供的通用CSS类
   ②下拉选择框
   属性selected可设定默认项
   属性disabled开启禁用，select和option标签都支持
   ③复选框
   属性title可自定义文本（温馨提示：如果只想显示复选框，可以不用设置title）
   属性checked可设定默认选中
   属性lay-skin可设置复选框的风格
   设置value="1"可自定义值，否则选中时返回的就是默认的on
   ④开关
   属性checked可设定默认开
   属性disabled开启禁用
   属性lay-text可自定义开关两种状态的文本
   设置value="1"可自定义值，否则选中时返回的就是默认的on
   ⑤单选
   属性title可自定义文本
   属性disabled开启禁用
   设置value="xxx"可自定义值，否则选中时返回的就是默认的on
   ⑥文本域
   class=“layui-textarea”：layui.css提供的通用CSS类
   ⑦组装行内表单
   class=“layui-inline”：定义外层行内
   class=“layui-input-inline”：定义内层行内

2）更新渲染
有些时候，你的有些表单元素可能是动态插入的。这时 form 模块 的自动化渲染是会对其失效的。虽然我们没有双向绑定机制（因为我们叫经典模块化框架，偷笑.gif） 但没有关系，你只需要执行 form.render(type, filter); 方法即可。

第一个参数：type，为表单的 type 类型，可选。默认对全部类型的表单进行一次更新。可局部刷新的 type 如下表：

参数（type）值 描述
select 刷新select选择框渲染
checkbox 刷新checkbox复选框（含开关）渲染
radio 刷新radio单选框框渲染

3)监听
①事件监听
语法：form.on(‘event(过滤器值)’, callback);

form模块在 layui 事件机制中注册了专属事件，所以当你使用layui.onevent()自定义模块事件时，请勿占用form名。form支持的事件如下

event 描述
select 监听select下拉选择事件
checkbox 监听checkbox复选框勾选事件
switch 监听checkbox复选框开关事件
radio 监听radio单选框事件
submit 监听表单提交事件

默认情况下，事件所监听的是全部的form模块元素，但如果你只想监听某一个元素，使用事件过滤器即可。
如：

form.on('select(test)', function(data){
  console.log(data);
});

4）表单初始赋值
语法：form.val(‘lay-filter的值’, object);

用于给指定表单集合的元素初始赋值。该方法为 layui 2.3.0 新增

//formTest 即 class="layui-form" 所在元素对应的 lay-filter="" 对应的值
form.val("formTest", {
  "username": "贤心" // "name": "value"
  ,"sex": "女"
  ,"auth": 3
  ,"check[write]": true
  ,"open": false
  ,"desc": "我爱layui"
})
      

第二个参数的键值是元素对应的 name 和 value。

5）表单验证
我们对表单的验证进行了非常巧妙的支持，大多数时候你只需要在表单元素上加上 lay-verify="" 属性值即可。如：

 
 
还同时支持多条规则的验证，如下：

上述对输入框定义了一个邮箱规则的校验，它会在 form 模块内部完成。目前我们内置的校验支持见上文的：预设元素属性

除了内置的校验规则外，你还可以自定义验证规则，通常对于比较复杂的校验，这是非常有必要的。

form.verify({
  username: function(value, item){ //value：表单的值、item：表单的DOM对象
    if(!new RegExp("^[a-zA-Z0-9_\u4e00-\u9fa5\\s·]+$").test(value)){
      return '用户名不能有特殊字符';
    }
    if(/(^\_)|(\__)|(\_+$)/.test(value)){
      return '用户名首尾不能出现下划线\'_\'';
    }
    if(/^\d+\d+\d$/.test(value)){
      return '用户名不能全为数字';
    }
  }
  
  //我们既支持上述函数式的方式，也支持下述数组的形式
  //数组的两个值分别代表：[正则匹配、匹配不符时的提示文字]
  ,pass: [
    /^[\S]{6,12}$/
    ,'密码必须6到12位，且不能出现空格'
  ] 
});      

当你自定义了类似上面的验证规则后，你只需要把 key 赋值给输入框的 lay-verify 属性即可：

文件上传
模板引擎 layui.laytpl

1. 四种方法
   laytpl 是 JavScript 模板引擎，在字符解析上有着比较出色的表现，欠缺之处在于异常调试上。由于传统意义的前端模板引擎已经变得不再流行，所以 laytpl 后续可能会进行重写，目前方向暂时还没有想好，预计会在layui比较稳定后开始实施。
   与一般的字符拼接不同的是，laytpl 的模板可与数据分离，集中把逻辑处理放在 View 层，提升代码可维护性，尤其是针对大量模板渲染的情况。

layui.use('laytpl', function(){
  var laytpl = layui.laytpl;
  
  //直接解析字符
  laytpl('{
    { d.name }}是一位公猿').render({
    name: '贤心'
  }, function(string){
    console.log(string); //贤心是一位公猿
  });
  
  //你也可以采用下述同步写法，将 render 方法的回调函数剔除，可直接返回渲染好的字符
  var string =  laytpl('{
    { d.name }}是一位公猿').render({
    name: '贤心'
  });
  console.log(string);  //贤心是一位公猿
  
  //如果模板较大，你也可以采用数据的写法，这样会比较直观一些
  laytpl([
    '{
    { d.name }}是一位公猿'
    ,'其它字符 {
    { d.content }}  其它字符'
  ].join(''))
}); 

你也可以将模板存储在页面或其它任意位置：

//第一步：编写模版。你可以使用一个script标签存放模板，如：

 
//第二步：建立视图。用于呈现渲染结果。

 
//第三步：渲染模版
var data = { //数据
  "title":"Layui常用模块"
  ,"list":[{"modname":"弹层","alias":"layer","site":"layer.layui.com"},{"modname":"表单","alias":"form"}]
}
var getTpl = demo.innerHTML
,view = document.getElementById('view');
laytpl(getTpl).render(data, function(html){
  view.innerHTML = html;
});
    

2. 模版语法

语法	说明	示例
{
    { d.field }}	输出一个普通字段，不转义html	
codelayui.code
{
    { d.content }}
              
{
    {= d.field }}	输出一个普通字段，并转义html	
codelayui.code
{
    {= d.title }}
              
{
    {# JavaScript表达式 }}	JS 语句。一般用于逻辑处理。用分隔符加 # 号开头。

注意：如果你是想输出一个函数，正确的写法是：{
    { fn() }}，而不是：{
    {# fn() }}	
codelayui.code
{
    {#  
  var fn = function(){
    return '2017-08-18';
  }; 
}}
 
{
    {#  if(true){ }}
  开始日期：{
    { fn() }}
{
    {#  } else { }}
  已截止
{
    {#  } }}           
              
{
    {! template !}}	对一段指定的模板区域进行过滤，即不解析该区域的模板。注：layui 2.1.6 新增	
codelayui.code
 {
    {! 这里面的模板不会被解析  !}}