Form 表单

AuForm 管理字段模型、规则和整体验证，AuFormItem 负责标签、错误信息和字段级状态。它们不改变内部控件的值，适合组合 Aurora Plus 控件或原生表单元素。

基础用法

vue

<template>
  <AuForm :model="form" label-width="76" @submit.prevent="validateForm">
    <AuFormItem
      ref="nameItemRef"
      v-slot="{ invalid }"
      label="名称"
      prop="name"
      :rules="nameRules"
    >
      <AuInput v-model="form.name" placeholder="输入日程名称" :invalid="invalid" />
    </AuFormItem>
    <AuFormItem
      ref="dateItemRef"
      v-slot="{ invalid }"
      label="日期"
      prop="date"
      :rules="dateRules"
    >
      <AuDatePicker v-model="form.date" :invalid="invalid" />
    </AuFormItem>
    <AuFormItem>
      <div class="form-demo__actions">
        <AuButton native-type="submit" type="primary">保存并校验</AuButton>
        <AuButton @click="resetForm">重置</AuButton>
      </div>
    </AuFormItem>
    <p v-if="result" class="form-demo__result" role="status" aria-live="polite">
      {{ result }}
    </p>
  </AuForm>
</template>
<script setup>
import { reactive, ref } from 'vue';
import {
  AuButton,
  AuDatePicker,
  AuForm,
  AuFormItem,
  AuInput,
} from 'aurora-plus';
const nameItemRef = ref(null);
const dateItemRef = ref(null);
const result = ref('');
const form = reactive({ name: '', date: '' });
const nameRules = [
  { required: true, message: '请输入名称', trigger: 'blur' },
  { min: 2, max: 24, message: '名称长度应为 2–24 个字符', trigger: 'change' },
];
const dateRules = [
  { required: true, message: '请选择日期', trigger: 'change' },
];
async function validateForm() {
  const [nameValid, dateValid] = await Promise.all([
    nameItemRef.value.validate(),
    dateItemRef.value.validate(),
  ]);
  if (nameValid && dateValid) {
    result.value = '校验通过。';
    return;
  }
  const messages = [];
  if (!nameValid) messages.push(readError(nameItemRef.value, '请输入名称'));
  if (!dateValid) messages.push(readError(dateItemRef.value, '请选择日期'));
  result.value = messages.join('；');
}
function readError(field, fallback) {
  const message = field?.errorMessage;
  return (typeof message === 'string' ? message : message?.value) || fallback;
}
function resetForm() {
  nameItemRef.value.resetField();
  dateItemRef.value.resetField();
  result.value = '';
}
</script>
<style scoped>
.au-form {
  width: min(100%, 480px);
}
.form-demo__actions {
  display: flex;
  gap: 8px;
}
.form-demo__result {
  margin: 0 0 0 76px;
  color: var(--au-color-text-secondary);
  font-size: var(--au-font-size-small);
}
</style>

校验规则

规则支持 required、whitespace、type、enum、pattern、len、min、max、transform、defaultField、fields、message 和 trigger。trigger 可为 change、blur 或数组；未设置时所有验证入口都会执行。validator(rule, value, callback, model, options) 与 asyncValidator 可以同步返回、返回 Promise，或调用 callback。

type 支持 string、number、integer、boolean、array、object、date、email、url、regexp、method 和 hex。字符串与数组的 min / max 表示长度，数字则比较数值。

Form Attributes

属性	说明	类型	默认值
`model`	表单模型	`object`	`{}`
`rules`	按字段路径组织的规则	`object`	`{}`
`labelPosition`	标签位置	`left / right / top`	`right`
`labelWidth`	标签宽度	`string / number`	`''`
`size`	提供给 FormItem 插槽的尺寸	`small / default / large`	`default`
`inline`	行内排列	`boolean`	`false`
`disabled`	提供给 FormItem 插槽的禁用状态	`boolean`	`false`
`showMessage`	是否显示字段错误	`boolean`	`true`
`inlineMessage`	错误信息是否与控件同行	`boolean`	`false`
`statusIcon`	是否显示成功、错误和验证中图标	`boolean`	`false`
`hideRequiredAsterisk`	隐藏必填星号	`boolean`	`false`
`requireAsteriskPosition`	星号位置	`left / right`	`left`
`validateOnRuleChange`	规则变化后重新校验	`boolean`	`true`
`scrollToError`	整体验证失败时滚动到首个错误	`boolean`	`false`
`scrollIntoViewOptions`	自动滚动参数；`false` 使用浏览器默认值	`object / false`	`{ block: 'center', behavior: 'smooth' }`

size、disabled、invalid、error 和 fieldId 通过 FormItem 默认插槽参数提供，避免表单直接修改子组件内部属性。需要同步控件错误外观时可将 invalid 绑定给输入控件。

Form Events 与 Exposes

名称	说明
`validate(prop, valid, message)`	字段完成一次校验
`submit(event)`	原生 submit 事件；是否阻止默认行为由使用者决定
`validate(callback?)`	验证全部字段，Promise 返回布尔值
`validateField(props, callback?)`	验证一个或多个字段
`resetFields(props?)`	恢复字段初始值并清除状态
`clearValidate(props?)`	清除字段校验状态
`scrollToField(prop, options?)`	滚动到字段
`getField(prop)`	获取已注册字段上下文
`fields`	已注册字段 Map

字段路径支持 profile.name 和 items[0].title。

FormItem Attributes

属性	说明	类型	默认值
`label`	标签文字	`string`	`''`
`labelFor`	标签关联的控件 id	`string`	`''`
`labelWidth` / `labelPosition`	覆盖表单标签布局	`string / number`	`''`
`prop`	模型字段路径	`string / path[]`	`''`
`required`	添加必填规则并显示必填标识	`boolean`	`false`
`rules`	字段附加规则	`object / array`	`null`
`error`	外部错误文字	`string`	`''`
`validateStatus`	外部状态	`error / success / validating`	`''`
`showMessage`	是否显示该字段错误	`boolean`	`true`
`inlineMessage` / `statusIcon`	覆盖表单的行内错误 / 状态图标设置	`boolean`	—
`validateEvent`	是否响应模型 change 与控件 blur 自动校验	`boolean`	`true`
`size`	覆盖表单尺寸	`small / default / large`	`''`

插槽包括 default、label 和 error。组件暴露 validate(trigger?)、resetField()、clearValidate()、errorMessage 与 element。

Form 表单 ​

基础用法 ​

校验规则 ​

Form Attributes ​