Cvue

Form 表单

表单包含 输入框, 单选框, 下拉选择, 多选框 等用户输入的组件。 使用表单，您可以收集、验证和提交数据。

基础用法

Form 组件允许你验证用户的输入是否符合规范，来帮助你找到和纠正错误。

Form 组件提供了表单验证的功能，只需为表单或表单的 columns 配置 rules 属性传入约定的验证规则。 更多高级用法可参考 async-validatoropen in new window。

<template>
  <CvueForm :model="form" :columns="formColumns" @finish="handleFinish"></CvueForm>
</template>

<script lang="ts" setup>
  import { reactive } from 'vue'
  import { ElMessage } from 'element-plus'
  import { cloneDeep } from 'lodash-es'

  let form = reactive({
    sex: 1,
  })

  let formColumns = reactive([
    {
      label: '姓名',
      prop: 'name',
      component: 'input',
      rules: [{ required: true, message: '请输入姓名', trigger: 'blur' }],
    },
    {
      label: '住址',
      prop: 'address',
      rules: [{ required: true, message: '请输入住址', trigger: 'blur' }],
    },
    {
      label: '性别',
      prop: 'sex',
      component: 'radio',
      dic: [
        { label: '男', value: 1 },
        { label: '女', value: 2 },
      ],
    },
    {
      label: '水果',
      component: 'select',
      prop: 'fruit',
      dic: [
        { label: '苹果', value: 1 },
        { label: '香蕉', value: 2 },
        { label: '荔枝', value: 3 },
      ],
      rules: [{ required: true, message: '请选择水果', trigger: 'change' }],
    },
    {
      label: '生日',
      prop: 'birthday',
      component: 'date-picker',
      rules: [{ required: true, message: '请选择日期', trigger: 'change' }],
    },
    {
      label: '时间',
      prop: 'time',
      component: 'time-picker',
      rules: [{ required: true, message: '请选择时间', trigger: 'change' }],
    },
    {
      label: '随时到岗',
      prop: 'switch',
      component: 'switch',
    },
    {
      label: '蔬菜',
      component: 'checkbox',
      prop: 'vegetable',
      dic: [
        { label: '毛豆', value: 1 },
        { label: '番茄', value: 2 },
        { label: '南瓜', value: 3 },
      ],
      rules: [{ required: true, message: '请选择蔬菜', trigger: 'change' }],
    },
    {
      label: '备注',
      prop: 'remark',
      type: 'textarea',
    },
  ])

  const handleFinish = (value: any, done: any) => {
    setTimeout(() => {
      console.log(value)
      ElMessage.success(JSON.stringify(value))
      done()
    }, 2000)
  }
</script>

行内表单

当垂直方向空间受限且表单较简单时，可以在一行内放置表单。通过设置 inline 属性为 true 可以让表单域变为行内的表单域。

<template>
  <cvue-form :model="form" :columns="columns" :inline="true"></cvue-form>
</template>

<script lang="ts" setup>
  import { reactive } from 'vue'

  let form = reactive({})
  let columns = [
    {
      label: '姓名',
      prop: 'name',
    },
    {
      label: '婚姻状态',
      prop: 'maritalStatus',
      component: 'select',
      dic: [
        { label: '未婚', value: 1 },
        { label: '已婚', value: 2 },
        { label: '丧偶', value: 3 },
        { label: '离婚', value: 4 },
      ],
    },
  ]
</script>

对齐方式

根据你们的设计情况，来选择最佳的标签对齐方式。

通过设置 label-position 属性可以改变表单域标签的位置，可选值为 top、left， 当设为 top 时标签会置于表单域的顶部

<template>
  <el-radio-group v-model="labelPosition" label="label position">
    <el-radio-button label="left">Left</el-radio-button>
    <el-radio-button label="right">Right</el-radio-button>
    <el-radio-button label="top">Top</el-radio-button>
  </el-radio-group>
  <div style="margin: 20px" />
  <cvue-form  style="max-width: 460px" :model="form" :columns="columns" :label-position="labelPosition"></cvue-form>
</template>

<script lang="ts" setup>
import { reactive, ref } from 'vue'

const labelPosition = ref('right')

const formLabelAlign = reactive({
  name: '',
  sex: 1
})

let form = reactive({})
let columns = [
  {
    label: '姓名',
    prop: 'name',
  },
  {
    label: '婚姻状态',
    prop: 'maritalStatus',
    component: 'select',
    dic: [
      { label: '未婚', value: 1 },
      { label: '已婚', value: 2 },
      { label: '丧偶', value: 3 },
      { label: '离婚', value: 4 },
    ],
  },
]
</script>

属性

属性名说明类型默认值
model表单数据对象Record<string, any>-
v-model表单数据对象Record<string, any>-
rules表单验证规则FormRules-
inline行内表单模式booleanfalse
label-position表单域标签的位置， 当设置为 left 或 right 时，则也需要设置 label-width 属性'left' | 'right' | 'top''right'
label-width标签的长度，例如 '50px'。 作为 Form 直接子元素的 form-item 会继承该值。 可以使用 auto。string | number84
label-suffix表单域标签的后缀string-
hide-required-asterisk是否隐藏必填字段标签旁边的红色星号。booleanfalse
require-asterisk-position星号的位置。'left' | 'right''left'
show-message是否显示校验错误信息booleantrue
inline-message是否以行内形式展示校验信息booleanfalse
status-icon是否在输入框中显示校验结果反馈图标booleanfalse
validate-on-rule-change是否在 rules 属性改变后立即触发一次验证booleantrue
size用于控制该表单内组件的尺寸'large' | 'default' | 'small'-
disabled是否禁用该表单内的所有组件。 如果设置为 true, 它将覆盖内部组件的 disabled 属性booleanfalse
scroll-to-error当校验失败时，滚动到第一个错误表单项booleanfalse

事件

插槽名说明slotProps
validate任一表单项被校验后触发(prop: FormItemProp, isValid: boolean, message: string) => void

方法

方法名说明类型
validate对整个表单的内容进行验证。 接收一个回调函数，或返回 Promise。(callback?: (isValid: boolean, invalidFields?: ValidateFieldsError) => void) => Promise<void>
validateField验证具体的某个字段。(props?: Arrayable<FormItemProp>, callback?: (isValid: boolean, invalidFields?: ValidateFieldsError) => void) => Promise<void>
resetFields重置该表单项，将其值重置为初始值，并移除校验结果(props?: Arrayable<FormItemProp>) => void
scrollToField滚动到指定的字段(prop: FormItemProp) => void
clearValidate清理某个字段的表单验证信息。(props?: Arrayable<FormItemProp>) => void
上次更新:
贡献者: wishzhang