Appearance
Form 表单
高性能表单组件，字段级精确更新，支持多种布局和丰富的校验规则。
基础用法
使用 useForm() 获取表单实例，@finish 在校验通过后触发。
校验规则
内置 required、min/max、pattern、email、whitespace，以及自定义 validator。
字段联动
effect 监听指定字段变化触发重新渲染，visible 函数返回 false 时隐藏字段。
动态 Props 联动
mergeProps 配合 effect 使用，当依赖字段变化时动态计算并合并到控件 props。
自定义控件（widget 注册）
在 AForm 上通过 widget 注册外部组件，items 中用字符串 key 引用。
函数控件（type 传组件）
type 直接传 Vue 组件，自动注入 form 实例，可读取任意字段实现联动。
动态列表
type: 'FormList' 管理动态增删行，每行字段路径自动带上行索引。
API
AForm Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
form | FormInstance | — | useForm() 返回的表单实例 |
initialValues | object | — | 表单初始值 |
layout | 'horizontal' | 'vertical' | 'inline' | 'horizontal' | 布局模式 |
labelCol | { span?: number } | { span: 6 } | 标签列宽（24 列制） |
wrapperCol | { span?: number } | { span: 18 } | 控件列宽 |
colon | boolean | true | 标签后是否显示冒号 |
requiredMark | boolean | true | 是否显示必填星号 |
validateTrigger | string | string[] | 'onChange' | 全局校验触发时机 |
name | string | — | 表单名称，用于字段 id 前缀 |
column | number | — | 多列布局列数（基于 24 列栅格） |
items | FormItemProps[] | — | 字段配置数组，替代手写 AFormItem |
widget | Record<string, Component> | — | 注册自定义控件，items 中用字符串 key 引用 |
AForm Events
| 事件 | 参数 | 说明 |
|---|---|---|
@finish | (values: Values) => void | 提交且校验通过时触发 |
@finish-failed | (info: { values, errorFields }) => void | 提交且校验失败时触发 |
@values-change | (changed: Partial<Values>, all: Values) => void | 任意字段值变化时触发 |
AFormItem Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
name | NamePath | — | 字段名，不传则仅作布局包装 |
label | string | — | 标签文字 |
rules | RuleItem[] | [] | 校验规则 |
required | boolean | — | 显示必填星号，同时自动注入 { required: true, message: '不能为空' } 规则 |
type | FormItemType | Component | — | 内置控件类型或自定义组件 |
props | Partial<对应组件 Props> | — | 透传给 type 指定组件的属性 |
initialValue | any | — | 字段级初始值 |
valuePropName | string | 'modelValue' | 控件受控属性名 |
getValueFromEvent | (...args) => any | — | 自定义从事件中取值 |
validateTrigger | string | string[] | 继承 Form | 覆盖字段级校验触发时机 |
normalize | (val, prev, all) => any | — | 值转换函数 |
effect | NamePath[] | — | 监听指定字段变化时触发重新渲染 |
visible | (form: FormInstance) => boolean | — | 返回 false 时隐藏该字段，配合 effect 实现联动显隐 |
mergeProps | (form: FormInstance) => Record<string, any> | — | 当 effect 依赖变化时调用，返回值与 props 合并后传给控件 |
help | string | — | 静态帮助文字 |
extra | string | — | 控件下方额外内容 |
noStyle | boolean | false | 不渲染任何包装样式 |
colon | boolean | 继承 Form | 覆盖冒号显示 |
span | number | 1 | 多列布局下占用的列数 |
FormItemType
type 属性支持以下内置控件：
| type 值 | 对应组件 | 备注 |
|---|---|---|
'Input' | AInput | — |
'InputNumber' | AInputNumber | — |
'Textarea' | ATextarea | — |
'Select' | ASelect | — |
'Switch' | ASwitch | valuePropName 自动设为 'modelValue' |
'Checkbox' | ACheckbox | valuePropName 自动设为 'modelValue' |
'CheckboxGroup' | ACheckboxGroup | — |
'RadioGroup' | ARadioGroup | — |
'Slider' | ASlider | — |
'Rate' | ARate | — |
'DatePicker' | ADatePicker | — |
'TimePicker' | ATimePicker | — |
'TimeRangePicker' | ATimePicker | 自动传入 range=true |
'Upload' | AUpload | valuePropName 自动设为 'fileList' |
'Cascader' | ACascader | — |
除内置类型外，type 还支持两种扩展方式：
方式一：widget 注册（字符串 key）
在 AForm 上通过 widget 注册自定义组件：
vue
<AForm :widget="{ MyPicker }" :items="[{ name: 'field', type: 'MyPicker' }]" />方式二：直接传 Vue 组件
type 可直接传入一个 Vue 组件，组件会自动收到 form、value（或对应 valuePropName）、onChange、onBlur、status 五个 prop：
vue
<script setup>
const BioInput = defineComponent({
props: { form: Object, value: String, onChange: Function, status: String },
setup(props) {
const other = computed(() => props.form?.getFieldValue("other"));
return () =>
h(AInput, {
modelValue: props.value,
"onUpdate:modelValue": props.onChange,
});
},
});
</script>Form.List 配置
在 items 中用 type: 'FormList' 声明动态列表，props 内支持：
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
items | FormItemProps[] | [] | 每行子字段模板 |
addText | string | '添加' | 表头新增按钮的 title |
FormInstance
| 方法 | 说明 |
|---|---|
getFieldValue(name) | 获取单个字段值 |
getFieldsValue(names?) | 获取多个字段值，不传则获取全部 |
setFieldValue(name, value) | 设置单个字段值 |
setFieldsValue(values) | 设置多个字段值 |
resetFields(names?) | 重置字段，恢复 initialValues |
validateFields(names?) | 触发校验，返回 Promise<Values> |
getFieldError(name) | 获取字段错误信息数组 |
getFieldsError(names?) | 获取多字段错误信息 |
isFieldTouched(name) | 字段是否被操作过 |
submit() | 手动触发提交 |
Rule
| 属性 | 类型 | 说明 |
|---|---|---|
required | boolean | 必填 |
message | string | 自定义错误提示 |
min | number | 字符串最小长度 / 数字最小值 |
max | number | 字符串最大长度 / 数字最大值 |
len | number | 字符串精确长度 |
pattern | RegExp | 正则校验 |
whitespace | boolean | 不允许纯空格 |
type | 'string' | 'number' | 'email' | 'url' | ... | 内置类型校验 |
enum | any[] | 枚举值校验 |
validator | (rule, value) => Promise<void> | 自定义异步校验函数 |
RuleItem = Rule | ((form: FormInstance) => Rule) — 支持函数形式以访问其他字段值。