搜索组件模块
grid 栅格布局
layout admin 布局
color 颜色
iconfont 字体图标
font 字体大小 颜色
animation 动画
button 按钮
form 表单组
input 输入框
select 下拉选择框
checkbox 复选框
switch 开关
radio 单选框
textarea 文本域
nav 导航菜单
menu 基础通用菜单
breadcrumb 面包屑
tabs 选项卡
progress 进度条
panel 面板 / card
collapse 折叠面板/手风琴
table 表格元素
badge 徽章
timeline 时间线
blockquote 引用块
fieldset 字段集
hr 分割线
layer 弹出层/弹窗综合
laydate 日期时间选择器
laypage 分页
laytpl 模板引擎
table 数据表格
form 表单模块
upload 文件/图片上传
dropdown 下拉菜单
contextmenu 右键菜单
transfer 穿梭框
tree 树形菜单
colorpicker 颜色选择器
element 常用元素操作
slider 滑块
rate 评分
carousel 轮播/跑马灯
layedit 富文本编辑器
flow 信息流/图片懒加载
util 工具集
code 代码文本行修饰
layim
layuiadmin
-

表单模块文档 - layui.form

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

模块加载名称:form

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

layui.form小例子code

  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. </script>
  72. </body>
  73. </html>

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

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

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

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

例子code

  1. form.render(); //更新全部
  2. form.render('select'); //刷新select选择框渲染
  3. //……

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

例子code

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

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

</>code

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

另外,除了我们内置的校验规则,你还可以给他设定任意的值,比如lay-verify="pass",那么你就需要借助form.verify()方法对pass进行一个校验规则的定义。详见表单验证
lay-verType tips(吸附层)
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模块元素,但如果你只想触发某一个元素,使用事件过滤器即可。
如:<select lay-filter="test"></select>

</>code

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

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

语法code

  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)即可。下面将不再对此进行备注。

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

语法code

  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. });

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

语法code

  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单选框被点击时触发,回调函数返回一个object参数,携带两个成员:

语法code

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

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

语法code

  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(*)中的 * 号为事件过滤器的值,是在你绑定执行提交的元素时设定的,如:

</>code

  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 开始新增

</>code

  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. var data1 = form.val("formTest");

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

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

</>code

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

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

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

语法code

  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. //如果不想自动弹出默认提示框,可以直接返回 true,这时你可以通过其他任意方式提示(v2.5.7 新增)
  13. if(value === 'xxx'){
  14. alert('用户名不能为敏感词');
  15. return true;
  16. }
  17. }
  18. //我们既支持上述函数式的方式,也支持下述数组的形式
  19. //数组的两个值分别代表:[正则匹配、匹配不符时的提示文字]
  20. ,pass: [
  21. /^[\S]{6,12}$/
  22. ,'密码必须6到12位,且不能出现空格'
  23. ]
  24. });

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

</>code

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

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

layui - 在每一个细节中,用心与你沟通