Form 表单组件

Form 包含 input、radio、select、checkbox 等需要用户输入的组件。VISTA B 直接使用 Element Plus 的 el-form 和 el-form-item，用于收集、验证和提交数据。

TIP

Element Plus Form 已从旧版 Float 布局升级为 Flex 布局。

典型表单

每个输入项都应放在 el-form-item 中，el-form-item 用于承载标签、内容、校验和错误信息。

Activity name

Activity zone

please select your zone

Activity time

-

Instant delivery

Activity type

Online activitiesPromotion activitiesOffline activities

Resources

SponsorVenue

Activity form

<el-form :model="form" label-width="auto">
  <el-form-item label="Activity name">
    <el-input v-model="form.name" />
  </el-form-item>
  <el-form-item label="Activity zone">
    <el-select v-model="form.region" placeholder="please select your zone">
      <el-option label="Zone one" value="shanghai" />
      <el-option label="Zone two" value="beijing" />
    </el-select>
  </el-form-item>
  <el-form-item>
    <el-button type="primary">Create</el-button>
    <el-button>Cancel</el-button>
  </el-form-item>
</el-form>

行内表单

设置 inline 后，表单域会在一行内排列，适合简单筛选条件。

Approved by

Activity zone

Activity zone

Activity time

<el-form :inline="true" :model="formInline">
  <el-form-item label="Approved by">
    <el-input v-model="formInline.user" placeholder="Approved by" clearable />
  </el-form-item>
  <el-form-item label="Activity zone">
    <el-select v-model="formInline.region" placeholder="Activity zone" clearable />
  </el-form-item>
  <el-form-item>
    <el-button type="primary">Query</el-button>
  </el-form-item>
</el-form>

对齐方式

通过 label-position 控制表单标签位置。el-form-item 也支持单独设置 label-position，不设置时继承 Form 的配置。

Form Align

LeftRightTop

Form Item Align

EmptyLeftRightTop

Name

Activity zone

Activity form

<el-form :label-position="labelPosition" label-width="auto" :model="formLabelAlign">
  <el-form-item label="Name" :label-position="itemLabelPosition">
    <el-input v-model="formLabelAlign.name" />
  </el-form-item>
  <el-form-item label="Activity zone" :label-position="itemLabelPosition">
    <el-input v-model="formLabelAlign.region" />
  </el-form-item>
</el-form>

表单校验

Form 通过 rules 定义校验规则，并在 el-form-item 上设置 prop 来绑定对应字段。校验规则基于 async-validator。

Activity name

Activity zone

Activity zone

Activity count

Activity count

Activity time

-

Activity location

Home

Company

School

Activity type

Online activitiesPromotion activitiesOffline activities

Resources

SponsorshipVenue

Activity form

<script setup>
import { reactive, ref } from 'vue'

const ruleFormRef = ref()
const ruleForm = reactive({
  name: '',
  region: ''
})

const rules = reactive({
  name: [
    { required: true, message: 'Please input Activity name', trigger: 'blur' },
    { min: 3, max: 5, message: 'Length should be 3 to 5', trigger: 'blur' }
  ],
  region: [{ required: true, message: 'Please select Activity zone', trigger: 'change' }]
})

const submitForm = async (formEl) => {
  if (!formEl) return
  await formEl.validate()
}
</script>

自定义校验规则

规则对象可以使用 validator 自定义校验逻辑，适合密码确认、年龄限制等跨字段场景。

Password

Confirm

Age

const validatePass2 = (rule, value, callback) => {
  if (value === '') {
    callback(new Error('Please input the password again'))
    return
  }

  if (value !== ruleForm.pass) {
    callback(new Error("Two inputs don't match!"))
    return
  }

  callback()
}

添加/删除表单项

动态表单项可以使用数组路径作为 prop，并为每一项单独设置 rules。

Email

Domain 1

<el-form-item
  v-for="(domain, index) in dynamicValidateForm.domains"
  :key="domain.key"
  :label="`Domain ${index + 1}`"
  :prop="['domains', index, 'value']"
  :rules="{ required: true, message: 'domain can not be null', trigger: 'blur' }"
>
  <el-input v-model="domain.value" />
</el-form-item>

数字类型验证

数字类型验证需要在 v-model 上加 .number 修饰符，将输入值转成 number。

age

<el-form-item
  label="age"
  prop="age"
  :rules="[
    { required: true, message: 'age is required' },
    { type: 'number', message: 'age must be a number' }
  ]"
>
  <el-input v-model.number="numberValidateForm.age" />
</el-form-item>

TIP

当一个 el-form-item 嵌套在另一个 el-form-item 中时，内部表单项的标签宽度会变为 0。如果需要，可以为内部 el-form-item 单独设置 label-width。

尺寸控制

Form 的 size 会被表单内子组件继承。若某个表单项或表单组件需要不同尺寸，可以在该项上单独设置 size。

Size

largedefaultsmall

Label

LeftRightTop

Activity name

Activity zone

please select your zone

Activity time

-

Resources

SponsorVenue

<el-form :model="sizeForm" :size="size" :label-position="labelPosition">
  <el-form-item label="Activity name">
    <el-input v-model="sizeForm.name" />
  </el-form-item>
  <el-form-item label="Resources">
    <el-radio-group v-model="sizeForm.resource">
      <el-radio border value="Sponsor">Sponsor</el-radio>
      <el-radio border value="Venue">Venue</el-radio>
    </el-radio-group>
  </el-form-item>
</el-form>

无障碍

当 el-form-item 内只有一个输入控件时，标签会自动关联到该控件。若一个 el-form-item 内包含多个输入控件，需要为每个控件单独设置可访问标签。

"Full Name" label is automatically attached to the input:

Full Name

"Your Information" serves as a label for the group of inputs. Specify labels on the individual inputs.

Your Information

<el-form-item label="Your Information">
  <el-row :gutter="20">
    <el-col :span="12">
      <el-input aria-label="First Name" placeholder="First Name" />
    </el-col>
    <el-col :span="12">
      <el-input aria-label="Last Name" placeholder="Last Name" />
    </el-col>
  </el-row>
</el-form-item>

API

Form 属性

属性	说明	类型	默认值
model	表单数据对象	object	-
rules	表单验证规则	object	-
inline	是否为行内表单	boolean	false
label-position	表单域标签位置	left / right / top	right
label-width	标签宽度，支持 auto	string / number	''
label-suffix	标签后缀	string	''
hide-required-asterisk	是否隐藏必填字段标签旁的红色星号	boolean	false
require-asterisk-position	星号位置	left / right	left
show-message	是否显示校验错误信息	boolean	true
inline-message	是否以行内形式展示校验信息	boolean	false
status-icon	是否在输入框中显示校验结果反馈图标	boolean	false
validate-on-rule-change	rules 改变后是否立即触发验证	boolean	true
size	控制表单内组件尺寸	large / default / small	-
disabled	是否禁用表单内所有组件	boolean	false
scroll-to-error	校验失败时是否滚动到第一个错误表单项	boolean	false
scroll-into-view-options	校验失败时滚动到错误项的配置	object / boolean	true

Form 事件

事件	说明	类型
validate	任一表单项被校验后触发	(prop, isValid, message) => void

Form 插槽

插槽	说明
default	自定义默认内容

Form 暴露

名称	说明	类型
validate	校验整个表单	(callback?) => Promise<boolean>
validateField	校验指定字段	(props?, callback?) => Promise<boolean>
resetFields	重置指定字段并移除校验结果	(props?) => void
clearValidate	清除指定字段的校验信息	(props?) => void
scrollToField	滚动到指定字段	(prop) => void
getField	获取字段上下文	(prop) => FormItemContext | undefined
fields	所有字段上下文	FormItemContext[]
setInitialValues	设置字段初始值	(initModel) => void

FormItem 属性

属性	说明	类型	默认值
prop	model 中的字段路径，校验和重置时需要设置	string / array	-
label	标签文本	string	-
label-width	标签宽度，支持 auto	string / number	-
label-position	标签位置，默认继承 Form	left / right / top / ''	''
required	是否必填，省略时由规则决定	boolean	-
rules	当前表单项校验规则	object / array	-
error	手动设置错误信息	string	-
validate-status	校验状态	error / validating / success	-
for	原生 label 的 for 属性	string	-
inline-message	是否以行内形式展示校验信息	boolean	-
show-message	是否显示校验错误信息	boolean	true
size	控制当前表单项内组件尺寸	large / default / small	-

FormItem 插槽

插槽	说明
default	表单项默认内容
label	自定义标签内容
error	自定义错误信息内容

FormItem 暴露

名称	说明	类型
size	当前表单项尺寸	ComputedRef
validateMessage	校验消息	Ref<string>
validateState	校验状态	Ref<string>
validate	校验当前表单项	(trigger, callback?) => Promise<boolean>
clearValidate	清除当前表单项校验状态	() => void
resetField	重置当前字段并清除校验结果	() => void
setInitialValue	设置当前字段初始值	(value) => void

使用提醒

• 每个需要校验或重置的字段都应设置 prop，并确保它能对应到 model 中的字段。
• 复杂表单优先按业务区块拆分，避免单页表单过长影响定位和校验反馈。
• 一个 el-form-item 内有多个输入控件时，不要只依赖占位符，应为每个控件提供可访问标签。