Form 表单

Form 表单

由输入框、文本框、单选框、多选框、评分控件组成，用以收集、校验、提交数据。适用于账号注册、用户信息填写等表单页面。

基础案例

用户信息表单。

<l-form name="student" l-form-btn-class="l-form-btn-class" bind:linsubmit="submit">
    <l-form-item label="姓名:" name="studentName">
        <l-input id="studentName" value="{{student.name}}" hide-label show-row="{{false}}"/>
    </l-form-item>
    <l-form-item label="年龄:" name="studentAge">
        <l-input id="studentAge" value="{{student.age}}" hide-label show-row="{{false}}"/>
    </l-form-item>
    <l-form-item label="地址:" name="studentAddress">
        <l-input id="studentAddress" value="{{student.address}}" hide-label show-row="{{false}}"/>
    </l-form-item>
    <view slot="submit">
        <l-button>提交</l-button>
    </view>
    <view slot="reset">
        <l-button type="default" plain>重置</l-button>
    </view>
</l-form>

.l-form-btn-class{
    display: flex;
    justify-content: space-around;
    margin-top: 10rpx;
}

Page({
  data: {
    student: {
      name: '',
      age: '',
      address: ''
    },
  },
  submit(event){
    const {detail} = event;
    /*
      detail 返回三个参数
      1、values: 各表单项的value值
      2、errors: 各表单项验证后的返回的错误信息数组
      3、isValidate: 表单是否验证通过的boolean值
      具体格式示例：
      detail = {
         values: {
             studentName: "",
             studentAge: "",
             studentAddress: ""
         },
         errors: {
             studentName: [],
             studentAge: [],
             studentAddress: []
         },
         isValidate: true
      }
    */
  },
  onLoad: function () {
    wx.lin.initValidateForm(this)
  },
})

在 form 组件中，每一个表单域由一个 form-Item 组件构成，表单域中可以放置各种类型的表单控件，包括 Input、Checkbox、Radio、Rate、TextArea 。 form-Item 中只能使用 Lin-UI 的表单元素，不能使用其他UI组件或者小程序的原生组件。

表单使用需要有以下注意：

使用 form 组件时需要在 onLoad 中调用 wx.lin.initValidateForm(this)进行初始化。
需要给 form 组件设置 name 属性。当用户手动提交表单的时候需要传入表单 name。例： <l-form name="student"></l-form>。
需要给 form-Item 设置 name 属性。name 的值将作为提交表单时返回的 Key 。例： <l-form-item name="studentName"></l-form-item>。
每一个表单控件必须设置一个 id 属性，且属性值必需与 form-Item 的 name 属性值相同。id属性用于通过selectComponent获取表单域的值。例：<l-form-item name="studentName"><l-input id="studentName"/></l-form-item>

使用更多表单项

示例代码

<l-form name="form" bind:linsubmit="submit" l-form-btn-class="l-form-btn-class">
    <l-form-item label="填写姓名:" name="name">
        <l-input id="name" value="{{name}}" hide-label show-row="{{false}}"/>
    </l-form-item>
    <l-form-item label="选择歌曲:" name="music" >
        <l-checkbox-group bind:linchange="change" id="music" placement="row">
            <l-checkbox
                l-class="l-checkbox-color"
                wx:for="{{items}}"
                wx:key="{{item.id}}"
                placement="{{position}}"
                key="{{item.name}}"
                checked="{{item.checked}}"
            >
                {{item.name}}
            </l-checkbox>
        </l-checkbox-group>
    </l-form-item>
    <l-form-item label="选择性别:" name="sex">
        <l-radio-group current="{{sex}}" id="sex" placement="row">
            <l-radio key="0">
                男
            </l-radio>
            <l-radio key="1">
                女
            </l-radio>
        </l-radio-group>
    </l-form-item>
    <l-form-item label="自我评分:" name="score">
        <l-rate id="score" value="{{score}}" />
    </l-form-item>
    <l-form-item label="性格描述:" name="desc">
        <l-textarea border="{{false}}" id="desc" value="{{desc}}" />
    </l-form-item>
    <view slot="submit">
        <l-button>提交验证</l-button>
    </view>
    <view slot="reset">
        <l-button type="default" plain>重置</l-button>
    </view>
</l-form>

  data: { 
    name: '王大锤', 
    sex: '', 
    music: '',
    score: '',
    desc: '',
    items: [
      {
        id: 1,
        name: '青瓷',
        checked: false
      },
      {
       id: 2,
       name: '双棍',
       checked: false
      },
      {
        id: 3,
        name: '明天',
        checked: false
    }]
  },
  onLoad: function () {
   wx.lin.initValidateForm(this)
  },
  change(e) {
    let items = this.data.items;
    items.forEach(item => {
      if(item.name == e.detail.key) {
        item.checked = e.detail.checked;
      }
    });
    this.setData({
      items: items
    });
  }

更改表单域的布局方式

通过设置 label-placement 切换表单项的布局方式。默认值是 row ，即label与内容项同行显示。值为 column 时，label显示在内容项上方。

示例代码

<l-form-item label="填写姓名:" name="name" label-placement="column">
    <l-input id="name" value="{{name}}" hide-label show-row="{{false}}"/>
</l-form-item>

设置表单域标签的文字对齐方式

通过设置 align-items 更改表单域标签内容文字的对齐方式。默认值是 start ，可选项为 start/center/end。

示例代码

<l-form-item label="填写姓名:" name="name" align-items="start">
    <l-input id="name" value="{{name}}" hide-label show-row="{{false}}"/>
</l-form-item>

设置表单域标签的宽度

通过设置 label-width 属性来修改表单域标签的宽度。

示例代码

<l-form-item label="填写姓名:" name="name" label-width="300rpx">
    <l-input id="name" value="{{name}}" hide-label show-row="{{false}}"/>
</l-form-item>

自定义表单域标签的内容

通过设置 label-slot 为 true，使用具名插槽 label 自定义表单域标签的内容。

示例代码

<l-form-item label="填写姓名:" name="name" label-slot>
    <view slot="label">插槽姓名:</view>
    <l-input id="name" value="{{name}}" hide-label show-row="{{false}}"/>
</l-form-item>

带验证的表单案例

通过在 form-Item 上设置 rules 属性，给表单项添加验证规则。rules 接收一个验证对象或者由多个验证对象组成的数组。 form组件使用了开源库 async-validator 来实现表单验证。可以快速使用 async-validator 内置的常用验证，也可以自定义验证函数。

验证时机： form组件可以实时验证，也可以在用户提交时统一‍验证。通过 trigger 设置表单项验证的时机，可选值 blur/change。trigger 默认为空，此时表单不会实时验证，可在提交时统一校验。trigger 可以传入一个数组或字符串，例： trigger:blur、trigger:['blur','change']

提示方式：验证器提供了三种提示错误的方式：message 、 toast 和 text ，通过设置 form-Item 的 tip-type 值为 message 或 toast 或 text 修改提示方式。默认值为 toast。 注意： 使用 message 和 toast 的方式需要在配置文件中引用组件。

基础校验

使用内置常用验证函数，例如：长度验证、必填验证、邮箱验证、自定义正则验证等。

<l-form name="loginForm" bind:linsubmit="submit" l-form-btn-class="l-form-btn-class">
    <l-form-item label="账号:" name="loginFormLoginId" rules="{{loginForm.loginIdRules}}">
        <l-input id="loginFormLoginId" value="{{loginForm.loginId}}" hide-label show-row="{{false}}"/>
    </l-form-item>
    <l-form-item label="密码:" name="loginFormPassword" rules="{{loginForm.passwordRules}}">
        <l-input id="loginFormPassword" value="{{loginForm.password}}" hide-label show-row="{{false}}"/>
    </l-form-item>
    <view slot="submit">
        <l-button>注册</l-button>
    </view>
    <view slot="reset">
        <l-button type="default" plain>重置</l-button>
    </view>
</l-form>

Page({
  data: {
    loginForm: {
      loginId: '',
      password: '',
      loginIdRules:{
        type: 'email',
        required: true,
        message: '邮箱地址不合法',
        trigger: 'change'
      },
      passwordRules: [
        { required: true, message: '请输入登录密码', trigger: 'blur' },
        { min: 8, max: 20, message: '密码长度在8-20个字符之间', trigger: 'blur' },
        { pattern: '^[A-Za-z0-9]+$', message: '密码必须由数字字母组成',trigger: 'blur'}
      ],
    }
  }
})

自定义校验

通过设置 validator 函数自定义验证规则，validator 接收四个参数。rule 表示当前的验证规则，value 表示当前验证的值，callback 为回调函数，source 为整个表单的数据。若验证不通过调用callback(false),若验证通过调用callback()。


<l-form name="register" l-form-btn-class="l-form-btn-class">
    <l-form-item tip-type="text" label="登录账号:" name="loginId" rules="{{loginIdRules}}">
        <l-input id="loginId" value="{{register.loginId}}" hide-label show-row="{{false}}"/>
    </l-form-item>
    <l-form-item tip-type="text" label="登录密码:" name="password" rules="{{passwordRules}}">
        <l-input id="password" value="{{register.password}}" hide-label show-row="{{false}}"/>
    </l-form-item>
    <l-form-item tip-type="text" label="确认密码:" name="confirm" rules="{{confirmRules}}">
        <l-input id="confirm" value="{{register.confirm}}" hide-label show-row="{{false}}"/>
    </l-form-item>
    <view slot="submit">
        <l-button>注册</l-button>
    </view>
    <view slot="reset">
        <l-button type="default" plain>重置</l-button>
    </view>
</l-form>


data: {
  register: {
    loginId: '',
    password: '',
    confirm: ''
  },
  loginIdRules: {
    type: 'email',
    required: true,
    message: '邮箱地址不合法',
    trigger: 'blur'
  },
  passwordRules: [
    { required: true, message: '请输入登录密码', trigger: 'blur' },
    { min: 8, max: 20, message: '密码长度在8-20个字符之间', trigger: 'blur' },
    { pattern: '^[A-Za-z0-9]+$', message: '密码必须由数字字母组成',trigger: 'blur'}
  ],
  confirmRules: [
    {
      validator(rule, value, callback,source) {
        const {password,confirm} = source;
        if(password !== confirm) {
          callback(false);
        }
        callback()
      },
      message: '两次密码输入不一致',
      trigger: 'change'
    }
  ]
}

复杂表单的校验案例


<l-form is-submit-validate="{{isSubmitValidate}}" name="ruleForm" bind:linsubmit="submit" l-form-btn-class="l-form-btn-class">
    <l-form-item label="登录账号:" name="ruleName" rules="{{nameRules}}">
        <l-input id="ruleName" value="{{ruleForm.name}}" hide-label show-row="{{false}}"/>
    </l-form-item>
    <l-form-item rules="{{musicRules}}" label="选择歌曲:" name="ruleMusic" >
        <l-checkbox-group bind:linchange="change2" id="ruleMusic" placement="row">
            <l-checkbox
                l-class="l-checkbox-color"
                wx:for="{{items2}}"
                wx:key="{{item.id}}"
                placement="{{position}}"
                key="{{item.name}}"
                checked="{{item.checked}}"
            >
                {{item.name}}
            </l-checkbox>
        </l-checkbox-group>
    </l-form-item>
    <l-form-item label="选择性别:" name="ruleSex">
        <l-radio-group id="ruleSex" placement="row">
            <l-radio key="0">
                男
            </l-radio>
            <l-radio key="1">
                女
            </l-radio>
        </l-radio-group>
    </l-form-item>
    <l-form-item rules="{{scoreRules}}" label="自我评分:" name="ruleScore">
        <l-rate id="ruleScore" value="{{ruleForm.score}}" />
    </l-form-item>
    <l-form-item rules="{{descRules}}" label="性格描述:" name="ruleDesc">
        <l-textarea border="{{false}}" id="ruleDesc" value="{{ruleForm.desc}}" />
    </l-form-item>
    <view slot="submit">
        <l-button>提交验证</l-button>
    </view>
    <view slot="reset">
        <l-button type="default" plain>重置</l-button>
    </view>
</l-form>

  data: {
    ruleForm: {
      name: '',
      music: '',
      sex: '',
      desc: '',
      score: ''
    },
    items: [
      {id: 1,name: '青瓷',checked: false},
      {id: 2,name: '双棍',checked: false},
      {id: 3,name: '明天',checked: false}
    ],
    items2: [
      {id: 1,name: '青瓷',checked: false},
      {id: 2,name: '双棍',checked: false},
      {id: 3,name: '明天',checked: false}
    ],
    tipType: 'toast',
    isSubmitValidate: false,
    alignType: 'start',
    nameRules: [
      { required: true, message: '请输入真实姓名', trigger: 'blur' },
      { min: 3, max: 5, message: '长度在 3 到 5 个字符', trigger: 'blur' },
    ],
    descRules: { min: 10, max: 50, message: '请输入10到50个字符的自我描述', trigger: 'change' },
    musicRules: [
      { type:'array', required: true, message: '歌曲必选', trigger: 'change' },
    ],
    scoreRules: [
      { type:'number',required: true, message: '请选择评分', trigger: 'blur' },
      {
        validator(rule, value, callback) {
          if(value < 3) {
            callback(false);
          } else {
            callback()
          }
        },
        message: '评分必须大于等于3分',
        trigger: 'change'
      }
    ]
  }

校验规则属性（Rules Attributes）

参数	说明	类型	可选值	默认值
enum	枚举类型	String	-	-
len	字段长度	Number	-	-
max	最大长度	Number	-	-
message	校验错误提示文案	String	-	-
min	最小长度	Number	-	-
pattern	正则表达式校验	String	-	-
required	是否必选	Boolean	-	`false`
type	内建校验类型	String	见下表	`string`
whitespace	必选时，空格是否会被视为错误	Boolean	-	`false`

更多高级用法可研究 async-validator

TIP

提示：pattern属性的值需是 String，传入正则时，微信小程序不识别，会导致传入的 pattern 是个空的对象。

内置校验类型（Type Value）

参数	说明
string	字符串
number	数字
boolean	布尔
method	方法
regexp	正则
integer	整数
float	浮点数字
array	数组
object	对象
enum	枚举类型，值必须存在 enum 中
date	日期
url	网址
email	邮箱
hex	16进制

手动提交或重置表单

通过wx.lin.submitForm('formName')方法，传入对应表单form 的 name 属性提交表单。

通过wx.lin.resetForm('formName')方法，传入对应表单form 的 name 属性重置表单。

表单容器组件属性 (Form Attributes）

参数	说明	类型	可选值	默认值	版本号
name	表单的name	String	—-	—-	—-
is-submit-validate	提交时是否校验	Boolean	true/false	true	—-

表单容器组件外部样式类（Form ExternalClasses）

外部样式类名	说明	备注	版本号
l-form-container-class	form的外部样式类	—-	—-
l-form-btn-class	按钮容器的外部样式类	—-	—-
l-form-submit-class	提交按钮的外部样式类	—-	—-
l-form-reset-class	重置按钮外部样式类	—-	—-

表单容器组件事件 (Form Events）

事件名称	说明	返回值	备注	版本号
bind:linsubmit	点击提交按钮时触发	点击提交时触发 `linsubmit` 事件，event.detail = {values: 整个表单项的value, errors: 表单内各字段的校验结果，isValidate: 表单是否验证通过}	-	—-
bind:linreset	点击重置按钮时触发	—	-	-

表单项组件属性（Form-Item Attributes）

参数	说明	类型	可选值	默认值	版本号
label	form-item 的文字内容	String	—	—	—
label-placement	文字内容所在区域	String	row/column	row	—
align-items	文字对齐方式	String	start/end/center	start	—
label-width	文字内容的宽度	String	—-	200rpx	—
label-slot	是否开启文字内容插槽	Boolean	true/false	false	—
name	name	String	—	—	—
rules	表单项的验证规则	Object/Array	—	—
tip-type	验证提示类型	String	text/toast/message	text	—

表单项组件外部样式类（Form-Item ExternalClasses）

外部样式类名	说明	备注	版本号
l-form-item-class	form-item的外部样式类		—
l-form-label-class	form-item文字区域的外部样式类		—
l-form-content-class	form-item内容区域的外部样式类		—
l-error-text-class	form-item校验错误提示的外部样式类	当 tip-type 为 text 时有效	—

Form 表单

Form 表单

基础案例

使用更多表单项

示例代码

更改表单域的布局方式

示例代码

设置表单域标签的文字对齐方式

示例代码

设置表单域标签的宽度

示例代码

自定义表单域标签的内容

示例代码

带验证的表单案例

基础校验

自定义校验

复杂表单的校验案例

校验规则属性 （Rules Attributes）

内置校验类型 （Type Value）

手动提交或重置表单

表单容器组件属性 (Form Attributes）

表单容器组件外部样式类（Form ExternalClasses）

表单容器组件事件 (Form Events）

表单项组件属性（Form-Item Attributes）

表单项组件外部样式类（Form-Item ExternalClasses）

校验规则属性（Rules Attributes）

内置校验类型（Type Value）