V3 Element

Appearance

On this page

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-
propmodel 的键名。在使用了 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;}