正心全栈编程-文档站

Appearance

表单组件 ​

http://layui.dev/docs/2.8/form

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

表单布局 ​

form 组件自身的普通布局。其要点为：

  • 通过 class="layui-form" 定义一个表单域，通常设置在 <form> 标签上， 或普通 <div> 标签亦可。
  • 通过 class="layui-form-item" 定义一个块级元素的表单项容器
  • 通过 class="layui-form-label" 定义标签
  • 通过 class="layui-form-block" 定义表单项父容器为块级元素
  • 通过 class="layui-form-inline" 或 class="layui-inline" 定义表单项父容器为行内块元素

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

官网注册页面案例

html
<body>
  <style>
    .demo-reg-container {
      width: 320px;
      margin: 21px auto 0;
    }

    .demo-reg-other .layui-icon {
      position: relative;
      display: inline-block;
      margin: 0 2px;
      top: 2px;
      font-size: 26px;
    }
  </style>
  <form class="layui-form">
    <div class="demo-reg-container">
      <div class="layui-form-item">
        <div class="layui-row">
          <div class="layui-col-xs7">
            <div class="layui-input-wrap">
              <div class="layui-input-prefix">
                <i class="layui-icon layui-icon-cellphone"></i>
              </div>
              <input
                type="text"
                name="cellphone"
                value=""
                lay-verify="required|phone"
                placeholder="手机号"
                lay-reqtext="请填写手机号"
                autocomplete="off"
                class="layui-input"
                id="reg-cellphone"
              />
            </div>
          </div>
          <div class="layui-col-xs5">
            <div style="margin-left: 11px;">
              <button
                type="button"
                class="layui-btn layui-btn-fluid layui-btn-primary"
                lay-on="reg-get-vercode"
              >
                获取验证码
              </button>
            </div>
          </div>
        </div>
      </div>
      <div class="layui-form-item">
        <div class="layui-input-wrap">
          <div class="layui-input-prefix">
            <i class="layui-icon layui-icon-vercode"></i>
          </div>
          <input
            type="text"
            name="vercode"
            value=""
            lay-verify="required"
            placeholder="验证码"
            lay-reqtext="请填写验证码"
            autocomplete="off"
            class="layui-input"
          />
        </div>
      </div>
      <div class="layui-form-item">
        <div class="layui-input-wrap">
          <div class="layui-input-prefix">
            <i class="layui-icon layui-icon-password"></i>
          </div>
          <input
            type="password"
            name="password"
            value=""
            lay-verify="required"
            placeholder="密码"
            autocomplete="off"
            class="layui-input"
            id="reg-password"
            lay-affix="eye"
          />
        </div>
      </div>
      <div class="layui-form-item">
        <div class="layui-input-wrap">
          <div class="layui-input-prefix">
            <i class="layui-icon layui-icon-password"></i>
          </div>
          <input
            type="password"
            name="confirmPassword"
            value=""
            lay-verify="required|confirmPassword"
            placeholder="确认密码"
            autocomplete="off"
            class="layui-input"
            lay-affix="eye"
          />
        </div>
      </div>
      <div class="layui-form-item">
        <div class="layui-input-wrap">
          <div class="layui-input-prefix">
            <i class="layui-icon layui-icon-username"></i>
          </div>
          <input
            type="text"
            name="nickname"
            value=""
            lay-verify="required"
            placeholder="昵称"
            autocomplete="off"
            class="layui-input"
            lay-affix="clear"
          />
        </div>
      </div>
      <div class="layui-form-item">
        <input
          type="checkbox"
          name="agreement"
          lay-verify="required"
          lay-skin="primary"
          title="同意"
        />
        <a
          href="#terms"
          target="_blank"
          style="position: relative; top: 6px; left: -15px;"
        >
          <ins>用户协议</ins>
        </a>
      </div>
      <div class="layui-form-item">
        <button
          class="layui-btn layui-btn-fluid"
          lay-submit
          lay-filter="demo-reg"
        >
          注册
        </button>
      </div>
      <div class="layui-form-item demo-reg-other">
        <label>社交账号注册</label>
        <span style="padding: 0 21px 0 6px;">
          <a href="javascript:;"
            ><i
              class="layui-icon layui-icon-login-qq"
              style="color: #3492ed;"
            ></i
          ></a>
          <a href="javascript:;"
            ><i
              class="layui-icon layui-icon-login-wechat"
              style="color: #4daf29;"
            ></i
          ></a>
          <a href="javascript:;"
            ><i
              class="layui-icon layui-icon-login-weibo"
              style="color: #cf1900;"
            ></i
          ></a>
        </span>
        <a href="#login">登录已有帐号</a>
      </div>
    </div>
  </form>
  <script src="/static/layui.js"></script>
  <script>
    layui.use(function () {
      var $ = layui.$;
      var form = layui.form;
      var layer = layui.layer;
    });
  </script>
</body>

属性 ​

http://layui.dev/docs/2.8/form/#attr

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

html
<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-verifyrequired必填项
phone手机号
email邮箱
url网址
number数字
date日期
identity身份证
自定义规则值		设置表单项的验证规则，支持单条或多条规则（多条用 竖线 分隔），如： lay-verify="required"
lay-verify="required 竖线 email"
lay-verify="其他自定义规则值"
自定义规则的用法：#详见
lay-vertypetips吸附层 alert 对话框 msg 默认设置验证异常时的提示层模式
lay-reqtext自定义设置必填项（lay-verify="required"）的默认提示文本
lay-affix#详见输入框动态点缀，<input type="text">元素 私有属性
lay-skin#详见设置 UI 风格。 <input type="checkbox"> 元素 私有属性
lay-search默认不区分大小写; 设置cs区分大小写给 select 组件开启搜索功能。<select> 元素 私有属性
lay-submit无需值设置元素（一般为<button> 标签）触发 submit 提交事件
lay-ignore无需值设置表单元素忽略渲染，即让元素保留系统原始 UI 风格

渲染 ​

form.render(type, filter);
  • 参数 type 可选，对应表单组件类型，支持：input,select,checkbox,radio；若不填，则指向所有类型。
  • 参数 filter 可选，对应 class="layui-form" 所在元素的 lay-filter 属性值，用于指定需渲染的表单区域。

常规渲染 ​

form 组件会在元素加载完毕后，自动对所有表单区域完成一次渲染，因此该方法主要用于对动态插入的表单元素的渲染。

html
<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 对象，从而完成定向渲染。且支持两种方式的指向：

  • 若 jQuery 对象指向表单域容器（class="layui-form"），则渲染该表单域中的所有表单项；
  • 若 jQuery 对象指向的不是表单域容器，则只对该对象进行渲染

定向渲染在页面出现大量表单时，可以极大地减少表单组件渲染时的性能开销，建议灵活运用。

html
<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 风格。

html
<body>
  <div class="layui-form">
    <select>
      <option value="a">正常渲染的 select</option>
    </select>
    <input type="checkbox" lay-skin="primary" title="正常渲染的 checkbox" />
    <hr />
    <select lay-ignore>
      <option value="">忽略渲染的 select</option>
    </select>
    <input type="checkbox" lay-ignore /> 忽略渲染的 checkbox
  </div>
</body>

验证 ​

Layui 对表单做了相对巧妙的支持，只需在表单元素上设置 lay-verify="" 属性值即可指定验证规则，如：

html
<div class="layui-form">
  <input type="text" lay-verify="required" />
  <input type="text" lay-verify="email" />
  <input type="text" lay-verify="required|phone|number" />
  <button class="layui-btn" lay-submit>提交</button>
</div>

其中，lay-verify 属性的内置规则值可参考上文的。 当表单提交时，会自动触发验证。

自定义验证规则 ​

form.verify(obj);
  • 参数 obj 是一个对象，用于定义验证规则的集合。

当内置的验证规则无法满足业务需求时，我们可以通过该方法自定义验证规则。如：

html
<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 />
    <button class="layui-btn" lay-submit lay-filter="demo-verify">提交</button>
  </form>

  <script src="/static/layui.js"></script>
  <script>
    layui.use(function () {
      var form = layui.form;
      // 自定义验证规则，如下以验证用户名和密码为例
      form.verify({
        // 函数写法
        // 参数 value 为表单的值；参数 item 为表单的 DOM 对象
        username: function (value, item) {
          if (!new RegExp("^[a-zA-Z0-9_\u4e00-\u9fa5\\s·]+$").test(value)) {
            return "用户名不能有特殊字符";
          }
          if (/(^_)|(__)|(_+$)/.test(value))
            return "用户名首尾不能出现 _ 下划线";
          if (/^\d+$/.test(value)) return "用户名不能全为数字";

          // 若不想自动弹出默认提示框，可返回 true，这时你可以通过其他提示方式替代（v2.5.7 新增）
          if (value === "xxx") {
            alert("用户名不能为敏感词");
            return true;
          }
        },
        // 数组写法。
        // 数组中两个成员值分别代表：[正则表达式、正则匹配不符时的提示文字]
        password: [/^[\S]{6,12}$/, "密码必须为6到12位的非空字符"],
      });
      // 提交事件
      form.on("submit(demo-verify)", function (data) {
        var field = data.field; // 获取表单字段值
        // 显示填写结果，仅作演示用
        layer.alert(JSON.stringify(field), {
          title: "当前填写的字段值",
        });
        // 此处可执行 Ajax 等操作
        // …
        return false; // 阻止默认 form 跳转
      });
    });
  </script>
</body>

主动触发验证 ​

form.validate(elem);
  • 参数 elem 为元素选择器或 jQuery 对象； 若验证通过，该方法将返回 true，否则返回 false
html
<body>
  <div class="layui-form">
    <div class="layui-form-item">
      <label class="layui-form-label">手机</label>
      <div class="layui-input-block">
        <input
          type="tel"
          name="phone"
          lay-verify="required|phone"
          class="layui-input"
          id="validate-phone"
        />
      </div>
    </div>
    <div class="layui-form-item">
      <label class="layui-form-label">验证码</label>
      <div class="layui-input-inline">
        <input
          type="text"
          name="vercode"
          lay-verify="required"
          class="layui-input"
        />
      </div>
      <div class="layui-inline">
        <button
          type="button"
          class="layui-btn layui-btn-primary"
          id="validate-get-vercode"
        >
          获取验证码
        </button>
      </div>
    </div>
    <div class="layui-form-item">
      <div class="layui-input-block">
        <button class="layui-btn" lay-submit lay-filter="demo-validate">
          提交
        </button>
      </div>
    </div>
  </div>

  <script src="/static/layui.js"></script>
  <script>
    layui.use(function () {
      var $ = layui.$;
      var form = layui.form;
      var layer = layui.layer;

      // 点击获取验证码
      $("#validate-get-vercode").on("click", function () {
        var isValid = form.validate("#validate-phone"); // 主动触发验证，v2.7.0 新增
        // 验证通过
        if (isValid) {
          layer.msg("手机号规则验证通过");
          // 此处可继续书写「发送验证码」等后续逻辑
          // …
        }
      });
      // 提交事件
      form.on("submit(demo-validate)", function (data) {
        var field = data.field; // 获取表单字段值
        // 显示填写结果，仅作演示用
        layer.alert(JSON.stringify(field), {
          title: "当前填写的字段值",
        });
        // 此处可执行 Ajax 等操作
        // …
        return false; // 阻止默认 form 跳转
      });
    });
  </script>
</body>

赋值/取值 ​

form.val(filter, obj);
  • 参数 filter 为表单域容器（class="layui-form"）的 lay-filter 属性值
  • 参数 obj 可选。若参数存在，则对表单域进行赋值；若参数不存在，则为对表单域进行取值。
html
<body>
  <form class="layui-form" action="" lay-filter="demo-val-filter">
    <div
      class="layui-btn-container"
      style="margin-bottom: 6px; text-align: center;"
    >
      <button
        type="button"
        class="layui-btn layui-btn-normal"
        id="LAY-component-form-setval"
      >
        赋值
      </button>
      <button
        type="button"
        class="layui-btn layui-btn-normal"
        id="LAY-component-form-getval"
      >
        取值
      </button>
    </div>
    <div class="layui-form-item">
      <label class="layui-form-label">输入框</label>
      <div class="layui-input-block">
        <input
          type="text"
          name="username"
          lay-verify="title"
          autocomplete="off"
          placeholder="请输入"
          class="layui-input"
        />
      </div>
    </div>
    <div class="layui-form-item">
      <label class="layui-form-label">密码框</label>
      <div class="layui-input-block">
        <input
          type="password"
          name="password"
          placeholder="请输入"
          autocomplete="off"
          class="layui-input"
        />
      </div>
    </div>
    <div class="layui-form-item">
      <label class="layui-form-label">选择框</label>
      <div class="layui-input-block">
        <select name="interest" lay-filter="aihao">
          <option value=""></option>
          <option value="0">写作</option>
          <option value="1">阅读</option>
          <option value="2">游戏</option>
          <option value="3">音乐</option>
          <option value="4">旅行</option>
        </select>
      </div>
    </div>
    <div class="layui-form-item">
      <label class="layui-form-label">复选框</label>
      <div class="layui-input-block">
        <input type="checkbox" name="like[write]" title="写作" />
        <input type="checkbox" name="like[read]" title="阅读" />
        <input type="checkbox" name="like[daze]" title="发呆" />
      </div>
    </div>
    <div class="layui-form-item">
      <label class="layui-form-label">开关</label>
      <div class="layui-input-block">
        <input
          type="checkbox"
          name="close"
          lay-skin="switch"
          lay-text="ON|OFF"
        />
      </div>
    </div>
    <div class="layui-form-item">
      <label class="layui-form-label">单选框</label>
      <div class="layui-input-block">
        <input type="radio" name="sex" value="男" title="男" checked />
        <input type="radio" name="sex" value="女" title="女" />
      </div>
    </div>
    <div class="layui-form-item layui-form-text">
      <label class="layui-form-label">文本域</label>
      <div class="layui-input-block">
        <textarea
          placeholder="请输入"
          class="layui-textarea"
          name="desc"
        ></textarea>
      </div>
    </div>
    <div class="layui-form-item">
      <div class="layui-input-block">
        <button
          type="submit"
          class="layui-btn"
          lay-submit
          lay-filter="demo-val"
        >
          立即提交
        </button>
        <button type="reset" class="layui-btn layui-btn-primary">重置</button>
      </div>
    </div>
  </form>

  <script src="/static/layui.js"></script>
  <script>
    layui.use(function () {
      var $ = layui.$;
      var form = layui.form;
      // 表单赋值
      $("#LAY-component-form-setval").on("click", function () {
        form.val("demo-val-filter", {
          username: "贤心", // "name": "value"
          password: "AAAAAA",
          interest: 1,
          "like[write]": true, // 复选框选中状态
          close: true, // 开关状态
          sex: "女",
          desc: "Layui 用于更简单快速地构建网页界面",
        });
      });
      // 表单取值
      layui.$("#LAY-component-form-getval").on("click", function () {
        var data = form.val("demo-val-filter");
        alert(JSON.stringify(data));
      });
      // 提交事件
      form.on("submit(demo-val)", function (data) {
        var field = data.field; // 获取表单字段值
        // 显示填写结果，仅作演示用
        layer.alert(JSON.stringify(field), {
          title: "当前填写的字段值",
        });
        // 此处可执行 Ajax 等操作
        // …
        return false; // 阻止默认 form 跳转
      });
    });
  </script>
</body>

提交 ​

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

提交事件 ​

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

html
<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="/static/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>

提交方法 ​

form.submit(filter, callback);
  • 参数 filter 为表单域容器的 lay-filter 属性值
  • 参数 callback 为执行提交事件后的回调函数

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

html
<body>
  <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>

  <!-- 请勿在项目正式环境中引用该 layui.js 地址 -->
  <script src="/static/layui.js"></script>
  <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>
</body>

事件 ​

form.on('event(filter)', callback);
  • 参数 event(filter) 是一个特定结构。event 为事件名，支持：select,checkbox,switch,radio,submit；filter 为元素属性 lay-filter 对应的值，若不填，则指向所有同类组件的事件。
  • 参数 callback 为事件执行时的回调函数，并返回一个包含各种值的 object 类型的参数。

如下以 select 事件为例：

js
// 指向所有 select 组件的选择事件
form.on("select", function (data) {
  console.log(data);
});

// 指向元素为 `<select lay-filter="test"></select>` 的选择事件
form.on("select(test)", function (data) {
  console.log(data);
});