# CRUD 应用构建

<cite>
**本文引用的文件**
- [README.md](file://README.md)
- [ProTable.vue](file://packages/components/ProTable.vue)
- [ProForm.vue](file://packages/components/ProForm.vue)
- [ProSearch.vue](file://packages/components/ProSearch.vue)
- [ProTypeItem.vue](file://packages/components/ProTypeItem/ProTypeItem.vue)
- [request.js](file://packages/libs/request.js)
- [ProTable 示例视图](file://src/views/ProTable.vue)
- [ProForm 示例视图](file://src/views/ProForm.vue)
- [ProSearch 示例视图](file://src/views/ProSearch.vue)
- [EditTable 示例视图](file://src/views/EditTable.vue)
- [ProTable 类型定义](file://types/ProTable.d.ts)
- [路由配置](file://src/router/index.js)
- [Home 示例视图](file://src/views/Home.vue)
</cite>

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

## 简介
本文件面向使用 Pro-IVIEW V3 构建 CRUD 应用的开发者，系统性讲解如何基于 ProTable、ProForm、ProSearch 等核心组件搭建完整的增删改查功能，覆盖数据加载、表格展示、表单编辑、搜索过滤、分页处理、批量操作与行内编辑等关键场景，并提供可落地的配置要点、事件处理与数据绑定方式，以及性能优化与最佳实践。

## 项目结构
仓库采用多包/多视图结构，核心组件位于 packages/components，示例页面位于 src/views，类型定义位于 types，路由配置位于 src/router。

```mermaid
graph TB
subgraph "示例页面"
Home["Home.vue"]
ProTableView["ProTable.vue"]
ProFormView["ProForm.vue"]
ProSearchView["ProSearch.vue"]
EditTableView["EditTable.vue"]
end
subgraph "核心组件"
PT["ProTable.vue"]
PF["ProForm.vue"]
PS["ProSearch.vue"]
PTI["ProTypeItem.vue"]
REQ["request.js"]
end
Home --> PT
ProTableView --> PT
ProFormView --> PF
ProSearchView --> PS
EditTableView --> PT
PT --> PS
PT --> PF
PT --> REQ
PF --> REQ
PS --> PTI
PT --> PTI
```

图表来源
- [ProTable.vue](file://packages/components/ProTable.vue)
- [ProForm.vue](file://packages/components/ProForm.vue)
- [ProSearch.vue](file://packages/components/ProSearch.vue)
- [ProTypeItem.vue](file://packages/components/ProTypeItem/ProTypeItem.vue)
- [request.js](file://packages/libs/request.js)
- [Home.vue](file://src/views/Home.vue)
- [ProTable.vue](file://src/views/ProTable.vue)
- [ProForm.vue](file://src/views/ProForm.vue)
- [ProSearch.vue](file://src/views/ProSearch.vue)
- [EditTable.vue](file://src/views/EditTable.vue)

章节来源
- [README.md](file://README.md)
- [路由配置](file://src/router/index.js)

## 核心组件
- ProTable：提供工具栏、搜索、表格、分页、弹窗表单、批量操作与行内编辑能力，内置远程数据请求与分页映射。
- ProForm：支持栅格布局、动态渲染、表单校验、提交与重置。
- ProSearch：支持栅格布局、动态渲染、展开收起、统一搜索与重置。
- ProTypeItem：统一渲染入口，支持字符串/函数/JSX 三种渲染方式，内置格式化与事件透传。
- request：统一请求适配器，支持字符串/对象/函数三种请求形式，自动拼装 GET/POST 参数与替换模板变量。

章节来源
- [ProTable.vue](file://packages/components/ProTable.vue)
- [ProForm.vue](file://packages/components/ProForm.vue)
- [ProSearch.vue](file://packages/components/ProSearch.vue)
- [ProTypeItem.vue](file://packages/components/ProTypeItem/ProTypeItem.vue)
- [request.js](file://packages/libs/request.js)
- [ProTable 类型定义](file://types/ProTable.d.ts)

## 架构总览
ProTable 作为中枢，串联搜索、表格、分页与表单弹窗；ProForm/ProSearch 通过 ProTypeItem 渲染具体控件；request 统一封装请求逻辑；示例视图演示典型配置与事件绑定。

```mermaid
sequenceDiagram
participant U as "用户"
participant PT as "ProTable"
participant PS as "ProSearch"
participant PF as "ProForm"
participant REQ as "request"
participant API as "后端接口"
U->>PT : 触发搜索/分页/新建/编辑/删除
PT->>PS : 同步搜索条件
PT->>REQ : 组装分页与查询参数
REQ->>API : 发送请求
API-->>REQ : 返回数据
REQ-->>PT : 解析 dataPath/totalPath
PT-->>U : 展示表格/分页/提示
U->>PT : 弹窗新建/编辑
PT->>PF : 打开表单并传入初始值
PF->>REQ : 提交表单
REQ->>API : 发送请求
API-->>REQ : 返回结果
REQ-->>PF : 回调 complete
PF-->>PT : 完成回调
PT->>PT : 刷新列表/关闭弹窗
```

图表来源
- [ProTable.vue](file://packages/components/ProTable.vue)
- [ProForm.vue](file://packages/components/ProForm.vue)
- [ProSearch.vue](file://packages/components/ProSearch.vue)
- [request.js](file://packages/libs/request.js)

## 详细组件分析

### ProTable：表格中枢
- 功能要点
  - 工具栏：新建、刷新、全屏、列设置等动作集合，支持自定义渲染。
  - 搜索：与 ProSearch 协作，支持展开收起、统一搜索与重置。
  - 表格：列过滤、渲染扩展、操作列、行点击事件。
  - 分页：双向绑定 current/pageSize，支持页大小变更与页码切换。
  - 表单弹窗：新建/编辑统一弹窗，支持表单列配置、校验与提交。
  - 请求适配：支持字符串/对象/函数三种请求形式，自动注入分页与查询参数，解析 dataPath/totalPath。
- 关键配置
  - columns：列定义，支持 renderTable/renderSearch/renderForm/action 等扩展点。
  - request/map/format：请求地址、分页字段映射、数据路径映射、成功条件与消息字段。
  - hide/search/form/table/page：各模块显隐与配置。
  - toolBarActions：工具栏动作集合或自定义渲染。
  - submitForm：新建/编辑提交配置。
- 事件与方法
  - 事件：search/searchReset/fetchFinish/pageClick 等。
  - 方法：search()/fetch()/fetchCurrent()/pageSizeChange()/getDatas()/finish()/getSelection() 等。
- 复杂场景
  - 行内编辑：通过列配置的 renderTableEdit 实现，支持编辑态/正常态切换、校验与快捷键。
  - 批量操作：通过选择列与工具栏按钮组合，支持复制/删除/刷新/恢复等。
  - 操作列：actions 支持 delete/new/edit/action 等类型，支持自定义渲染与条件显示。

```mermaid
classDiagram
class ProTable {
+props : columns,request,map,format,hide,search,form,toolBarActions,submitForm
+data : innerValue,showTableColumns,resData,formDialog,loading,total,page
+methods : search(),fetch(),pageSizeChange(),tableAction(),finish(),getDatas()
+events : search,searchReset,fetchFinish,pageClick
}
class ProSearch {
+props : columns,modelValue,searchLineNum,position
+methods : search(),reset(),upDownHandle()
}
class ProForm {
+props : columns,modelValue,submitForm,labelPosition,formLineNum
+methods : submit(),reset(),validate(),validateField()
}
class Request {
+call : (request,method,datas,headers) => Promise
}
ProTable --> ProSearch : "使用"
ProTable --> ProForm : "弹窗表单"
ProTable --> Request : "请求适配"
ProForm --> Request : "提交表单"
```

图表来源
- [ProTable.vue](file://packages/components/ProTable.vue)
- [ProSearch.vue](file://packages/components/ProSearch.vue)
- [ProForm.vue](file://packages/components/ProForm.vue)
- [request.js](file://packages/libs/request.js)

章节来源
- [ProTable.vue](file://packages/components/ProTable.vue)
- [ProTable 示例视图](file://src/views/ProTable.vue)
- [Home 示例视图](file://src/views/Home.vue)
- [ProTable 类型定义](file://types/ProTable.d.ts)

### ProForm：表单渲染与提交
- 功能要点
  - 栅格布局：formLineNum 控制每行列数，支持百分比/像素宽度。
  - 动态渲染：通过 renderItem 支持字符串/函数/JSX 三类渲染。
  - 校验：基于 async-validator，支持规则转换与单项校验。
  - 提交：统一走 request 适配器，支持 complete 回调。
- 关键配置
  - columns：每个字段的 title/key/rules/renderForm/showForm 等。
  - submitForm：请求地址、方法、位置与完成回调。
  - labelPosition/labelWidth/formLineNum：布局与样式。
- 事件与方法
  - 事件：itemClick/uiConfig 等。
  - 方法：submit()/reset()/validate()/validateField()。

```mermaid
flowchart TD
Start(["开始"]) --> Validate["表单校验"]
Validate --> Valid{"校验通过?"}
Valid --> |否| ShowError["显示错误"]
Valid --> |是| SubmitReq["调用 request 提交"]
SubmitReq --> Complete["执行 complete 回调"]
Complete --> End(["结束"])
ShowError --> End
```

图表来源
- [ProForm.vue](file://packages/components/ProForm.vue)
- [request.js](file://packages/libs/request.js)

章节来源
- [ProForm.vue](file://packages/components/ProForm.vue)
- [ProForm 示例视图](file://src/views/ProForm.vue)

### ProSearch：搜索与筛选
- 功能要点
  - 栅格布局：searchLineNum 控制每行列数，支持展开收起。
  - 动态渲染：通过 renderItem 支持多种控件。
  - 统一事件：search/reset，支持 beforeSearch/beforeReset 钩子。
- 关键配置
  - columns：每个字段的 title/key/renderSearch。
  - position/searchLineNum：布局与显示策略。
- 事件与方法
  - 事件：search/reset。
  - 方法：search()/reset()/upDownHandle()。

```mermaid
flowchart TD
S0(["初始化"]) --> S1["渲染搜索项"]
S1 --> S2["展开/收起控制"]
S2 --> S3["用户输入"]
S3 --> S4{"点击搜索?"}
S4 --> |是| S5["触发 search 事件"]
S4 --> |否| S6["等待输入"]
S5 --> S7["触发 reset 事件"]
S7 --> S1
```

图表来源
- [ProSearch.vue](file://packages/components/ProSearch.vue)

章节来源
- [ProSearch.vue](file://packages/components/ProSearch.vue)
- [ProSearch 示例视图](file://src/views/ProSearch.vue)

### ProTypeItem：统一渲染入口
- 功能要点
  - 支持字符串/函数/JSX 三种渲染方式。
  - 内置格式化 format 与表达式 useExp/text。
  - 自动透传 v-model 与事件，兼容 HTML 标签与组件。
- 关键配置
  - renderItem：type/props/on/scopedSlots/style/text/useExp/format。
  - modelValue/outData：上下文数据。
- 事件与方法
  - update:modelValue/wapperInput：用于双向绑定与包装更新。

章节来源
- [ProTypeItem.vue](file://packages/components/ProTypeItem/ProTypeItem.vue)

### request：请求适配器
- 功能要点
  - 支持字符串/对象/函数三种请求形式。
  - 自动拼装 GET/POST 参数，支持模板变量替换。
  - 自动注入 Authorization 头部（从查询参数读取）。
- 关键配置
  - request/method/datas/headers/keys：请求参数。
- 使用场景
  - ProTable/ProForm 统一使用该适配器发起请求。

章节来源
- [request.js](file://packages/libs/request.js)

### EditTable：行内编辑与批量操作
- 功能要点
  - 行内编辑：renderTableEdit.normal/edit，支持焦点跳转、快捷键、校验与错误提示。
  - 批量操作：选择列 + 工具栏按钮，支持复制/删除/刷新/恢复。
  - 新增/删除/刷新：支持默认值、方向控制、分页联动。
  - 保存：统一 save 回调，支持新旧数据对比与批量提交。
- 关键配置
  - columns：renderTableEdit.normal/renderTableEdit.edit/rules/addDefaultValue。
  - controls/notShowLeftControls：左侧控制列与按钮。
  - page/autoFetch：分页与自动拉取。
  - save：保存回调。
- 事件与方法
  - validateAll()/addRow()/addMultiple()/deleteRow()/refreshRow()/saveData() 等。

```mermaid
sequenceDiagram
participant U as "用户"
participant ET as "EditTable"
participant T as "表格"
participant VAL as "校验器"
participant SAVE as "save 回调"
U->>ET : 点击单元格进入编辑态
ET->>T : 渲染编辑组件
T->>VAL : 单项校验
VAL-->>T : 校验结果
U->>ET : 点击保存
ET->>SAVE : 传入新旧数据
SAVE-->>ET : 返回更新后的数据
ET-->>U : 刷新表格/清空状态
```

图表来源
- [EditTable 示例视图](file://src/views/EditTable.vue)
- [ProTableEdit.vue](file://packages/components/ProTableEdit.vue)

章节来源
- [EditTable 示例视图](file://src/views/EditTable.vue)
- [ProTableEdit.vue](file://packages/components/ProTableEdit.vue)

## 依赖关系分析
- 组件耦合
  - ProTable 依赖 ProSearch/ProForm/ProTypeItem/UIEditFrame/screenfull。
  - ProForm/ProSearch 依赖 ProTypeItem。
  - request 作为通用适配器被多个组件共享。
- 外部依赖
  - axios/lodash-es/dayjs/mousetrap/screenfull 等。
- 路由与示例
  - 路由注册了各示例页面，便于快速验证组件能力。

```mermaid
graph LR
PT["ProTable.vue"] --> PS["ProSearch.vue"]
PT --> PF["ProForm.vue"]
PT --> REQ["request.js"]
PF --> REQ
PS --> PTI["ProTypeItem.vue"]
PT --> PTI
Home["Home.vue"] --> PT
ProTableView["ProTable.vue"] --> PT
ProFormView["ProForm.vue"] --> PF
ProSearchView["ProSearch.vue"] --> PS
EditTableView["EditTable.vue"] --> PT
```

图表来源
- [ProTable.vue](file://packages/components/ProTable.vue)
- [ProForm.vue](file://packages/components/ProForm.vue)
- [ProSearch.vue](file://packages/components/ProSearch.vue)
- [ProTypeItem.vue](file://packages/components/ProTypeItem/ProTypeItem.vue)
- [request.js](file://packages/libs/request.js)
- [Home.vue](file://src/views/Home.vue)
- [ProTable.vue](file://src/views/ProTable.vue)
- [ProForm.vue](file://src/views/ProForm.vue)
- [ProSearch.vue](file://src/views/ProSearch.vue)
- [EditTable.vue](file://src/views/EditTable.vue)

章节来源
- [路由配置](file://src/router/index.js)

## 性能考虑
- 渲染优化
  - 使用 columnFilter 仅渲染可见列，减少 DOM 数量。
  - ProTypeItem 支持表达式与条件渲染，避免不必要的组件实例化。
- 请求优化
  - request 自动合并参数，避免冗余字段；支持 keys 仅取指定字段。
  - ProTable 在分页切换时仅更新必要字段，避免全量重绘。
- 交互优化
  - EditTable 的焦点跳转与快捷键减少键盘操作成本。
  - 全屏模式通过 screenfull 管理，避免重复计算与样式抖动。
- 建议
  - 大数据量场景启用虚拟滚动（如可用）。
  - 合理设置分页大小，避免一次性加载过多数据。
  - 对高频输入控件使用防抖/节流（可通过 ProTypeItem 的 format/wrapper 实现）。

## 故障排查指南
- 请求失败
  - 检查 request 配置（字符串/对象/函数），确认 URL/方法/参数是否正确。
  - 检查 headers 与 Authorization 注入是否生效。
- 分页异常
  - 确认 map.current/pageSize/dataPath/totalPath 是否与后端一致。
  - 若后端需要特殊分页格式，使用 format.formatCurrent 自定义转换。
- 表单校验不生效
  - 确认 rules 中的 pattern 是否为正则对象（组件内部会转换为 RegExp）。
  - 使用 validateField 单项校验定位问题字段。
- 搜索重置无效
  - 确认 beforeReset 钩子是否正确调用回调。
- 行内编辑冲突
  - 检查 renderTableEdit.edit 的 canEdit 与 render 返回值是否正确。
  - 确认 save 回调返回的数据结构与 map.savePath 匹配。

章节来源
- [ProTable.vue](file://packages/components/ProTable.vue)
- [ProForm.vue](file://packages/components/ProForm.vue)
- [ProSearch.vue](file://packages/components/ProSearch.vue)
- [request.js](file://packages/libs/request.js)

## 结论
Pro-IVIEW V3 的 ProTable/ProForm/ProSearch 体系提供了完整的 CRUD 能力：从数据加载、搜索过滤、表格展示到表单编辑与分页处理，均以统一的配置与事件模型实现。结合 ProTypeItem 的灵活渲染与 request 的统一适配，开发者可以快速搭建复杂业务场景。配合 EditTable 的行内编辑与批量操作，能够覆盖大多数企业级 CRUD 需求。建议在实际项目中根据业务定制列配置、校验规则与请求格式，同时关注性能与用户体验细节。

## 附录
- 快速上手清单
  - 配置 columns 与 request/map/format。
  - 在 ProTable 上绑定 v-model 绑定表格数据。
  - 通过 actions 定义操作列，支持 delete/new/edit/action。
  - 使用 ProSearch 定义查询条件，绑定 v-model。
  - 使用 ProForm 定义表单字段，配置 submitForm。
  - 如需行内编辑，参考 EditTable 的配置与 save 回调。
- 参考示例
  - Home.vue：综合演示 ProTable 的常用配置与事件。
  - ProTable.vue/ProForm.vue/ProSearch.vue：组件独立示例。
  - EditTable.vue：行内编辑与批量操作示例。

章节来源
- [Home 示例视图](file://src/views/Home.vue)
- [ProTable 示例视图](file://src/views/ProTable.vue)
- [ProForm 示例视图](file://src/views/ProForm.vue)
- [ProSearch 示例视图](file://src/views/ProSearch.vue)
- [EditTable 示例视图](file://src/views/EditTable.vue)