Form 表单
表单包含 输入框
, 单选框
, 下拉选择
, 多选框
等用户输入的组件。 使用表单,您可以收集、验证和提交数据。
典型表单
最基础的表单包括各种输入表单项,比如 input
、select
等。
在每一个 form
组件中,你需要一个 form-item
字段作为输入项的容器,用于获取值与验证值。
form value:
{ "email": "", "password": "", "confirmPwd": "", "agreement": false, "zone": "" }
<template>
<div>
<vk-form :model="model" ref="formRef">
<vk-form-item prop="email" label="the email">
<vk-input v-model="model.email" />
</vk-form-item>
<vk-form-item prop="password" label="the password">
<vk-input v-model="model.password" type="password" />
</vk-form-item>
<vk-form-item prop="agreement" label="agreement">
<vk-switch v-model="model.agreement" />
</vk-form-item>
<vk-form-item prop="zone" label="zone">
<vk-select v-model="model.zone" :options="options" />
</vk-form-item>
<vk-form-item>
<vk-button @click.prevent="submit" type="primary">Submit</vk-button>
<vk-button @click.prevent="reset">Reset</vk-button>
</vk-form-item>
</vk-form>
<p>
form value:
<pre>{{model}}</pre>
</p>
</div>
</template>
<script setup>
import { reactive, ref } from 'vue';
const model = reactive({
email: '',
password: '',
confirmPwd: '',
agreement: false,
zone: ''
})
const options = [
{ label: 'zone 1', value: 'one' },
{ label: 'zone 2', value: 'two' },
{ label: 'zone 3', value: 'three' }
]
const formRef = ref()
const submit = async () => {
alert('submitted!')
}
const reset = () => {
formRef.value.resetFields()
}
</script>
表单校验
Form
组件允许你验证用户的输入是否符合规范,来帮助你找到和纠正错误。
Form
组件提供了表单验证的功能,只需为 rules
属性传入约定的验证规则,并将 form-Item
的 prop
属性设置为需要验证的特殊键值即可。 更多高级用法可参考 async-validator
。
form value:
{ "email": "", "password": "", "agreement": false, "zone": "" }
<template>
<div>
<vk-form :model="model" :rules="rules" ref="formRef">
<vk-form-item prop="email" label="the email">
<vk-input v-model="model.email" />
</vk-form-item>
<vk-form-item prop="password" label="the password">
<vk-input v-model="model.password" type="password" />
</vk-form-item>
<vk-form-item prop="agreement" label="agreement">
<vk-switch v-model="model.agreement" />
</vk-form-item>
<vk-form-item prop="zone" label="zone">
<vk-select v-model="model.zone" :options="options" />
</vk-form-item>
<vk-form-item>
<vk-button @click.prevent="submit" type="primary">Submit</vk-button>
<vk-button @click.prevent="reset">Reset</vk-button>
</vk-form-item>
</vk-form>
<p>
form value:
<pre>{{model}}</pre>
</p>
</div>
</template>
<script setup>
import { reactive, ref } from 'vue'
const model = reactive({
email: '',
password: '',
agreement: false,
zone: ''
})
const rules = {
email: [{ type: 'email', required: true, trigger: 'blur' }],
password: [{ type: 'string', required: true, trigger: 'blur' }, { min: 3, max: 5, message: 'Length should be 3 to 5', trigger: 'blur' } ],
agreement: [{ type: 'enum', required: true, enum: [true], message: '请同意协议'} ],
zone: [{ type: 'string', required: true, trigger: 'change' }],
}
const options = [
{ label: 'zone 1', value: 'one' },
{ label: 'zone 2', value: 'two' },
{ label: 'zone 3', value: 'three' }
]
const formRef = ref()
const submit = async () => {
try {
await formRef.value.validate()
console.log('passed!')
} catch(e) {
console.log('the promise', e)
}
}
const reset = () => {
formRef.value.resetFields()
}
</script>
自定义校验规则
这个例子中展示了如何使用自定义验证规则来完成密码的二次验证。
form value:
{ "email": "", "password": "", "confirmPwd": "" }
<template>
<div>
<vk-form :model="model" :rules="rules" ref="formRef">
<vk-form-item prop="email" label="the email">
<vk-input v-model="model.email" />
</vk-form-item>
<vk-form-item prop="password" label="the password">
<vk-input v-model="model.password" type="password" />
</vk-form-item>
<vk-form-item prop="confirmPwd" label="confirm password">
<vk-input v-model="model.confirmPwd" type="password" />
</vk-form-item>
<vk-form-item>
<vk-button @click.prevent="submit" type="primary">Submit</vk-button>
<vk-button @click.prevent="reset">Reset</vk-button>
</vk-form-item>
</vk-form>
<p>
form value:
<pre>{{model}}</pre>
</p>
</div>
</template>
<script setup>
import { reactive, ref } from 'vue'
const model = reactive({
email: '',
password: '',
confirmPwd: ''
})
const rules = {
email: [{ type: 'email', required: true, trigger: 'blur' }],
password: [{ type: 'string', required: true, trigger: 'blur' }, { min: 3, max: 5, message: 'Length should be 3 to 5', trigger: 'blur' } ],
confirmPwd: [{ type: 'string', required: true, trigger: 'blur' }, { validator: (rule, value) => value === model.password, trigger: 'blur', message: '两个密码必须一致' } ],
}
const formRef = ref()
const submit = async () => {
try {
await formRef.value.validate()
console.log('passed!')
} catch(e) {
console.log('the promise', e)
}
}
const reset = () => {
formRef.value.resetFields()
}
</script>
FormAPI
属性
属性名 | 说明 | 类型 | 默认值 |
---|---|---|---|
model | 表单数据对象 | Record<string, any> | - |
rules | 表单验证规则 | RuleItem & { trigger?: string} | - |
插槽
插槽名 | 说明 | 子标签 |
---|---|---|
default | 自定义内容 | FormItem |
实例
名称 | 说明 | 类型 |
---|---|---|
validate | 对整个表单的内容进行验证。 | () => Promise<any> |
resetFields | 重置该表单项,将其值重置为初始值,并移除校验结果 | (props?: string[]) => void |
clearValidate | 清理某个字段的表单验证信息。 | (props?: string[]) => void |
FormItem API
属性
属性名 | 说明 | 类型 | 默认值 |
---|---|---|---|
label | 标签文本 | string | - |
prop | model 的键名。在使用了 validate 、resetFields 的方法时,该属性是必填的。 | string | - |
插槽
插槽名 | 说明 | 类型 |
---|---|---|
default | 表单的内容 | - |
label | 标签位置显示的内容 | {label: string} |
实例
名称 | 说明 | 类型 |
---|---|---|
validate | 验证表单项。 | (trigger?: string) => Promise<any>; |
resetField | 对该表单项进行重置,将其值重置为初始值并移除校验结果 | () => void |
clearValidate | 移除该表单项的校验结果。 | () => void |
validateStatus | 校验数据 | {state: 'init' | 'success' | 'error'; errorMsg: string; loading: boolean;} |