 表单模块文档 - layui.form

尽管 form 会对表单进行自动渲染，但当元素动态插入时，需通过核心方法 form.render(type, filter) 来进行渲染。
其中参数 type为表单的元素类型，可选。默认对全部类型的表单进行一次渲染。也可指向 type 进行渲染：

// 示例
var form = layui.form;
 
// 一般当表单存在动态生成时，进行渲染
form.render(); // 渲染全部
form.render('select'); //渲染 select 选择框
      

第二个参数 filter 为 class="layui-form" 所在元素的 lay-filter="" 的值。你可以借助该参数，对表单完成区域渲染。

<div class="layui-form" lay-filter="test1">
  …
</div>
      
<script>
layui.use('form', function(){
  var form = layui.form;
 
  // 一般当表单存在动态生成时，进行渲染
  form.render(null, 'test1'); // 渲染所在容器内的全部表单
  form.render('select', 'test1'); // 渲染所在容器内的 select 元素
});
</script>
      

定向渲染 - 注：v2.7.0 新增

<div class="layui-form">
  <select id="select-id">
    <option value="a">A</option>
  </select>
</div>
 
<script> 
layui.use('form', function(){
  var $ = layui.$;
  var form = layui.form;
  
  // 定向渲染（一般当表单存在动态生成时，进行渲染）
  form.render($('#select-id')); // 传入需要渲染的相应表单元素的 jQuery 对象 
});
</script>  
      

事实上在使用表单时，你的一半精力可能会在元素本身上。所以我们把一些基础属性的配置恰恰安放在了标签本身上。如：

<input type="text" lay-verify="email">
<input type="checkbox" checked lay-skin="switch" lay-filter="encrypt" title="是否加密">
<button lay-submit>提交</button>
      

上述 lay- 前缀的属性即是表单所能识别的元素属性，他们可以使得一些交互操作交由 form 模块内部处理，或者借助 form 提供的 api 精确操作。目前我们可支持的属性如下表所示：

var form = layui.form; // 获得 form 模块对象
 
form.render(type, filter); // 渲染 - 核心方法
form.validate(elem); // 执行验证，elem 为需要验证的区域选择器或 DOM 对象  注：v2.7.0 新增
form.verify(obj); // 定义表单验证的规则（详见下文）
form.on('event(filter)', callback); // 事件
form.val(filter, object); // 表单赋值或取值。 如果 object 参数存在，则为赋值，否则为取值。
form.submit(filter, callback); // 用于执行指定表单的提交 注：v2.7.0 新增
form.config; // 获取 form 模块的配置信息
form.set(options); // 设置 form 的配置信息
      

语法：form.on('event(filter)', callback);

默认情况下，事件所触发的是全部的 form 模块元素，但如果你只想触发某一个元素，使用事件过滤器即可。
如：<select lay-filter="test"></select>

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

下拉选择框被选中时触发，回调函数返回一个object参数，携带两个成员：

form.on('select(filter)', function(data){
  console.log(data.elem); //得到select原始DOM对象
  console.log(data.value); //得到被选中的值
  console.log(data.othis); //得到美化后的DOM对象
});      
      

请注意：如果你想触发所有的select，去掉过滤器(filter)即可。下面将不再对此进行备注。

复选框点击勾选时触发，回调函数返回一个object参数，携带两个成员：

form.on('checkbox(filter)', function(data){
  console.log(data.elem); //得到checkbox原始DOM对象
  console.log(data.elem.checked); //是否被选中，true或者false
  console.log(data.value); //复选框value值，也可以通过data.elem.value得到
  console.log(data.othis); //得到美化后的DOM对象
});        
      

开关被点击时触发，回调函数返回一个object参数，携带两个成员：

form.on('switch(filter)', function(data){
  console.log(data.elem); //得到checkbox原始DOM对象
  console.log(data.elem.checked); //开关是否开启，true或者false
  console.log(data.value); //开关value值，也可以通过data.elem.value得到
  console.log(data.othis); //得到美化后的DOM对象
});  
      

radio单选框被点击时触发，回调函数返回一个object参数，携带两个成员：

form.on('radio(filter)', function(data){
  console.log(data.elem); //得到radio原始DOM对象
  console.log(data.value); //被点击的radio的value值
});  
      

按钮点击或者表单被执行提交时触发，其中回调函数只有在验证全部通过后才会进入，回调返回三个成员：

form.on('submit(*)', function(data){
  console.log(data.elem) //被执行事件的元素DOM对象，一般为button对象
  console.log(data.form) //被执行提交的form对象，一般在存在form标签时才会返回
  console.log(data.field) //当前容器的全部表单字段，名值对形式：{name: value}
  return false; //阻止表单跳转。如果需要表单跳转，去掉这段即可。
});
      

再次温馨提示：上述的submit(*)中的 * 号为事件过滤器的值，是在你绑定执行提交的元素时设定的，如：

<button lay-submit lay-filter="*">提交</button>     
      

你可以把*号换成任意的值，如：lay-filter="go"，但触发事件时也要改成 form.on('submit(go)', callback);

执行提交方法：

有时我们未必要通过点击表单内的按钮来进行提交，这时需要用到提交方法：form.submit(filter, callback);

<div class="layui-form" lay-filter="test1">
  <!-- 表单内部 -->
</div>
 
<button id="testSubmitBtn">任意位置按钮</button>
 
<script>
layui.use('form', function(){ 
  var form = layui.form;
  
  //方法提交
  $('#testSubmitBtn').on('click', function(data){
    form.submit('test1', function(data){ // 注：v2.7.0 新增
      // 回调函数返回结果跟上述 submit 事件完全一致
      var field = data.field;
      // do something
    });
    return false;
  });
});
</script>
      

语法：form.val('filter', object);

用于给指定表单集合的元素赋值和取值。如果 object 参数存在，则为赋值；如果 object 参数不存在，则为取值。
注：其中「取值」功能为 layui 2.5.5 开始新增

//给表单赋值
form.val("formTest", { //formTest 即 class="layui-form" 所在元素属性 lay-filter="" 对应的值
  "username": "贤心" // "name": "value"
  ,"sex": "女"
  ,"auth": 3
  ,"check[write]": true
  ,"open": false
  ,"desc": "我爱layui"
});
 
//获取表单区域所有值
var data1 = form.val("formTest");
      

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

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

<input type="text" lay-verify="email"> 
 
还同时支持多条规则的验证，如下：
<input type="text" lay-verify="required|phone|number">
      

上述对输入框定义了一个邮箱规则的校验，它会在 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 '用户名不能全为数字';
    }
    
    //如果不想自动弹出默认提示框，可以直接返回 true，这时你可以通过其他任意方式提示（v2.5.7 新增）
    if(value === 'xxx'){
      alert('用户名不能为敏感词');
      return true;
    }
  }
  
  //我们既支持上述函数式的方式，也支持下述数组的形式
  //数组的两个值分别代表：[正则匹配、匹配不符时的提示文字]
  ,pass: [
    /^[\S]{6,12}$/
    ,'密码必须6到12位，且不能出现空格'
  ] 
});      
      

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

<input type="text" name="username" lay-verify="username">
<input type="password" name="pass" lay-verify="pass">
<input type="checkbox" name="agreement" lay-verify="required" title="同意">
      

当表单提交时，自动触发验证

var layer = layui.layer;
var form = layui.form;
 
// 提交事件
form.on('submit(*)', function(data){
  var field = data.field;
  
  // 若需验证 checkbox 是否勾选，则需判断其值是否存在，如：
  if(!field.agreement){
    layer.msg('请同意');
    return false;
  }
  
  // 验证均通过后的操作（如 Ajax 提交）
  // …
  
  return false;
});
      

主动触发验证：

方法：form.validate(elem); 若验证通过返回 true，否则 false

<div class="layui-form">  
  <div class="layui-form-item">
    <label class="layui-form-label">手机</label>
    <div class="layui-input-block">
      <input type="tel" name="phone" lay-verify="required|phone" class="layui-input demo-phone">
    </div>
  </div>
  <div class="layui-form-item">
    <label class="layui-form-label">验证码</label>
    <div class="layui-input-inline">
      <input type="text" name="vercode" lay-verify="required" class="layui-input">
    </div>
    <div class="layui-inline"> 
      <button type="button" class="layui-btn layui-btn-primary" lay-on="get-vercode">获取验证码</button>
    </div>
  </div>
</div>
 
<script>
layui.use(['form', 'util'], function(){
  var form = layui.form;
  var layer = layui.layer;
  var util = layui.util;
  
  // 自定义普通事件
  util.on('lay-on', {
    "get-vercode": function(othis){
      var isValid = form.validate('.demo-phone');  // 注：v2.7.0 新增
  
      // 验证通过
      if(isValid){
        layer.msg('手机号验证通过，执行发送验证码的操作');
      }
    }
  });
});
</script>
      

针对一些不同的表单排版，比如行内表单、整体表单风格、按钮风格等等，请移步到文档导航左侧【页面元素】下的指定分类即可。