表单模块文档 - layui.form

我们通常会在最常用的模块上耗费更多的精力,用尽可能简单的方式诠释 layui 所带来的便捷性。显而易见,form 是我们非常看重的一块。于是它试图用一贯极简的姿态,去捕获你对它的深深青睐。寄托在原始表单元素上的属性设定,及其全自动的初始渲染,和基于事件驱动的接口书写方式,会让你觉得,传统模式下的组件调用形式,也可以是那样的优雅、简单。然而文字的陈述始终是苍白的,所以用行动慢慢感受 layui.form 给你的项目带来的效率提升吧。

模块加载名称:form

使用

layui 针对各种表单元素做了较为全面的UI支持,你无需去书写那些 UI 结构,你只需要写 HTML 原始的 input、select、textarea 这些基本的标签即可。我们在 UI 上的渲染只要求一点,你必须给表单体系所在的父元素加上class=”layui-form”,一切的工作都会在你加载完form模块后,自动完成。如下是一个最基本的例子:

  1. <!DOCTYPE html>
  2. <html>
  3. <head>
  4. <meta charset="utf-8">
  5. <title>layui.form小例子</title>
  6. <link rel="stylesheet" href="layui.css" media="all">
  7. </head>
  8. <body>
  9. <form class="layui-form"> <!-- 提示:如果你不想用form,你可以换成div等任何一个普通元素 -->
  10. <div class="layui-form-item">
  11. <label class="layui-form-label">输入框</label>
  12. <div class="layui-input-block">
  13. <input type="text" name="" placeholder="请输入" autocomplete="off" class="layui-input">
  14. </div>
  15. </div>
  16. <div class="layui-form-item">
  17. <label class="layui-form-label">下拉选择框</label>
  18. <div class="layui-input-block">
  19. <select name="interest" lay-filter="aihao">
  20. <option value="0">写作</option>
  21. <option value="1">阅读</option>
  22. </select>
  23. </div>
  24. </div>
  25. <div class="layui-form-item">
  26. <label class="layui-form-label">复选框</label>
  27. <div class="layui-input-block">
  28. <input type="checkbox" name="like[write]" title="写作">
  29. <input type="checkbox" name="like[read]" title="阅读">
  30. </div>
  31. </div>
  32. <div class="layui-form-item">
  33. <label class="layui-form-label">开关关</label>
  34. <div class="layui-input-block">
  35. <input type="checkbox" lay-skin="switch">
  36. </div>
  37. </div>
  38. <div class="layui-form-item">
  39. <label class="layui-form-label">开关开</label>
  40. <div class="layui-input-block">
  41. <input type="checkbox" checked lay-skin="switch">
  42. </div>
  43. </div>
  44. <div class="layui-form-item">
  45. <label class="layui-form-label">单选框</label>
  46. <div class="layui-input-block">
  47. <input type="radio" name="sex" value="0" title="男">
  48. <input type="radio" name="sex" value="1" title="女" checked>
  49. </div>
  50. </div>
  51. <div class="layui-form-item layui-form-text">
  52. <label class="layui-form-label">请填写描述</label>
  53. <div class="layui-input-block">
  54. <textarea placeholder="请输入内容" class="layui-textarea"></textarea>
  55. </div>
  56. </div>
  57. <div class="layui-form-item">
  58. <div class="layui-input-block">
  59. <button class="layui-btn" lay-submit lay-filter="*">立即提交</button>
  60. <button type="reset" class="layui-btn layui-btn-primary">重置</button>
  61. </div>
  62. </div>
  63. <!-- 更多表单结构排版请移步文档左侧【页面元素-表单】一项阅览 -->
  64. </form>
  65. <script src="layui.js"></script>
  66. <script>
  67. layui.use('form', function(){
  68. var form = layui.form;
  69.  
  70. //各种基于事件的操作,下面会有进一步介绍
  71. });
  72. </script>
  73. </body>
  74. </html>

正如你上述看到的,你必须放入 layui 所规范的元素结构,form 模块才会对其进行重置渲染。值得注意的是,在具体的每一块表单元素中,你仍是像往日一样写 input 等标签即可。另外,我们对我们所规范的结构进行了响应式的支持,而针对一些不同的表单排版,比如行内表单,你也只需要设定我们所定义好的 class 即可。关于这一块,你可以移步页面元素的表单文档中做详细了解。而事实上你的大部分焦点可能也在那里,但当前这篇文档主要还是介绍 form 整体模块。

更新渲染

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

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

参数(type)值描述
select刷新select选择框渲染
checkbox刷新checkbox复选框(含开关)渲染
radio刷新radio单选框框渲染
  1. form.render(); //更新全部
  2. form.render('select'); //刷新select选择框渲染
  3. //……

第二个参数:filter,为 class=”layui-form” 所在元素的 lay-filter=”” 的值。你可以借助该参数,对表单完成局部更新。

  1. HTML
  2. <div class="layui-form" lay-filter="test1">
  3. </div>
  4.  
  5. <div class="layui-form" lay-filter="test2">
  6. </div>
  7.  
  8. JavaScript
  9. form.render(null, 'test1'); //更新 lay-filter="test1" 所在容器内的全部表单状态
  10. form.render('select', 'test2'); //更新 lay-filter="test2" 所在容器内的全部 select 状态
  11. //……

预设元素属性

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

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

上述的lay-verifylay-skinlay-filterlay-submit神马的都是我们所说的预设的元素属性,他们可以使得一些交互操作交由form模块内部、或者你来借助form提供的JS接口精确控制。目前我们可支持的属性如下表所示:

属性名属性值说明
title任意字符设定元素名称,一般用于checkbox、radio框
lay-skinswitch(开关风格) primary(原始风格)定义元素的风格,目前只对 checkbox 元素有效,可将其转变为开关样式
lay-ignore任意字符或不设值是否忽略元素美化处理。设置后,将不会对该元素进行初始化渲染,即保留系统风格
lay-filter任意字符事件过滤器,主要用于事件的精确匹配,跟选择器是比较类似的。其实它并不私属于form模块,它在 layui 的很多基于事件的接口中都会应用到。
lay-verifyrequired(必填项)
phone(手机号)
email(邮箱)
url(网址)
number(数字)
date(日期)
identity(身份证)
自定义值
同时支持多条规则的验证,格式:lay-verify=”验证A|验证B”
如:lay-verify=”required|phone|number”

另外,除了我们内置的校验规则,你还可以给他设定任意的值,比如lay-verify=”pass”,那么你就需要借助form.verify()方法对pass进行一个校验规则的定义。详见表单验证
lay-verTypetips(吸附层)
alert(对话框)
msg(默认)
用于定义异常提示层模式。
lay-reqText任意字符用于自定义必填项(即设定了 lay-verify=”required” 的表单)的提示文本
注意:该功能为 layui 2.5.0 新增
lay-submit无需填写值绑定触发提交的元素,如button

事件监听

语法:form.on(‘event(过滤器值)’, callback);

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

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

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

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

监听select选择

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

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

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

监听checkbox复选

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

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

监听switch开关

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

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

监听radio单选

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

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

监听submit提交

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

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

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

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

你可以把*号换成任意的值,如:lay-filter=”go”,但监听事件时也要改成 form.on(‘submit(go)’, callback);

表单赋值 / 取值

语法:form.val(‘filter’, object);

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

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

第二个参数中的键值是表单元素对应的 namevalue

表单验证

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

  1. <input type="text" lay-verify="email">
  2.  
  3. 还同时支持多条规则的验证,如下:
  4. <input type="text" lay-verify="required|phone|number">

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

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

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

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

  1. <input type="text" lay-verify="username" placeholder="请输入用户名">
  2. <input type="password" lay-verify="pass" placeholder="请输入密码">

再次温馨提示一下

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

layui - 用心与你沟通