表单组件
表单组件form是包含输入框、选择框、复选框、开关、单选框等表单项组件的集合,主要用于对表单域进行各类动态化渲染和相关的交互操作。form是 Layui 最常用的组件之一。
布局
- 通过 class=“layui-form” 定义一个表单域,通常设置在标签上, 或普通
标签亦可。
- 通过 class=“layui-form-item” 定义一个块级元素的表单项容器
- 通过 class=“layui-form-label” 定义标签
- 通过 class=“layui-input-block” 定义表单项父容器为块级元素
- 通过 class=“layui-input-inline” 或 class=“layui-inline” 定义表单项父容器为行内块元素
属性
属性 | 值 | 描述 |
---|---|---|
title | 自定义 | 设置表单元素标题,一般用于 checkbox,radio 元素 |
lay-filter | 自定义 | 设置表单元素的过滤器,以便用于执行相关方法时的参数匹配 |
lay-verify | required、phone、email 、url、number、date、identity、自定义规则值 | 设置表单项的验证规则,支持单条或多条规则如:lay-verify=“required”、lay-verify="required l email"lay-verify=“其他自定义规则值” |
lay-vertype | tips吸附层、alert 对话框、msg 默认 | 设置验证异常时的提示层模式 |
lay-reqtext | 自定义 | 设置必填项(lay-verify=“required”)的默认提示文本 |
lay-skin | 设置 UI 风格。 元素 私有属性 | |
lay-submit | 无需值 | 设置元素(一般为 标签)触发 submit 提交事件 |
lay-ignore | 无需值 | 设置表单元素忽略渲染,即让元素保留系统原始 UI 风格 |
<form class="layui-form" lay-filter="form-1">
<input type="text" class="layui-input" lay-verify="email">
<input type="checkbox" lay-skin="switch" lay-filter="agree" title="同意">
<button class="layui-btn" lay-submit>提交</button>
</form>
API
API | 描述 |
---|---|
var form = layui.form | 获得 form 模块 |
form.render(type, filter) | 表单域组件渲染,核心方法 |
form.verify(obj) | 自定义表单验证的规则 |
form.val(filter, obj) | 表单赋值或取值 |
form.on(‘event(filter)’, callback) | 表单事件监听 |
form.set(options) | 设置 form 组件全局配置项 |
form.config | 获取 form 组件全局配置项 |
渲染
form.render(type, filter);
- 参数 type 可选,对应表单组件类型,支持:input,select,checkbox,radio;若不填,则指向所有类型。
- 参数 filter 可选,对应 class=“layui-form” 所在元素的 lay-filter 属性值,用于指定需渲染的表单区域。
form 组件会在元素加载完毕后,自动对所有表单区域完成一次渲染,因此该方法主要用于对动态插入的表单元素的渲染。
<form class="layui-form" lay-filter="test">
动态插入的表单域
</form>
<!-- import layui -->
<script>
layui.use(function(){
var form = layui.form;
// 当表单元素被动态插入时,需主动进行组件渲染才能显示
form.render(); // 渲染全部表单
form.render('select'); // 仅渲染 select 元素
form.render(null, 'test'); // 仅渲染 lay-filter="test" 的容器内的全部表单
form.render('checkbox', 'test'); // 仅渲染 lay-filter="test" 的容器内的 checkbox 元素
})
</script>
验证
Layui 对表单验证做了巧妙的支持,只需在表单元素上设置 lay-verify=“” 属性值即可指定验证规则,如:
<div class="layui-form">
<input type="text" lay-verify="required" placeholder="必填项">
<input type="text" lay-verify="email" placeholder="非必填项,但若有值则验证邮箱格式">
<input type="text" lay-verify="required|number" placeholder="必填项,并验证数字格式">
<button class="layui-btn" lay-submit>提交</button>
</div>
自定义验证规则
form.verify(obj);
- 参数 obj 是一个对象,用于定义验证规则的集合。
除了内置的验证规则外,form 还允许自定义验证规则,规则以函数命名,返回的参数如下:
form.verify({
// 必填项
rule1: function(value, elem) {
console.log(value); // 当前进入验证的表单项的值
console.log(elem); // 当前进入验证的表单项的 DOM 元素
// 自定义规则
if (value.length < 6) {
return '不能小于 6 个字符';
}
},
// 非必填项,只有当值填写时才验证自定义规则
rule2: function(value, elem) {
if (!value) return; // 若值未填写,不进行后续规则验证
// 自定义规则
if (/^[A-Z]/.test(value)) {
return '必须用大写字符开头';
}
},
// 自定义提示方式
rule3: function(value, elem) {
// 自定义规则和自定义提示方式
if(value === 'xxx'){
alert('用户名不能为敏感词'); // 此处以系统自带的 alert 提示方式为例
return true; // 返回 true 即可阻止 form 默认的提示风格
}
}
});
完整示例:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Demo</title>
<!-- 请勿在项目正式环境中引用该 layui.css 地址 -->
<link href="//unpkg.com/layui@2.9.1/dist/css/layui.css" rel="stylesheet">
</head>
<body>
<form class="layui-form">
<input type="text" name="username" lay-verify="required|username" placeholder="用户名" class="layui-input">
<hr>
<input type="password" name="password" lay-verify="password" placeholder="密码" class="layui-input">
<hr>
<input type="text" name="motto" lay-verify="motto" placeholder="座右铭" class="layui-input">
<hr>
<button class="layui-btn" lay-submit lay-filter="demo-verify">提交</button>
</form>
<!-- 请勿在项目正式环境中引用该 layui.js 地址 -->
<script src="//unpkg.com/layui@2.9.1/dist/layui.js"></script>
<script>
layui.use(function(){
var form = layui.form;
// 自定义验证规则
form.verify({
// 验证用户名,且为必填项
username: function(value, elem){
if (!new RegExp("^[a-zA-Z0-9_\u4e00-\u9fa5\\s·]+$").test(value)) {
return '用户名不能有特殊字符';
}
if (/(^_)|(__)|(_+$)/.test(value)) {
return '用户名首尾不能出现下划线';
}
if (/^\d+$/.test(value)) {
return '用户名不能全为数字';
}
},
// 验证密码,且为必填项
password: function(value, elem) {
if (!/^[\S]{6,16}$/.test(value)) {
return '密码必须为 6 到 16 位的非空字符';
}
},
// 验证座右铭,且为非必填项
motto: function(value, elem) {
if (!value) return; // 非必填
// 自定义规则
if (!new RegExp("^[a-zA-Z0-9_\u4e00-\u9fa5\\s·]+$").test(value)) {
return '座右铭不能有特殊字符';
}
}
});
// 提交事件
form.on('submit(demo-verify)', function(data){
var field = data.field; // 获取表单字段值
// 显示填写结果,仅作演示用
layer.alert(JSON.stringify(field), {
title: '当前填写的字段值'
});
// 此处可执行 Ajax 等操作
// …
return false; // 阻止默认 form 跳转
});
})
</script>
</body>
</html>
赋值/取值
form.val(filter, obj);
- 参数 filter 为表单域容器(class=“layui-form”)的 lay-filter 属性值
- 参数 obj 可选。若参数存在,则对表单域进行赋值;若参数不存在,则为对表单域进行取值。
form.val('demo-val-filter', {
"username": "贤心", // "name": "value"
"password": "AAAAAA",
"interest": 1,
"like[write]": true, // 复选框选中状态
"close": true, // 开关状态
"sex": "女",
"desc": "Layui 用于更简单快速地构建网页界面"
});
var data = form.val('demo-val-filter');
提交
在表单域中,对指定按钮设置 lay-submit 属性,即意味着点击该按钮时,将触发提交事件。如:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Demo</title>
<!-- 请勿在项目正式环境中引用该 layui.css 地址 -->
<link href="//unpkg.com/layui@2.9.1/dist/css/layui.css" rel="stylesheet">
</head>
<body>
<form class="layui-form">
<input type="text" name="nickname" lay-verify="required" class="layui-input">
<hr>
<button class="layui-btn" lay-submit lay-filter="demo-submit">提交按钮</button>
<button class="layui-btn" id="test-btn-other">普通按钮</button>
</form>
<!-- 请勿在项目正式环境中引用该 layui.js 地址 -->
<script src="//unpkg.com/layui@2.9.1/dist/layui.js"></script>
<script>
layui.use(function(){
var $ = layui.$;
var form = layui.form;
var layer = layui.layer;
// 提交事件
form.on('submit(demo-submit)', function(data){
var field = data.field; // 获取表单全部字段值
var elem = data.elem; // 获取当前触发事件的元素 DOM 对象,一般为 button 标签
var elemForm = data.form; // 获取当前表单域的 form 元素对象,若容器为 form 标签才会返回。
// 显示填写结果,仅作演示用
layer.alert(JSON.stringify(field), {
title: '当前填写的字段值'
});
// 此处可执行 Ajax 等操作
// …
return false; // 阻止默认 form 跳转
});
// 普通按钮
$('#test-btn-other').on('click', function(){
layer.msg('点击未设置特定属性的按钮不会触发组件的提交事件');
return false;
});
});
</script>
</body>
</html>
事件
form.on(‘event(filter)’, callback);
- 参数 event(filter) 是一个特定结构。event 为事件名,支持:select,checkbox,switch,radio,submit;filter 为元素属性 lay-filter 对应的值,若不填,则指向所有同类组件的事件。
- 参数 callback 为事件执行时的回调函数,并返回一个包含各种值的 object 类型的参数。
如下以 select 事件为例:
// 指向所有 select 组件的选择事件
form.on('select', function(data){
console.log(data);
});
// 指向元素为 `<select lay-filter="test"></select>` 的选择事件
form.on('select(test)', function(data){
console.log(data);
});