Form 表单

此组件一般由输入框、选择器、单选框、多选框等控件组成，用以收集、校验、提交数据。

平台差异说明

APP	H5	微信小程序	支付宝小程序	QQ小程序	···
√	√	√	√	√	适配中

代码示例

部分功能示例，具体可参考示例程序以及文档API。

基础用法

此组件一般用于表单验证，每个表单域由一个 fu-form-item 组成，在表单域中可以放置 fu-input、fu-textarea、fu-checkbox、fu-switch 等。

在表单组中，通过 :model 属性绑定一个对象，这个对象的属性名为各个 fu-form-item 内组件的对应变量。
由于表单验证和绑定表单规则时，需要通过 ref 操作，故这里需要给 form 组件生命 ref="formRef" 属性。
关于 fu-form-item 组件内其他可能包含的如 input、checkbox 等组件，请详见各组件的相关文档说明。

html

<template>
    <view>
        <!-- 注意：如果需要兼容微信小程序，最好通过setRules方法设置rules规则 -->
        <fu-form 
            ref="formRef"
            :model="model"
            :rules="rules"
        >
            <fu-form-item label="姓名" prop="name">
                <fu-input v-model="model.name" placeholder="请输入姓名"></fu-input>
            </fu-form-item>
            <fu-form-item label="年龄" prop="age">
                <fu-input v-model="model.age" placeholder="请输入年龄"></fu-input>
            </fu-form-item>
        </fu-form>
    </view>
</template>

<script setup>
    import { ref, reactive } from 'vue';
    import { onReady } from '@dcloudio/uni-app';

    // data数据
    const formRef = ref();
    let model = ref({
        name: '',
        age: ''
    });
    const rules = reactive({
        name: {
            rules: [{
                required: true,
                message: '姓名不能为空'
            }]
        },
        age: {
            rules: [{
                required: true,
                message: '年龄不能为空'
            }, {
                format: 'number',
                message: '年龄只能输入数字'
            }, {
                validateFunction: (rule, value, data, callback) => {
                    // 异步需要返回 Promise 对象
                    return new Promise((resolve, reject) => {
                        setTimeout(() => {
                            if (value > 10) {
                                // 通过返回 resolve
                                resolve()
                            } else {
                                // 不通过返回 reject(new Error('错误信息'))
                                reject(new Error('年龄必须大于十岁'))
                            }
                        }, 0)
                    })
                }
            }]
        }
    });

    // 生命周期
    onReady(() => {
        // 如果需要兼容微信小程序，并且校验规则中含有方法等，只能通过setRules方法设置rules规则
        formRef.value.setRules(rules)
    });
</script>

从上面的示例中我们可以看到，rules 中的属性名和 form 的属性名是一致的，同时传递给 fu-form-item 的 prop 属性绑定的也是相同的属性名，注意这里的 prop 属性绑定的是字符串（属性名），而不是一个变量。

label 对齐方式

通过 labelPosition 属性设置表单域标签的位置，默认 left 左对齐，当设为 top 时标签将置于表单域的顶部。

html

<fu-form labelPosition="top">
    <fu-form-item label="姓名" labelPosition="top">
        <fu-input v-model="model.name" placeholder="请输入姓名"></fu-input>
    </fu-form-item>
    <fu-form-item label="年龄">
        <fu-input v-model="model.age" placeholder="请输入年龄"></fu-input>
    </fu-form-item>
</fu-form>

form-item 组件说明

此组件一般需要结合 form 组件使用，也可以单独搭配 input 等组件使用，由于此组件属性较多，这里只对其中属性最简要介绍，其余请见底部的API说明：

prop 属性传入 form 组件的 model 中的属性字段，如果需要表单校验，此属性必填
labelPosition 可以配置左侧 label 的对齐方式, 可选值为 left 和 top
如果想在表单域配置左侧的图标或小图片，可以通过 label 插槽自定义，插槽名为 label

注意

fu-form-item 组件中的 labelPosition 优先级高于 fu-form 组件中的 labelPosition

表单校验

表单组件具备完整的校验功能，验证用户的输入是否符合规范，可以满足大部分常见的校验场景

model 属性为一个对象，对象属性为需要验证的变量名
通过 ref 在 onMounted 或 onReady 生命周期时获取 form 组件实例，并调用组件的 setRules 方法绑定验证规则，无法通过 props 传递变量，因为微信小程序会过滤掉对象中的方法，导致自定义验证规则无效

html

<template>
    <view>
        <!-- 注意：如果需要兼容微信小程序，最好通过setRules方法设置rules规则 -->
        <fu-form 
            ref="formRef"
            :model="model"
            :rules="rules"
        >
            <fu-form-item label="姓名" prop="name">
                <fu-input v-model="model.name" placeholder="请输入姓名"></fu-input>
            </fu-form-item>
            <fu-form-item label="年龄" prop="name">
                <fu-input v-model="model.age" placeholder="请输入年龄"></fu-input>
            </fu-form-item>
        </fu-form>

        <fu-button @click="handleSubmit">提交</fu-button>
    </view>
</template>

<script setup>
    import { ref, reactive } from 'vue';
    import { onReady } from '@dcloudio/uni-app';

    // data数据
    const formRef = ref();
    let model = ref({
        name: '',
        age: ''
    });
    const rules = reactive({
        name: {
            rules: [{
                required: true,
                message: '姓名不能为空'
            }]
        },
        age: {
            rules: [{
                required: true,
                message: '年龄不能为空'
            }, {
                format: 'number',
                message: '年龄只能输入数字'
            }, {
                validateFunction: (rule, value, data, callback) => {
                    // 非异步校验
                    // if (value < 10) {
                    //     callback('年龄必须大于十岁')
                    // }
                    // return true

                    // 异步需要返回 Promise 对象
                    return new Promise((resolve, reject) => {
                        setTimeout(() => {
                            if (value > 10) {
                                // 通过返回 resolve
                                resolve()
                            } else {
                                // 不通过返回 reject(new Error('错误信息'))
                                reject(new Error('年龄必须大于十岁'))
                            }
                        }, 0)
                    })
                }
            }]
        }
    });

    // 生命周期
    onReady(() => {
        // 如果需要兼容微信小程序，并且校验规则中含有方法等，只能通过setRules方法设置rules规则
        formRef.value.setRules(rules)
    });

    // methods方法
    const handleSubmit = () => {
        formRef.value.validate().then(() => {
            console.log('校验成功')
            uni.$fu.toast('校验通过')
        }).catch(() => {
            console.log('校验失败')
        });
    };
</script>

rules 属性说明

每一个校验规则中，可以设置多个属性，下面对常用的属性进行说明：

required 是否必填，此属性不会显示输入框左边的必填星号，如需要，请设置 fu-form-item 组件的 required 属性为 true
range 数组至少要有一个元素，且数组内的每一个元素都是唯一的
format 内置校验规则，如这些规则无法满足需求，可以使用正则匹配或自定义规则，可选值：
- string 必须是 string 类型，默认类型
- number 必须是 number 类型
- boolean 必须是 boolean 类型
- array 必须是 array 类型
- object 必须是 object 类型
- url 必须是 url 类型
- email 必须是 email 类型
pattern 正则表达式，注意事项见下方说明
maximum 校验最大值(大于)
minimum 校验最小值(小于)
maxLength 校验数据最大长度
message 校验失败提示信息语，可添加属性占位符，当前表格内属性都可用作占位符
validateFunction 自定义校验函数，函数为四个参数：
- rule 当前校验字段在 rules 中所对应的校验规则
- value 当前校验字段的值
- data 所有校验字段的字段和值的对象
- callback 校验完成时的回调，一般无需执行callback，返回true(校验通过)或者false(校验失败)即可，如果需要显示不同的 message，如果校验不通过需要执行 callback('提示错误信息')，如果校验通过，执行callback()即可

pattern属性说明

在小程序中，json 中不能使用正则对象，如：/^\S+?@\S+?.\S+?$/，使用正则对象会被微信序列化，导致正则失效。
所以建议统一使用字符串的方式来使用正则，如'^\S+?@\S+?\.\S+?$' ，需要注意 \ 需要使用 \ 来转译。
如验证邮箱：/^\S+?@\S+?.\S+?$/ （注意不带引号）,或使用 "^\S+?@\S+?.\S+?$"（注意带引号需要使用 \ 转义）

validateFunction 自定义校验规则使用说明

fu-form 的 rules 基础规则有时候不能满足项目的所有使用场景，这时候可以使用 validateFunction 来自定义校验规则，详见上方表单校验

validateFunction 方法返回四个参数 validateFunction:function(rule,value,data,callback){}，当然返回参数名可以自定义

注意

需要注意，如果需要使用 validateFunction 自定义校验规则,则不能采用 fu-form 的 rules 属性来配置校验规则，这时候需要通过 ref，在 onReady 生命周期调用组件的 setRules 方法绑定验证规则
无法通过props传递变量，是因为微信小程序会过滤掉对象中的方法，导致自定义验证规则无效。
如果使用了 validateFunction 且 required 为 false 的情况，表现为不填写内容不校验，有内容才校验，所以内容为空时 validateFunction 不会执行

API

Form Props

属性名	说明	类型	默认值	可选值
model	表单数据	Object	-	-
rules	表单验证规则	Object	-	-
validateTrigger	表单校验时机，blur仅在 `fu-input` 中生效	String	submit	bind/blur
labelPosition	label 位置，详见上方form-item 组件说明	String	left	top
labelWidth	label 宽度	Number	70	-
labelAlign	label 对齐方式	String	left	center/right
errShowType	表单错误信息提示方式	String	undertext	toast/modal

Form Methods

方法名	说明	参数
validate	表单校验	-
resetFields	重置表单	-
clearValidate	清除表单的校验结果	-
setRules	设置表单项的校验规则	rules

Form Events

事件名	说明	回调参数
validate	表单项被校验后触发，返回表单校验信息	-

Form Slot

名称	说明
default	表单内容，可以放置 `fu-form-item` 组件

FormItem Props

属性名	说明	类型	默认值	可选值
prop	表单域model对象的属性名，在使用 validate、resetFields 方法的情况下，该属性是必填的	String	-	-
label	label 文本	String	-	-
labelWidth	label 宽度	Number	70	-
labelAlign	label 对齐方式	String	left	center/right
message	表单域验证错误信息，如果为空字符串或者false，则不显示错误信息	String	-	-
required	是否显示左边的"*"号，样式显示不会对校验规则产生效果，如需校验必填，请通过rules配置必填规则	Boolean	false	true
labelPosition	label 位置，详见上方form-item 组件说明	String	left	top

FormItem Methods

方法名	说明	参数
setRules	动态设置表单规则	-
onFieldChange	校验子表单	-

FormItem Slot

名称	说明
default	Form Item 的内容
label	自定义label显示内容

Form 表单 ​

平台差异说明 ​

代码示例 ​

基础用法 ​

label 对齐方式 ​

form-item 组件说明 ​

表单校验 ​

rules 属性说明 ​

validateFunction 自定义校验规则使用说明 ​

API ​

Form Props ​

Form Methods ​

Form Events ​

Form Slot ​

FormItem Props ​

FormItem Methods ​

FormItem Slot ​

Form 表单

平台差异说明

代码示例

基础用法

label 对齐方式

form-item 组件说明

表单校验

rules 属性说明

validateFunction 自定义校验规则使用说明

API

Form Props

Form Methods

Form Events

Form Slot

FormItem Props

FormItem Methods

FormItem Slot