WUI v1.1.0

基础说明

开始使用 Getting Started
底层方法 基础支撑
页面元素 规范 / 公共类
模块规范 使用 / 扩展
常见问题 FAQ
更新日志

页面元素

布局 容器 / 栅格 / 后台布局
颜色 主题色 / 内置背景色
图标 字体图标
动画 内置 CSS3 动画
按钮 button 组
表单 form 元素集合
导航 菜单 / 面包屑
选项卡 Tabs 切换
进度条 progress
面板 折叠 / 手风琴
表格 静态 table
徽章 小圆点 / 小边框
时间线 timeline
区块 引用 / 字段集
文字 颜色 / 链接 / 位置
辅助 边距 / 填充 / 横线等

内置模块

弹出层 layer
日期与时间选择 wdate
分页 wpage
模板引擎 wtpl
数据表格 table
表单 form
文件上传 upload
穿梭框 transfer
树形组件 tree
颜色选择器 colorpicker
常用元素操作 element
滑块 slider
评分 rate
轮播 carousel
流加载 flow
工具集 util
简单编辑器 wedit
富文本编辑器 tinymce
下拉菜单 menu
拖动排序 dragsort
自动完成 autocomplete
代码修饰器 code
通知控件 notice
下拉多选控件 xmSelect
滑块验证 sliderVerify
无限级联选择器 cascader
表单模块 - wui.form

模块加载名称:form
wui 针对各种表单元素做了较为全面的UI支持,你无需去书写那些 UI 结构,你只需要写 HTML 原始的 input、select、textarea 这些基本的标签即可。我们在 UI 上的渲染只要求一点,你必须给表单体系所在的父元素加上class="wui-form",一切的工作都会在你加载完form模块后,自动完成。如下是一个最基本的例子:
<form class="wui-form"> <!-- 提示:如果你不想用form,你可以换成div等任何一个普通元素 -->
  <div class="wui-form-item">
    <label class="wui-form-label">输入框</label>
    <div class="wui-input-block">
      <input type="text" name="" placeholder="请输入" autocomplete="off" class="wui-input">
    </div>
  </div>
  <div class="wui-form-item">
    <label class="wui-form-label">下拉选择框</label>
    <div class="wui-input-block">
      <select name="interest" w-filter="aihao">
        <option value="0">写作</option>
        <option value="1">阅读</option>
      </select>
    </div>
  </div>
  <div class="wui-form-item">
    <label class="wui-form-label">复选框</label>
    <div class="wui-input-block">
      <input type="checkbox" name="like[write]" title="写作">
      <input type="checkbox" name="like[read]" title="阅读">
    </div>
  </div>
  <div class="wui-form-item">
    <label class="wui-form-label">开关关</label>
    <div class="wui-input-block">
      <input type="checkbox" skin="switch">
    </div>
  </div>
  <div class="wui-form-item">
    <label class="wui-form-label">开关开</label>
    <div class="wui-input-block">
      <input type="checkbox" checked skin="switch">
    </div>
  </div>
  <div class="wui-form-item">
    <label class="wui-form-label">单选框</label>
    <div class="wui-input-block">
      <input type="radio" name="sex" value="0" title="男">
      <input type="radio" name="sex" value="1" title="女" checked>
    </div>
  </div>
  <div class="wui-form-item wui-form-text">
    <label class="wui-form-label">请填写描述</label>
    <div class="wui-input-block">
      <textarea placeholder="请输入内容" class="wui-textarea"></textarea>
    </div>
  </div>
  <div class="wui-form-item">
    <div class="wui-input-block">
      <button class="wui-btn" w-submit w-filter="*">立即提交</button>
      <button type="reset" class="wui-btn wui-btn-primary">重置</button>
    </div>
  </div>
  <!-- 更多表单结构排版请移步文档左侧【页面元素-表单】一项阅览 -->
</form>

<script>
wui.use('form', function(){
  var form = wui.form;

  //各种基于事件的操作,下面会有进一步介绍
});
</script>
正如你上述看到的,你必须放入 wui 所规范的元素结构,form 模块才会对其进行重置渲染。值得注意的是,在具体的每一块表单元素中,你仍是像往日一样写 input 等标签即可。另外,我们对我们所规范的结构进行了响应式的支持,而针对一些不同的表单排版,比如行内表单,你也只需要设定我们所定义好的 class 即可。关于这一块,你可以移步页面元素的表单文档中做详细了解。而事实上你的大部分焦点可能也在那里,但当前这篇文档主要还是介绍 form 整体模块。 有些时候,你的有些表单元素可能是动态插入的。这时 form 模块 的自动化渲染是会对其失效的。虽然我们没有双向绑定机制(因为我们叫经典模块化框架,偷笑.gif) 但没有关系,你只需要执行 form.render(type, filter); 方法即可。

第一个参数:type,为表单的 type 类型,可选。默认对全部类型的表单进行一次更新。可局部刷新的 type 如下表:
参数(type)值 描述
select 刷新select选择框渲染
checkbox 刷新checkbox复选框(含开关)渲染
radio 刷新radio单选框框渲染
form.render(); //更新全部
form.render('select'); //刷新select选择框渲染
//……
第二个参数:filter,为 class="wui-form" 所在元素的 w-filter="" 的值。你可以借助该参数,对表单完成局部更新。
【HTML】
【JavaScript】 form.render(null, 'test1'); //更新 w-filter="test1" 所在容器内的全部表单状态 form.render('select', 'test2'); //更新 w-filter="test2" 所在容器内的全部 select 状态 //……
事实上在使用表单时,你的一半精力可能会在元素本身上。所以我们把一些基础属性的配置恰恰安放在了标签本身上。如:



上述的w-verify、skin、w-filter、w-submit神马的都是我们所说的预设的元素属性,他们可以使得一些交互操作交由form模块内部、或者你来借助form提供的JS接口精确控制。目前我们可支持的属性如下表所示:
属性名 属性值 备注
title 任意字符 设定元素名称,一般用于checkbox、radio框
skin switch(开关风格)
primary(原始风格)
定义元素的风格,目前只对 checkbox 元素有效,可将其转变为开关样式
w-ignore 任意字符或不设值 是否忽略元素美化处理。设置后,将不会对该元素进行初始化渲染,即保留系统风格
w-filter 任意字符 事件过滤器,主要用于事件的精确匹配,跟选择器是比较类似的。其实它并不私属于form模块,它在 wui 的很多基于事件的接口中都会应用到。
w-verify required(必填项)
phone(手机号)
email(邮箱)
url(网址)
number(数字)
date(日期)
identity(身份证)
自定义值
同时支持多条规则的验证,格式:w-verify="验证A|验证B"
如:w-verify="required|phone|number"
另外,除了我们内置的校验规则,你还可以给他设定任意的值,比如 w-verify="pass",那么
你就需要借助 form.verify() 方法对 pass 进行一个校验规则的定义。详见表单验证
w-verType tips(吸附层)
alert(对话框)
msg(默认)
用于定义异常提示层模式。
w-reqText 任意字符 用于自定义必填项(即设定了 w-verify="required" 的表单)的提示文本
w-submit 无需填写值 绑定触发提交的元素,如button
语法:form.on('event(过滤器值)', callback);
form模块在 wui 事件机制中注册了专属事件,所以当你使用wui.onevent()自定义模块事件时,请勿占用form名。form支持的事件如下:
event 描述
select 监听select下拉选择事件
checkbox 监听checkbox复选框勾选事件
switch 监听checkbox复选框开关事件
radio 监听radio单选框事件
submit 监听表单提交事件
默认情况下,事件所监听的是全部的form模块元素,但如果你只想监听某一个元素,使用事件过滤器即可。
如:<select w-filter="test"></select>
form.on('select(test)', function(data){
  console.log(data);
});
下拉选择框被选中时触发,回调函数返回一个object参数,携带两个成员:
form.on('select(filter)', function(data){
  console.log(data.elem); //得到select原始DOM对象
  console.log(data.value); //得到被选中的值
  console.log(data.othis); //得到美化后的DOM对象
});
请注意:如果你想监听所有的select,去掉过滤器(filter)即可。下面将不再对此进行备注。 复选框点击勾选时触发,回调函数返回一个object参数,携带两个成员:
form.on('checkbox(filter)', function(data){
  console.log(data.elem); //得到checkbox原始DOM对象
  console.log(data.elem.checked); //是否被选中,true或者false
  console.log(data.value); //复选框value值,也可以通过data.elem.value得到
  console.log(data.othis); //得到美化后的DOM对象
});
开关被点击时触发,回调函数返回一个 object 参数,携带两个成员:
form.on('switch(filter)', function(data){
  console.log(data.elem); //得到checkbox原始DOM对象
  console.log(data.elem.checked); //开关是否开启,true或者false
  console.log(data.value); //开关value值,也可以通过data.elem.value得到
  console.log(data.othis); //得到美化后的DOM对象
});
radio单选框被点击时触发,回调函数返回一个object参数,携带两个成员:
form.on('radio(filter)', function(data){
  console.log(data.elem); //得到radio原始DOM对象
  console.log(data.value); //被点击的radio的value值
});
按钮点击或者表单被执行提交时触发,其中回调函数只有在验证全部通过后才会进入,回调返回三个成员:
form.on('submit(*)', function(data){
  console.log(data.elem) //被执行事件的元素DOM对象,一般为button对象
  console.log(data.form) //被执行提交的form对象,一般在存在form标签时才会返回
  console.log(data.field) //当前容器的全部表单字段,名值对形式:{name: value}
    return false; //阻止表单跳转。如果需要表单跳转,去掉这段即可。
});
再次温馨提示:上述的submit(*)中的 * 号为事件过滤器的值,是在你绑定执行提交的元素时设定的,如:
<button w-submit w-filter="*">提交</button>
你可以把*号换成任意的值,如:w-filter="go",但监听事件时也要改成 form.on('submit(go)', callback); 语法:form.val('filter', object);
用于给指定表单集合的元素赋值和取值。如果 object 参数存在,则为赋值;如果 object 参数不存在,则为取值。
//给表单赋值
form.val("formTest", { //formTest 即 class="wui-form" 所在元素属性 w-filter="" 对应的值
  "username": "小明" // "name": "value"
  ,"sex": "女"
  ,"auth": 3
  ,"check[write]": true
  ,"open": false
  ,"desc": "我爱wui"
});

//获取表单区域所有值
var data1 = form.val("formTest");
第二个参数中的键值是表单元素对应的 name 和 value。 我们对表单的验证进行了非常巧妙的支持,大多数时候你只需要在表单元素上加上 w-verify="" 属性值即可。如:
<input type="text" w-verify="email">

还同时支持多条规则的验证,如下:
<input type="text" w-verify="required|phone|number">
上述对输入框定义了一个邮箱规则的校验,它会在 form 模块内部完成。目前我们内置的校验支持见上文的:预设元素属性
除了内置的校验规则外,你还可以自定义验证规则,通常对于比较复杂的校验,这是非常有必要的。
form.verify({
  username: function(value, item){ //value:表单的值、item:表单的DOM对象
    if(!new RegExp("^[a-zA-Z0-9_\u4e00-\u9fa5\\s·]+$").test(value)){
      return '用户名不能有特殊字符';
    }
    if(/(^\_)|(\__)|(\_+$)/.test(value)){
      return '用户名首尾不能出现下划线\'_\'';
    }
    if(/^\d+\d+\d$/.test(value)){
      return '用户名不能全为数字';
    }
  }

  //我们既支持上述函数式的方式,也支持下述数组的形式
  //数组的两个值分别代表:[正则匹配、匹配不符时的提示文字]
  ,pass: [
    /^[\S]{6,12}$/
    ,'密码必须6到12位,且不能出现空格'
  ]
});
当你自定义了类似上面的验证规则后,你只需要把 key 赋值给输入框的 w-verify 属性即可:
<input type="text" w-verify="username" placeholder="请输入用户名">
<input type="password" w-verify="pass" placeholder="请输入密码">
© 2021 Wangren.Net  Layui  tinyMCE  SUI Mobile