# ProForm API

<cite>
**本文引用的文件**
- [packages/core/src/components/ProForm.vue](file://packages/core/src/components/ProForm.vue)
- [packages/core/src/components/ProTypeItem/ProTypeItem.vue](file://packages/core/src/components/ProTypeItem/ProTypeItem.vue)
- [src/views/ProForm.vue](file://src/views/ProForm.vue)
- [packages/core/types/index.d.ts](file://packages/core/types/index.d.ts)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件为 ProForm 组件的详细 API 参考文档，覆盖属性、事件、插槽与方法，并对表单配置（fields、model、rules 等）进行深入说明，解释交互行为（如提交、重置、字段变更）、验证机制以及与渲染扩展组件（ProTypeItem）的协作方式。

## 项目结构
ProForm 位于核心包中，采用 UI 适配器模式，通过 useUIAdapter 注入具体 UI 组件（Form、FormItem、Input、Button、Icon）。表单项支持自定义渲染（renderForm），并通过 ProTypeItem 动态生成复杂输入控件。

```mermaid
graph TB
PF["ProForm.vue<br/>核心表单组件"] --> PTI["ProTypeItem.vue<br/>动态渲染器"]
PF --> UIAF["useUIAdapter()<br/>UI 适配器"]
UIAF --> F["Form"]
UIAF --> FI["FormItem"]
UIAF --> INP["Input"]
UIAF --> BTN["Button"]
UIAF --> ICO["Icon"]
PF --> DEMO["示例页面<br/>src/views/ProForm.vue"]
```

图表来源
- [packages/core/src/components/ProForm.vue:146-173](file://packages/core/src/components/ProForm.vue#L146-L173)
- [packages/core/src/components/ProTypeItem/ProTypeItem.vue:1-132](file://packages/core/src/components/ProTypeItem/ProTypeItem.vue#L1-L132)
- [src/views/ProForm.vue:1-13](file://src/views/ProForm.vue#L1-L13)

章节来源
- [packages/core/src/components/ProForm.vue:1-144](file://packages/core/src/components/ProForm.vue#L1-L144)
- [packages/core/src/components/ProTypeItem/ProTypeItem.vue:1-132](file://packages/core/src/components/ProTypeItem/ProTypeItem.vue#L1-L132)
- [src/views/ProForm.vue:1-13](file://src/views/ProForm.vue#L1-L13)

## 核心组件
- ProForm：基于 UI 适配器渲染的表单容器，负责列布局、分组、标签位置与宽度、校验触发与提交流程。
- ProTypeItem：根据配置动态渲染输入组件或函数式渲染，支持格式化与包裹更新。

章节来源
- [packages/core/src/components/ProForm.vue:154-327](file://packages/core/src/components/ProForm.vue#L154-L327)
- [packages/core/src/components/ProTypeItem/ProTypeItem.vue:7-125](file://packages/core/src/components/ProTypeItem/ProTypeItem.vue#L7-L125)

## 架构总览
ProForm 将 columns 中的每一项映射为一个 FormItem；若未提供 renderForm，则使用默认 Input；若提供 renderForm，则交由 ProTypeItem 渲染。提交时先执行表单级校验，再发起请求，最后回调 complete。

```mermaid
sequenceDiagram
participant U as "用户"
participant PF as "ProForm"
participant VF as "底层 Form"
participant REQ as "customRequest"
U->>PF : 点击“提交”
PF->>VF : validate(fn)
VF-->>PF : 回调(valid)
alt 校验通过
PF->>REQ : 发起请求(datas=modelValue)
REQ-->>PF : 返回结果(res)
PF->>PF : 调用 submitForm.complete(res)
else 校验失败
PF-->>U : 停止提交
end
```

图表来源
- [packages/core/src/components/ProForm.vue:234-243](file://packages/core/src/components/ProForm.vue#L234-L243)
- [packages/core/src/components/ProForm.vue:151-151](file://packages/core/src/components/ProForm.vue#L151-L151)

## 详细组件分析

### 属性（Props）
- uiEdit: 是否启用编辑态 UI 框架（布尔）
- submitForm: 提交配置对象，包含 position、request、complete 等
- type: 表单类型，默认 "edit"，用于控制某些字段在不同场景下的可见性
- labelWidth: 标签宽度（数字）
- formLineNum: 每行显示的列数（数字）
- labelPosition: 标签位置，"left"|"top"（字符串）
- columns: 表单项配置数组，每项可包含 key、title、rules、renderForm、showForm、icons、formWidth 等
- modelValue: 表单数据模型（对象）

章节来源
- [packages/core/src/components/ProForm.vue:175-212](file://packages/core/src/components/ProForm.vue#L175-L212)

### 事件（Events）
- update:modelValue: 当任意字段值变化时触发，用于双向绑定
- uiChoose(item): UI 编辑框架选择某项时触发
- uiConfig(item): UI 编辑框架配置某项时触发
- itemClick(item, type): 点击某表单项时触发
- footer（插槽）: 自定义底部操作区（当 submitForm 存在且未隐藏时）

章节来源
- [packages/core/src/components/ProForm.vue:245-249](file://packages/core/src/components/ProForm.vue#L245-L249)
- [packages/core/src/components/ProForm.vue:124-140](file://packages/core/src/components/ProForm.vue#L124-L140)

### 插槽（Slots）
- default: 默认插槽，用于在表单内部插入内容（与 footer 不同）
- footer: 底部按钮区插槽，仅在存在 submitForm 且未隐藏时渲染

章节来源
- [packages/core/src/components/ProForm.vue:124-140](file://packages/core/src/components/ProForm.vue#L124-L140)

### 方法（Methods）
- validate(fn): 对整个表单进行校验
- validateField(prop, fn): 对指定字段进行校验
- reset(fn): 重置表单字段
- submit(): 触发表单校验并按配置发起请求
- change(item, value): 处理字段值变更并触发单项校验
- wapperInput(item, payload): 包裹更新并触发单项校验
- showColumns(item): 控制字段在当前 type 下的显示逻辑
- ruleChange(item): 规则预处理（如正则字符串转正则）
- getValue(value, item): 获取嵌套路径值
- propItem(item): 计算字段校验 prop（支持点号路径）

章节来源
- [packages/core/src/components/ProForm.vue:226-321](file://packages/core/src/components/ProForm.vue#L226-L321)

### 表单配置详解
- columns 数组中的每个元素代表一个表单项：
  - key: 字段键名，支持点号路径（如 a.b.c）
  - title: 标签名
  - rules 或 validate: 校验规则数组，支持 pattern 字符串自动转正则
  - renderForm: 可为函数或对象，用于自定义渲染
    - 函数形式：接收上下文并返回 VNode
    - 对象形式：包含 type、props、scopedSlots、style、on、format 等
  - showForm: 控制在特定 type 下是否显示，可为布尔、数组或函数
  - icons.form: 标签前图标
  - formWidth: 输入宽度（像素或百分比）
  - disabled/readonly: 控制输入状态
  - group: 分组标题，相同 group 的项会被归为一组
  - notShowForm/notShowSearch/notShowTable: 用于控制在不同视图下的显示
- modelValue: 与 columns.key 对应的表单数据对象，支持嵌套路径
- submitForm:
  - position: 按钮对齐方式
  - request: 提交地址
  - complete(res): 提交完成后的回调

章节来源
- [packages/core/src/components/ProForm.vue:251-266](file://packages/core/src/components/ProForm.vue#L251-L266)
- [packages/core/src/components/ProForm.vue:270-277](file://packages/core/src/components/ProForm.vue#L270-L277)
- [packages/core/src/components/ProForm.vue:282-290](file://packages/core/src/components/ProForm.vue#L282-L290)
- [src/views/ProForm.vue:22-28](file://src/views/ProForm.vue#L22-L28)
- [src/views/ProForm.vue:29-191](file://src/views/ProForm.vue#L29-L191)

### 交互行为与验证流程
- 字段变更：通过 change/wrapperInput 更新 modelValue，并对对应字段进行单项校验
- 校验规则：支持字符串正则自动转换；支持函数式显示条件（showForm）
- 提交流程：先 validate，再 customRequest，最后调用 complete

```mermaid
flowchart TD
S["开始"] --> C["change/wrapperInput 更新 modelValue"]
C --> P["propItem 计算校验 prop"]
P --> V{"propItem 存在？"}
V --> |是| NF["validateField(prop) 单项校验"]
V --> |否| E["结束"]
NF --> E
```

图表来源
- [packages/core/src/components/ProForm.vue:292-301](file://packages/core/src/components/ProForm.vue#L292-L301)
- [packages/core/src/components/ProForm.vue:303-311](file://packages/core/src/components/ProForm.vue#L303-L311)
- [packages/core/src/components/ProForm.vue:282-290](file://packages/core/src/components/ProForm.vue#L282-L290)

### 渲染扩展（ProTypeItem）
- 支持两种渲染方式：
  - 函数式：传入 h、input、modelValue 等上下文
  - 对象式：指定 type、props、scopedSlots、style、on、format 等
- format：可对输入值进行格式化，支持包裹更新（formatWapper）

```mermaid
classDiagram
class ProTypeItem {
+props item
+props outData
+props modelValue
+props renderItem
+evalUse(obj, innerValue)
+input(value)
+render()
}
```

图表来源
- [packages/core/src/components/ProTypeItem/ProTypeItem.vue:7-125](file://packages/core/src/components/ProTypeItem/ProTypeItem.vue#L7-L125)

章节来源
- [packages/core/src/components/ProTypeItem/ProTypeItem.vue:26-49](file://packages/core/src/components/ProTypeItem/ProTypeItem.vue#L26-L49)
- [packages/core/src/components/ProTypeItem/ProTypeItem.vue:51-124](file://packages/core/src/components/ProTypeItem/ProTypeItem.vue#L51-L124)

### 使用示例与参数说明
- v-model 绑定表单数据
- 通过 columns 配置字段、标签、校验规则与渲染
- 通过 submitForm 配置提交地址与完成回调
- 通过 footer 插槽自定义底部按钮区域

章节来源
- [src/views/ProForm.vue:5-11](file://src/views/ProForm.vue#L5-L11)
- [src/views/ProForm.vue:22-28](file://src/views/ProForm.vue#L22-L28)
- [src/views/ProForm.vue:29-191](file://src/views/ProForm.vue#L29-L191)

## 依赖关系分析
- ProForm 依赖 UI 适配器提供的 Form/FormItem/Input/Button/Icon
- ProForm 内部使用 ProTypeItem 进行复杂渲染
- 提交流程依赖 customRequest（封装请求）
- columns 的规则与显示逻辑由 ProForm 内部方法处理

```mermaid
graph LR
PF["ProForm"] --> PTI["ProTypeItem"]
PF --> UIA["useUIAdapter()"]
UIA --> F["Form"]
UIA --> FI["FormItem"]
UIA --> INP["Input"]
UIA --> BTN["Button"]
UIA --> ICO["Icon"]
PF --> REQ["customRequest"]
```

图表来源
- [packages/core/src/components/ProForm.vue:147-151](file://packages/core/src/components/ProForm.vue#L147-L151)
- [packages/core/src/components/ProForm.vue:159-173](file://packages/core/src/components/ProForm.vue#L159-L173)

章节来源
- [packages/core/src/components/ProForm.vue:147-151](file://packages/core/src/components/ProForm.vue#L147-L151)
- [packages/core/src/components/ProForm.vue:159-173](file://packages/core/src/components/ProForm.vue#L159-L173)

## 性能考量
- 字段变更后仅对当前字段进行单项校验，避免全量校验开销
- 使用 nextTick 确保 DOM 更新后再触发校验，减少抖动
- columns 按 group 分组渲染，提升布局效率
- renderForm 支持函数式与对象式，便于按需渲染复杂组件

## 故障排查指南
- 字段路径错误：当 key 为嵌套路径且父路径不存在时会输出提示日志，请检查 modelValue 结构与 key 路径
- 校验规则无效：确保 rules 中的 pattern 为字符串时会被自动转换为正则
- 自定义渲染无响应：确认 renderForm 的函数或对象形式正确，且已设置 v-model 与 onUpdate:modelValue

章节来源
- [packages/core/src/components/ProForm.vue:282-289](file://packages/core/src/components/ProForm.vue#L282-L289)
- [packages/core/src/components/ProForm.vue:270-277](file://packages/core/src/components/ProForm.vue#L270-L277)
- [packages/core/src/components/ProTypeItem/ProTypeItem.vue:99-121](file://packages/core/src/components/ProTypeItem/ProTypeItem.vue#L99-L121)

## 结论
ProForm 提供了灵活的表单配置能力与强大的渲染扩展机制，结合 UI 适配器可在不同 UI 框架间无缝切换。通过 columns 与 renderForm，开发者可以快速构建复杂的表单界面；通过 submitForm 与内置校验方法，能够轻松实现表单提交与验证流程。

## 附录
- 类型导出：ProForm 在核心类型声明中导出为组件类型，便于在 TypeScript 项目中使用

章节来源
- [packages/core/types/index.d.ts:103-103](file://packages/core/types/index.d.ts#L103-L103)