表单验证

在 column.rules 中填写校验规则数组，例如必填、格式、长度或自定义 validator。表单字段需有稳定的 prop，绑定数据对象使用 v-model。

基础用法

效果预览可直接操作下方示例

rules 为数组。先直接提交查看必填提示，补齐字段后再次提交。

正在加载示例…

<template>
  <avue-form :option="option"
             @submit="submit"
             @error="error"></avue-form>
</template>

<script setup>
import { ref } from 'vue';
import { ElMessage } from 'element-plus';

const option = ref({
  column: [
    {
      label: '姓名',
      prop: 'name',
      rules: [
        {
          required: true,
          message: '请输入姓名',
          trigger: 'blur'
        }
      ]
    },
    {
      label: '性别',
      prop: 'sex',
      rules: [
        {
          required: true,
          message: '请输入性别',
          trigger: 'blur'
        }
      ]
    }
  ]
});

const submit = (form, done) => {
  ElMessage.success(JSON.stringify(form));
  done();
};

const error = (err) => {
  ElMessage.success('请查看控制台');
  console.log(err);
};
</script>

外置验证

Avue 的 validate(callback) 会同时校验表单及可见的 Dynamic 子表，回调签名为 (valid, done, errors)。它返回 void，不能用 await formRef.value.validate() 判断是否有效。通过校验后表单会锁定，完成自己的操作后需要调用 done()。

效果预览可直接操作下方示例

点击“验证表单”，下方显示是否通过与错误字段；通过或失败后仍可继续编辑。点击“清除校验提示”只清除提示，不修改数据。

正在加载示例…

<template>
  <el-space wrap>
    <el-button type="primary" @click="validate">验证表单</el-button>
    <el-button @click="formRef?.clearValidate()">清除校验提示</el-button>
  </el-space>
  <avue-form ref="formRef" v-model="form" :option="option" />
  <pre>{{ JSON.stringify(result, null, 2) }}</pre>
</template>

<script setup>
import { ref } from 'vue';
const formRef = ref(null);
const form = ref({ name: '', email: '' });
const result = ref(null);
const option = {
  menuBtn: false,
  column: [
    { label: '姓名', prop: 'name', span: 24, rules: [
      { required: true, message: '请输入姓名', trigger: 'blur' },
    ] },
    { label: '邮箱', prop: 'email', span: 24, rules: [
      { required: true, message: '请输入邮箱', trigger: 'blur' },
      { type: 'email', message: '邮箱格式不正确', trigger: 'blur' },
    ] },
  ],
};
function validate() {
  formRef.value.validate((valid, done, errors) => {
    result.value = { valid, fields: Object.keys(errors || {}) };
    // Avue locks the form after successful validation; always release it.
    done();
  });
}
</script>

仅验证单个字段可调用 validateField('name')，它透传 Element Plus 的 Promise；失败时需要处理 rejection。这个方法不会额外遍历 Dynamic 子表。

try {
  await formRef.value.validateField('name');
} catch (errors) {
  // 字段未通过校验
}

自定义验证

效果预览可直接操作下方示例

validator 接收 rule、value、callback，根据业务规则调用 callback() 或 callback(new Error('提示'))。每个分支都应结束校验；插槽输入仍需绑定当前 prop 对应的值。

正在加载示例…

<template>
  <avue-form v-model="obj"
             :option="option1"
             @submit="submit"
             @error="error"></avue-form>
</template>

<script setup>
import { ref } from 'vue';
import { ElMessage } from 'element-plus';

const obj = ref({
  name: '张三',
  password: '',
  oldpassword: ''
});

const option1 = {
  column: [
    {
      label: '姓名',
      prop: 'name',
      rules: [
        {
          required: true,
          message: "请输入姓名",
          trigger: "blur"
        }
      ]
    },
    {
      label: '性别',
      prop: 'sex',
      rules: [
        {
          required: true,
          message: "请输入性别",
          trigger: "blur"
        }
      ]
    },
    {
      label: '密码',
      prop: 'password',
      type: 'password',
      rules: [
        {
          validator: (rule, value, callback) => {
            if (value === '') {
              callback(new Error('请输入密码'));
            } else {
              callback();
            }
          },
          trigger: 'blur'
        }
      ]
    },
    {
      label: '确认密码',
      prop: 'oldpassword',
      type: 'password',
      rules: [
        {
          validator: (rule, value, callback) => {
            if (value === '') {
              callback(new Error('请再次输入密码'));
            } else if (value !== obj.value.password) {
              callback(new Error('两次输入密码不一致!'));
            } else {
              callback();
            }
          },
          trigger: 'blur'
        }
      ]
    }
  ]
};

const submit = (form, done) => {
  ElMessage.success(JSON.stringify(form));
  done();
};

const error = (err) => {
  ElMessage.success('请查看控制台');
  console.log(err);
};
</script>

resetForm() 默认清空数据；resetFields() 还原 Element Plus 注册时的初始值；clearValidate() 只清校验信息。这三种操作的用途不同，完整方法见 Form API。