---
title: ProForm 表单组件
---

# ProForm 表单组件

ProForm 是基于 ProField 的高级表单组件，支持自动布局、验证、收起/展开等功能。

## 说明

ProForm 通过 `columns` 配置自动生成表单，每个字段配置对应一个 ProField 组件。支持响应式布局、表单验证、只读模式、收起/展开等高级功能。

## API

### Props

| 参数                          | 说明                                                            | 类型               | 默认值      |
| ----------------------------- | --------------------------------------------------------------- | ------------------ | ----------- |
| columns                       | 表单列配置                                                      | `Array`            | `[]`        |
| initialValues                 | 表单初始值                                                      | `Object`           | `{}`        |
| rules                         | 表单验证规则                                                    | `Object`           | `{}`        |
| labelWidth                    | 标签宽度                                                        | `String \| Number` | `'100px'`   |
| labelPosition                 | 标签位置                                                        | `String`           | `'right'`   |
| inline                        | 行内表单                                                        | `Boolean`          | `false`     |
| size                          | 尺寸                                                            | `String`           | `'default'` |
| disabled                      | 是否禁用                                                        | `Boolean`          | `false`     |
| validateOnRuleChange          | 是否在 rules 属性改变后立即触发一次验证                         | `Boolean`          | `true`      |
| hideRequiredAsterisk          | 是否隐藏必填字段的标签旁边的红色星号                            | `Boolean`          | `false`     |
| enableReadonlyOverflowTooltip | 是否启用只读模式文本溢出检测和 tooltip 功能                     | `Boolean`          | `false`     |
| requireAsteriskPosition       | 必填标识的位置                                                  | `String`           | `'left'`    |
| gutter                        | 栅格间距                                                        | `Number`           | `24`        |
| cols                          | 每行列数，支持数字或响应式对象 `{ xs: 1, sm: 2, md: 3, lg: 4 }` | `Number \| Object` | `3`         |
| formProps                     | 表单属性                                                        | `Object`           | `{}`        |
| collapsible                   | 是否支持收起/展开                                               | `Boolean`          | `false`     |
| defaultCollapsed              | 默认是否收起                                                    | `Boolean`          | `true`      |
| loading                       | 加载状态                                                        | `Boolean`          | `false`     |

### Column 配置

| 参数              | 说明                    | 类型            | 默认值   |
| ----------------- | ----------------------- | --------------- | -------- |
| name              | 字段名                  | `String`        | -        |
| label             | 标签文本                | `String`        | -        |
| valueType         | 字段类型（同 ProField） | `String`        | `'text'` |
| mode              | 模式类型（edit/read）   | `String`        | `'edit'` |
| required          | 是否必填                | `Boolean`       | `false`  |
| rules             | 验证规则                | `Array`         | -        |
| fieldProps        | 字段属性                | `Object`        | `{}`     |
| formItemProps     | 表单项属性              | `Object`        | `{}`     |
| showWhenCollapsed | 收起时是否显示          | `Boolean`       | `true`   |
| valueEnum         | 映射值的类型            | `Object \| Map` | -        |
| slots             | 插槽配置                | `Object`        | -        |
| component         | 自定义组件              | `Component`     | -        |
| componentProps    | 自定义组件属性          | `Object`        | `{}`     |

### Events

| 事件名       | 说明                   | 参数                                                |
| ------------ | ---------------------- | --------------------------------------------------- |
| validate     | 任一表单项被校验后触发 | `(prop: string, isValid: boolean, message: string)` |
| submit       | 表单提交时触发         | `(values: object)`                                  |
| reset        | 表单重置时触发         | -                                                   |
| valuesChange | 表单值变化时触发       | `(values: object)`                                  |

### Slots

| 插槽名         | 说明               | 参数                                               |
| -------------- | ------------------ | -------------------------------------------------- |
| actions        | 操作按钮区域       | `{ form: FormMethods }`                            |
| title          | 表单标题           | -                                                  |
| `{name}`       | 字段自定义内容     | `{ item: Column, value: any, onUpdate: Function }` |
| `{name}-label` | 字段标签自定义     | `{ item: Column }`                                 |
| `{name}-error` | 字段错误信息自定义 | `{ error: string, item: Column }`                  |

### FormMethods

通过 `actions` 插槽可以访问表单方法：

| 方法          | 说明                   | 参数                                               |
| ------------- | ---------------------- | -------------------------------------------------- |
| submit        | 提交表单（会触发验证） | -                                                  |
| reset         | 重置表单               | -                                                  |
| validate      | 验证表单               | `(props?: string \| string[]) => Promise<boolean>` |
| clearValidate | 清除验证               | `(props?: string \| string[]) => void`             |
| getValues     | 获取表单值             | -                                                  |
| setValues     | 设置表单值             | `(values: object) => void`                         |

## 示例

:::example

pro-form/basic

:::

## ProFormGroup 表单组

ProFormGroup 是 ProForm 的扩展，支持表单分组功能。

:::example

pro-form/group

:::

## 多产品多线路表单配置示例

这是一个高级示例，展示了如何使用 ProForm 实现多产品、多线路的复杂表单配置场景。支持为每个产品 × 线路组合生成独立的表单，并实现性能优化（只渲染可见表单）。

:::example

pro-form/product-route

:::