表单组件 🔥

表单组件form是包含输入框、选择框、复选框、开关、单选框等表单项组件的集合,主要用于对表单域进行各类动态化渲染和相关的交互操作。form是 Layui 最常用的组件之一。

示例

综合演示

方框风格

登录模板 2.8+

注册模板 2.8+

更多其他表单模板均可自由布局实现,为了避免影响文档其他重要版面的阅读,我们就不做过多演示了。

表单布局

🌕 普通布局

在上文的「综合演示」示例中,我们用的是 form 组件自身的普通布局。其要点为:

通过 class="layui-form" 定义一个表单域,通常设置在

标签上, 或普通
标签亦可。

通过 class="layui-form-item" 定义一个块级元素的表单项容器

通过 class="layui-form-label" 定义标签

通过 class="layui-input-block" 定义表单项父容器为块级元素

通过 class="layui-input-inline" 或 class="layui-inline" 定义表单项父容器为行内块元素

即必须按照规定的层级定义相应的 class。

🌕 栅格布局

form 还可以借助栅格实现更灵活的响应式布局。

API

API

描述

var form = layui.form

获得 form 模块。

form.render(type, filter)

表单域组件渲染,核心方法。#用法

form.verify(obj)

自定义表单验证的规则。#用法

form.validate(elem) 2.7+

主动触发执行验证。#用法

form.val(filter, obj)

表单赋值或取值。 #用法

form.submit(filter, callback) 2.7+

用于主动执行指定表单的提交。#用法

form.on('event(filter)', callback)

事件。#用法

form.set(options)

设置 form 组件全局配置项。

form.config

获取 form 组件全局配置项。

属性

在表单域中,有时还需要定义一些特定属性来配合组件的使用,它们一般以 lay-* 为命名格式,如:

以下为 form 组件的特定属性列表:

属性

值

描述

title

自定义

设置表单元素标题,一般用于 checkbox,radio 元素

lay-filter

自定义

设置表单元素的过滤器,以便用于执行相关方法时的参数匹配

lay-verify

required必填项 phone手机号 email邮箱 url网址number数字date日期identity身份证自定义规则值

设置表单项的验证规则,支持单条或多条规则(多条用|分隔),如:lay-verify="required" lay-verify="required|email"lay-verify="其他自定义规则值" 自定义规则的用法:#详见注:2.8.3 版本中调整了内置规则,不再强制必填。如需保留必填,可叠加 required 规则,如: lay-verify="required|number"

lay-vertype

tips吸附层alert 对话框msg 默认

设置验证异常时的提示层模式

lay-reqtext

自定义

设置必填项(lay-verify="required")的默认提示文本

lay-affix

#详见

输入框动态点缀,元素 私有属性

lay-skin

#详见

设置 UI 风格。 , 元素 私有属性

lay-search

2.9.15+ lay-search="{caseSensitive:false, fuzzy: false}" caseSensitive 是否区分大小写,默认值为 false fuzzy是否开启模糊匹配,开启后将会忽略匹配字符出现在字符串中的位置,默认值为 false 设置cs区分大小写(2.9.15+ 已弃用)

给 select 组件开启搜索功能。 元素 私有属性

lay-append-to 2.9.12+ 实验性

body

是否将 select 面板追加到 body 元素中。 元素 私有属性

lay-submit

无需值

设置元素(一般为

注:上述代码指定的均为内置的验证规则,具体可参考:#属性介绍

自定义验证规则

form.verify(obj);

参数 obj 是一个对象,用于定义验证规则的集合。

除了内置的验证规则外,form 还允许自定义验证规则,规则以函数命名,返回的参数如下:

// 自定义验证规则

form.verify({

rule: function(value, elem) {

console.log(value); // 当前进入验证的表单项的值

console.log(elem); // 当前进入验证的表单项的 DOM 元素

}

});

在自定义规则中,可根据规则函数返回的 value 自行判断是否必填,如:

form.verify({

// 必填项

rule1: function(value, elem) {

// 自定义规则

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 默认的提示风格

}

}

});

以下是一个自定义验证规则的示例:

更多「自定义验证规则」示例参考:

将 form 提示语显示在表单项旁边,并在提交时批量触发验证

主动触发验证 2.7+

form.validate(elem);

参数 elem 为元素选择器或 jQuery 对象; 若验证通过,该方法将返回 true,否则返回 false

赋值/取值

form.val(filter, obj);

参数 filter 为表单域容器(class="layui-form")的 lay-filter 属性值

参数 obj 可选。若参数存在,则对表单域进行赋值;若参数不存在,则为对表单域进行取值。

提交

表单的提交可以通过事件触发或方法触发

提交事件

在表单域中,对指定按钮设置 lay-submit 属性,即意味着点击该按钮时,将触发提交事件。如:

提交方法 2.7+

form.submit(filter, callback);

参数 filter 为表单域容器的 lay-filter 属性值

参数 callback 为执行提交事件后的回调函数

使用该方法可以实现在任意位置对指定表单的主动提交,相比上述的提交事件更加灵活。

事件

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

});

// 指向元素为 `` 的选择事件

form.on('select(test)', function(data){

console.log(data);

});

全局设置

form.set(options);

参数 options : 全局属性选项。详见下表:

属性名

描述

类型

默认值

autocomplete

设置 input 框的 autocomplete 属性初始值

string

-

该方法用于对 form 组件进行全局设置。

form.set({

autocomplete: 'off' // 阻止 input 框默认的自动输入完成功能

});