docs/form/index.md
<h2 id="examples" lay-toc="{anchor: null}" style="margin-bottom: 0;">示例</h2> <h3 lay-toc="{level: 2, id: 'examples', hot: true}" class="layui-hide">综合演示</h3> <pre class="layui-code" lay-options="{preview: true, text: {preview: '综合演示'}, codeStyle: 'height: 508px;', layout: ['preview', 'code'], tools: ['full'], done: function(obj){ obj.render() }}"> <textarea> {{- d.include("/form/examples/form.demo.md") }} </textarea> </pre> <h3 id="pane" lay-toc="{level: 2}">方框风格</h3> <pre class="layui-code" lay-options="{preview: true, layout: ['preview', 'code'], codeStyle: 'height: 508px;', tools: ['full'], done: function(obj){ obj.render() }}"> <textarea> {{- d.include("/form/examples/form.pane.md") }} </textarea> </pre> <h3 id="login" lay-toc="{level: 2}">登录模板 <sup>2.8+</sup></h3> <pre class="layui-code" lay-options="{preview: true, layout: ['preview', 'code'], codeStyle: 'height: 508px;', tools: ['full'], done: function(obj){ obj.render() }}"> <textarea> {{- d.include("/form/examples/form.login.md") }} </textarea> </pre> <h3 id="reg" lay-toc="{level: 2}">注册模板 <sup>2.8+</sup></h3> <pre class="layui-code" lay-options="{preview: true, layout: ['preview', 'code'], codeStyle: 'height: 508px;', tools: ['full'], done: function(obj){ obj.render() }}"> <textarea> {{- d.include("/form/examples/form.reg.md") }} </textarea> </pre>表单组件
form是包含输入框、选择框、复选框、开关、单选框等表单项组件的集合，主要用于对表单域进行各类动态化渲染和相关的交互操作。form是 Layui 最常用的组件之一。
更多其他表单模板均可自由布局实现，为了避免影响文档其他重要版面的阅读，我们就不做过多演示了。
<h2 id="layout" lay-toc="{title: '布局'}">表单布局</h2>在上文的「综合演示」示例中，我们用的是 form 组件自身的普通布局。其要点为：
class="layui-form" 定义一个表单域，通常设置在<form>标签上， 或普通<div> 标签亦可。class="layui-form-item" 定义一个块级元素的表单项容器class="layui-form-label" 定义标签class="layui-input-block" 定义表单项父容器为块级元素class="layui-input-inline" 或 class="layui-inline" 定义表单项父容器为行内块元素即必须按照规定的层级定义相应的 class。
form 还可以借助栅格实现更灵活的响应式布局。
<pre class="layui-code" lay-options="{preview: true, layout: ['preview', 'code'], codeStyle: 'height: 500px;', done: function(obj){ obj.render() }}"> <textarea> {{- d.include("/form/examples/form.grid.md") }} </textarea> </pre> <h2 id="api" lay-toc="{hot: 1}">API</h2>| API | 描述 |
|---|---|
| var form = layui.form | 获得 form 模块。 |
| form.render(type, filter) | 表单域组件渲染，核心方法。#用法 |
| form.verify(obj) | 自定义表单验证的规则。#用法 |
| form.validate(elem) <sup>2.7+</sup> | 主动触发执行验证。#用法 |
| form.val(filter, obj) | 表单赋值或取值。 #用法 |
| form.submit(filter, callback) <sup>2.7+</sup> | 用于主动执行指定表单的提交。#用法 |
| form.on('event(filter)', callback) | 事件。#用法 |
| form.set(options) | 设置 form 组件全局配置项。 |
| form.config | 获取 form 组件全局配置项。 |
在表单域中，有时还需要定义一些特定属性来配合组件的使用，它们一般以 lay-* 为命名格式，如：
<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>
以下为 form 组件的特定属性列表：
| 属性 | 值 | 描述 |
|---|---|---|
| title | 自定义 | 设置表单元素标题，一般用于 checkbox,radio 元素 |
| lay-filter | 自定义 | 设置表单元素的过滤器，以便用于执行相关方法时的参数匹配 |
| lay-verify | required必填项 | |
phone手机号 | ||
email邮箱 | ||
url网址 | ||
number数字 | ||
date日期 | ||
identity身份证<hr>自定义规则值 | 设置表单项的验证规则，支持单条或多条规则（多条用|分隔），如： | |
lay-verify="required" | ||
lay-verify="required|email" | ||
lay-verify="其他自定义规则值" <hr>自定义规则的用法：#详见<hr>注：<sup>2.8.3</sup> 版本中调整了内置规则，不再强制必填。 | ||
如需保留必填，可叠加 required 规则，如： | ||
lay-verify="required|number" | ||
| lay-vertype | tips吸附层 | |
alert 对话框 | ||
msg 默认 | 设置验证异常时的提示层模式 | |
| lay-reqtext | 自定义 | 设置必填项（lay-verify="required"）的默认提示文本 |
| lay-affix | #详见 | 输入框动态点缀，<input type="text">元素 私有属性 |
| lay-skin | #详见 | 设置 UI 风格。 <input type="checkbox">，<input type="radio"> 元素 私有属性 |
| lay-search | <sup>2.9.15+</sup> lay-search="{caseSensitive:false, fuzzy: false}" | |
caseSensitive 是否区分大小写，默认值为 false | ||
fuzzy是否开启模糊匹配，开启后将会忽略匹配字符出现在字符串中的位置，默认值为 false | ||
设置cs区分大小写(2.9.15+ 已弃用) | 给 select 组件开启搜索功能。<select> 元素 私有属性 | |
| lay-creatable <sup>2.9.7+</sup> | 无需值 | 是否允许创建新条目，需要配合 lay-search 使用。<select> 元素 私有属性 |
| lay-append-to <sup>2.9.12+</sup> <sup>实验性</sup> | body | 是否将 select 面板追加到 body 元素中。<select> 元素 私有属性 |
| lay-append-position <sup>2.9.12+</sup> <sup>实验性</sup> | absolute 绝对定位 (默认) | |
fixed 固定定位 | 用于设置 select 面板开启 lay-append-to 属性后的定位方式。<select> 元素 私有属性 | |
| lay-submit | 无需值 | 设置元素（一般为<button> 标签）触发 submit 提交事件 |
| lay-ignore | 无需值 | 设置表单元素忽略渲染，即让元素保留系统原始 UI 风格。注 <sup>2.10.2+</sup>：该属性若设置在 <div> 等父元素上，则该父元素下的所有表单均可被忽略渲染。 |
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>
该方法还允许指定表单元素的 jQuery 对象，从而完成定向渲染。且支持两种方式的指向：
class="layui-form"），则渲染该表单域中的所有表单项；<sup>2.8+</sup>定向渲染在页面出现大量表单时，可以极大地减少表单组件渲染时的性能开销，建议灵活运用。
<div class="layui-form" id="form-id">
<select id="select-id">
<option value="a">A</option>
</select>
<!-- 其他表单元素 -->
</div>
<!-- import layui -->
<script>
layui.use('form', function(){
var $ = layui.$;
var form = layui.form;
// 定向渲染（一般当表单存在动态生成时，进行渲染）
// 传入需要渲染的相应表单元素的 jQuery 对象
form.render($('#form-id')); // 渲染 id="form-id" 的表单域中的所有表单项
form.render($('#select-id')); // 仅渲染 id="select-id" 的表单项
});
</script>
若表单域中的部分表单不需要 Layui 来渲染，那么可通过 lay-ignore 属性让其保留系统原始 UI 风格。
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>
注：上述代码指定的均为内置的验证规则，具体可参考：#属性介绍
<h3 id="verify" lay-toc="{level: 3, title: '定义验证规则'}" class="ws-bold">自定义验证规则</h3>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 默认的提示风格
}
}
});
以下是一个自定义验证规则的示例：
<pre class="layui-code" lay-options="{preview: true, codeStyle: 'height: 508px;', done: function(obj){ obj.render() }}"> <textarea> {{- d.include("/form/examples/form.verify.md") }} </textarea> </pre>更多「自定义验证规则」示例参考：
<h3 id="validate" lay-toc="{level: 3}" class="ws-bold">主动触发验证 <sup>2.7+</sup></h3>
- <a href="https://gitee.com/layui/layui/issues/I5HC2L#note_11673264_link" target="_blank">将 form 提示语显示在表单项旁边，并在提交时批量触发验证</a>
form.validate(elem);
elem 为元素选择器或 jQuery 对象； 若验证通过，该方法将返回 true，否则返回 falseform.val(filter, obj);
filter 为表单域容器（class="layui-form"）的 lay-filter 属性值obj 可选。若参数存在，则对表单域进行赋值；若参数不存在，则为对表单域进行取值。表单的提交可以通过事件触发或方法触发
在表单域中，对指定按钮设置 lay-submit 属性，即意味着点击该按钮时，将触发提交事件。如：
form.submit(filter, callback);
filter 为表单域容器的 lay-filter 属性值callback 为执行提交事件后的回调函数使用该方法可以实现在任意位置对指定表单的主动提交，相比上述的提交事件更加灵活。
<pre class="layui-code" lay-options="{preview: true, codeStyle: 'height: 508px;', done: function(obj){ obj.render() }}"> <textarea> <fieldset class="layui-elem-field"> <legend>表单内部</legend> <div class="layui-field-box"> <form class="layui-form" lay-filter="form-demo-submit"> <input type="text" name="nickname" lay-verify="required" class="layui-input"> </form> </div> </fieldset> <button class="layui-btn" id="test-btn-submit">任意位置按钮</button> <!-- import layui --> <script> layui.use(function(){ var $ = layui.$; var form = layui.form; var layer = layui.layer; // 任意位置按钮触发提交 $('#test-btn-submit').on('click', function(){ form.submit('form-demo-submit', function(data){ var field = data.field; // 获取表单全部字段值 console.log(data); // 回调函数返回的 data 参数和提交事件中返回的一致 // 执行提交 layer.confirm('确定提交吗？', function(index){ layer.close(index); // 关闭确认提示框 // 显示填写结果，仅作演示用 layer.alert(JSON.stringify(field), { title: '当前填写的字段值' }); // 此处可执行 Ajax 等操作 // … }); }); return false; }); }); </script> </textarea> </pre> <h2 id="on" lay-toc="{}">事件</h2>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);
});
form.set(options);
options : 全局属性选项。详见下表：| 属性名 | 描述 | 类型 | 默认值 |
|---|---|---|---|
| autocomplete | 设置 input 框的 autocomplete 属性初始值 | string | - |
该方法用于对 form 组件进行全局设置。
form.set({
autocomplete: 'off' // 阻止 input 框默认的自动输入完成功能
});