# ProTable API

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

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

## 简介
本文件为 ProTable 组件的详细 API 参考文档，覆盖属性、事件、插槽与方法，重点说明表格配置（如 columns、data、pagination）与交互行为（如搜索、分页、行设置、表单弹窗等）。文档基于仓库中的实现与类型声明进行整理，帮助开发者快速理解与正确使用该组件。

## 项目结构
ProTable 组件位于 packages/components 与 packages/core/src/components 两个目录下，功能一致但构建产物不同；类型声明位于 types 目录；示例位于 src/views 中。

```mermaid
graph TB
subgraph "组件源码"
A["packages/components/ProTable.vue"]
B["packages/core/src/components/ProTable.vue"]
C["packages/components/ProTable/RowSetting.vue"]
D["packages/components/ProTable/ToolBarActions.vue"]
end
subgraph "类型定义"
T["types/ProTable.d.ts"]
end
subgraph "示例"
E["src/views/ProTable.vue"]
end
A --> C
A --> D
B --> C
B --> D
T --> A
T --> B
E --> A
```

**图表来源**
- [packages/components/ProTable.vue:1-152](file://packages/components/ProTable.vue#L1-L152)
- [packages/core/src/components/ProTable.vue:1-152](file://packages/core/src/components/ProTable.vue#L1-L152)
- [packages/components/ProTable/RowSetting.vue:1-79](file://packages/components/ProTable/RowSetting.vue#L1-L79)
- [packages/components/ProTable/ToolBarActions.vue:1-58](file://packages/components/ProTable/ToolBarActions.vue#L1-L58)
- [types/ProTable.d.ts:1-58](file://types/ProTable.d.ts#L1-L58)
- [src/views/ProTable.vue:1-306](file://src/views/ProTable.vue#L1-L306)

**章节来源**
- [packages/components/ProTable.vue:1-152](file://packages/components/ProTable.vue#L1-L152)
- [packages/core/src/components/ProTable.vue:1-152](file://packages/core/src/components/ProTable.vue#L1-L152)
- [types/ProTable.d.ts:1-58](file://types/ProTable.d.ts#L1-L58)
- [src/views/ProTable.vue:1-306](file://src/views/ProTable.vue#L1-L306)

## 核心组件
- 组件名称：ProTable
- 类型：Vue 单文件组件（SFC），使用 JSX 渲染
- 主要职责：
  - 提供带搜索、分页、工具栏、行设置、表单弹窗的表格能力
  - 支持远程数据请求与本地数据绑定
  - 支持列级渲染（search/table/form）、动作列（新增/编辑/删除/自定义）

**章节来源**
- [packages/components/ProTable.vue:167-266](file://packages/components/ProTable.vue#L167-L266)
- [packages/core/src/components/ProTable.vue:167-266](file://packages/core/src/components/ProTable.vue#L167-L266)
- [types/ProTable.d.ts:3-58](file://types/ProTable.d.ts#L3-L58)

## 架构概览
ProTable 内部由多个子组件协作完成功能模块化：
- UI 编辑框架：UIEditFrame（用于可视化编辑）
- 搜索区：ProSearch（基于列配置生成搜索控件）
- 表格主体：iView Table（通过 columns/data/border 等属性驱动）
- 分页：iView Page（支持页码与页大小变更）
- 工具栏：ProTypeItem + RowSetting（行设置、刷新、全屏、新增）
- 表单弹窗：ProForm（基于列配置生成表单项）

```mermaid
graph TB
PT["ProTable.vue"]
RS["ProSearch.vue"]
TF["Table(iView)"]
PG["Page(iView)"]
FS["FormDialog(Modal)"]
PF["ProForm.vue"]
RS --> PT
PT --> TF
PT --> PG
PT --> FS
FS --> PF
```

**图表来源**
- [packages/components/ProTable.vue:17-147](file://packages/components/ProTable.vue#L17-L147)
- [packages/core/src/components/ProTable.vue:17-147](file://packages/core/src/components/ProTable.vue#L17-L147)

**章节来源**
- [packages/components/ProTable.vue:1-152](file://packages/components/ProTable.vue#L1-L152)
- [packages/core/src/components/ProTable.vue:1-152](file://packages/core/src/components/ProTable.vue#L1-L152)

## 详细组件分析

### 属性（Props）
- columns: 列配置数组，支持渲染类型（renderSearch/renderTable/renderForm）、动作列（actions）、固定/对齐/宽度等
- hide: 控制区域隐藏
  - hide.toolBar: 是否隐藏工具栏
  - hide.search: 是否隐藏搜索区
  - hide.page: 是否隐藏分页
- map: 请求结果映射
  - map.dataPath: 数据数组字段路径
  - map.totalPath: 总条数字段路径
- request: 请求配置（字符串/函数/对象），用于获取表格数据
- submitForm: 新增/编辑提交配置（字符串/函数/对象）
- search: ProSearch 组件传参（如初始值、布局等）
- form: ProForm 组件传参（如弹窗宽度、表单项布局等）
- table: iView Table 组件传参（如边框、高度等）
- 其他常用属性
  - pageSize: 默认每页条数
  - toolBarActions: 工具栏按钮集合（可自定义渲染）
  - attrs: 透传到各子组件的属性对象
  - title: 标题文本
  - method/headers: 请求方法与请求头
  - autoFetch: 是否自动发起首次请求
  - format: 分页参数格式化（支持函数或表达式字符串）
  - modelValue: 外部绑定的数据（双向绑定）
  - storage: 行设置持久化键名
  - uiEdit: 是否启用 UI 编辑模式

**章节来源**
- [packages/components/ProTable.vue:195-266](file://packages/components/ProTable.vue#L195-L266)
- [packages/core/src/components/ProTable.vue:195-266](file://packages/core/src/components/ProTable.vue#L195-L266)
- [types/ProTable.d.ts:3-58](file://types/ProTable.d.ts#L3-L58)

### 事件（Events）
- pageClick(e): 分页容器点击事件
- uiConfig(options): UI 编辑配置事件
- search({ form, page, table }): 搜索触发后的回调，携带当前表单值、页码信息与表格数据
- searchReset({ form, page, table }): 搜索重置后的回调
- formReset(): 表单重置后的回调
- fetchFinish(data): 请求完成后回调，传入解析后的数据

注意：上述事件由组件内部 emitActions 与 fetchFinish 触发，参数结构见“章节来源”。

**章节来源**
- [packages/components/ProTable.vue:457-462](file://packages/components/ProTable.vue#L457-L462)
- [packages/components/ProTable.vue:655-661](file://packages/components/ProTable.vue#L655-L661)
- [packages/components/ProTable.vue:721-722](file://packages/components/ProTable.vue#L721-L722)
- [packages/core/src/components/ProTable.vue:457-462](file://packages/core/src/components/ProTable.vue#L457-L462)
- [packages/core/src/components/ProTable.vue:655-661](file://packages/core/src/components/ProTable.vue#L655-L661)
- [packages/core/src/components/ProTable.vue:721-722](file://packages/core/src/components/ProTable.vue#L721-L722)

### 插槽（Slots）
- header: 工具栏区域插槽，默认展示标题与工具按钮组
- title: 自定义标题插槽（优先级高于默认标题）
- tableTip: 表格上方提示信息插槽
- 注意：header 插槽内仍受 hide.toolBar 控制

**章节来源**
- [packages/components/ProTable.vue:37-72](file://packages/components/ProTable.vue#L37-L72)
- [packages/core/src/components/ProTable.vue:37-72](file://packages/core/src/components/ProTable.vue#L37-L72)

### 方法（Methods）
以下方法可通过组件实例访问（例如通过 ref 调用）：

- search(current?: number): 执行搜索并跳转至指定页（默认第一页）
- fetchCurrent(current?: number): 设置页码并发起请求，返回 Promise
- pageSizeChange(pageSize: number): 修改页大小并按需重新请求
- setTotal(value: number): 设置总条目数（用于外部控制）
- getTotal(): 获取总条目数
- getDatas(): 返回当前上下文数据（search/form/page/table/resData/dialog 等）
- getSelection(): 获取表格选中行（委托给 iView Table 的 getSelection）
- finish(): 关闭表单弹窗、重置表单并刷新列表
- success(res): 成功回调（根据 map.message 或默认文案提示）
- error(res): 错误回调（根据 map.message 或默认文案提示）
- submitLoading(): 表单提交加载动画切换（用于防抖视觉反馈）
- submit(): 校验表单并提交（区分新增/编辑/查看）
- fetch(fn?, options?): 发起请求（支持格式化分页参数、映射数据与总数）

调用示例（参考示例页面）：
- 通过 ref 访问组件实例并调用 search() 执行搜索
- 通过 ref 访问组件实例并调用 getSelection() 获取选中行

**章节来源**
- [packages/components/ProTable.vue:605-624](file://packages/components/ProTable.vue#L605-L624)
- [packages/components/ProTable.vue:665-741](file://packages/components/ProTable.vue#L665-L741)
- [packages/components/ProTable.vue:753-830](file://packages/components/ProTable.vue#L753-L830)
- [packages/core/src/components/ProTable.vue:605-624](file://packages/core/src/components/ProTable.vue#L605-L624)
- [packages/core/src/components/ProTable.vue:665-741](file://packages/core/src/components/ProTable.vue#L665-L741)
- [packages/core/src/components/ProTable.vue:753-830](file://packages/core/src/components/ProTable.vue#L753-L830)
- [src/views/ProTable.vue:293-301](file://src/views/ProTable.vue#L293-L301)

### 列配置（columns）详解
- 基础字段：title/key/width/align/fixed/children 等
- 渲染相关：
  - renderSearch: 搜索区渲染（支持函数/对象）
  - renderTable: 表格单元格渲染（支持函数/对象）
  - renderForm: 表单弹窗渲染（支持函数/对象）
- 动作列：当 key 为 "action" 时，通过 actions 数组定义操作按钮（新增/编辑/删除/自定义）
- 显示控制：notShowSearch/notShowTable/notShowForm/notShowRowSetting 等
- 其他：tooltip、resizable、rules 等

**章节来源**
- [packages/components/ProTable.vue:490-554](file://packages/components/ProTable.vue#L490-L554)
- [packages/core/src/components/ProTable.vue:490-554](file://packages/core/src/components/ProTable.vue#L490-L554)

### 工具栏与行设置
- 工具栏按钮：new/refresh/fullscreen/rowSetting（可自定义渲染）
- 行设置：支持勾选/拖拽调整列显示顺序，支持重置与本地存储

```mermaid
sequenceDiagram
participant U as "用户"
participant PT as "ProTable"
participant RS as "RowSetting"
participant TF as "Table"
U->>PT : 点击行设置
PT->>RS : 打开设置面板
U->>RS : 勾选/取消/拖拽
RS-->>PT : input/change 事件列顺序与可见性
PT->>TF : 更新列渲染columnFilter
TF-->>U : 刷新表格显示
```

**图表来源**
- [packages/components/ProTable/RowSetting.vue:149-167](file://packages/components/ProTable/RowSetting.vue#L149-L167)
- [packages/components/ProTable.vue:351-366](file://packages/components/ProTable.vue#L351-L366)
- [packages/core/src/components/ProTable.vue:351-366](file://packages/core/src/components/ProTable.vue#L351-L366)

**章节来源**
- [packages/components/ProTable/RowSetting.vue:1-200](file://packages/components/ProTable/RowSetting.vue#L1-L200)
- [packages/components/ProTable/ToolBarActions.vue:1-58](file://packages/components/ProTable/ToolBarActions.vue#L1-L58)
- [packages/core/src/components/ProTable/ToolBarActions.vue:1-58](file://packages/core/src/components/ProTable/ToolBarActions.vue#L1-L58)

### 表单弹窗与提交流程
- 打开方式：点击“新增/编辑”或删除确认后打开
- 表单生成：基于列配置的 renderForm 生成
- 提交逻辑：校验通过后调用 submit()，根据类型选择新增/编辑/删除请求

```mermaid
sequenceDiagram
participant U as "用户"
participant PT as "ProTable"
participant PF as "ProForm"
participant SRV as "服务端"
U->>PT : 点击“新增/编辑”
PT->>PF : 初始化表单数据
U->>PF : 填写/修改表单项
PF-->>PT : 校验通过
PT->>SRV : 提交请求新增/编辑
SRV-->>PT : 返回结果
PT-->>U : 成功/失败提示并关闭弹窗
```

**图表来源**
- [packages/components/ProTable.vue:799-830](file://packages/components/ProTable.vue#L799-L830)
- [packages/core/src/components/ProTable.vue:799-830](file://packages/core/src/components/ProTable.vue#L799-L830)

**章节来源**
- [packages/components/ProTable.vue:119-147](file://packages/components/ProTable.vue#L119-L147)
- [packages/core/src/components/ProTable.vue:119-147](file://packages/core/src/components/ProTable.vue#L119-L147)

### 数据流与分页
- 分页参数：支持通过 map.current/map.pageSize 与 format.formatCurrent 自定义分页字段与格式
- 数据映射：通过 map.dataPath/map.totalPath 解析响应体
- 自动请求：autoFetch=true 时挂载即请求；否则需手动调用 fetch()

```mermaid
flowchart TD
Start(["开始"]) --> CheckReq{"是否配置 request?"}
CheckReq --> |否| Log["输出请求路径为空"]
CheckReq --> |是| BuildPage["构造分页参数<br/>current/pageSize/formatCurrent"]
BuildPage --> Fetch["发起请求"]
Fetch --> ParseRes{"解析响应"}
ParseRes --> |成功| MapData["映射 dataPath/totalPath"]
ParseRes --> |失败| Empty["清空数据与总数"]
MapData --> Emit["触发 fetchFinish 与 successHandle"]
Empty --> Emit
Emit --> End(["结束"])
```

**图表来源**
- [packages/components/ProTable.vue:665-741](file://packages/components/ProTable.vue#L665-L741)
- [packages/core/src/components/ProTable.vue:665-741](file://packages/core/src/components/ProTable.vue#L665-L741)

**章节来源**
- [packages/components/ProTable.vue:665-741](file://packages/components/ProTable.vue#L665-L741)
- [packages/core/src/components/ProTable.vue:665-741](file://packages/core/src/components/ProTable.vue#L665-L741)

## 依赖关系分析
- 组件依赖：
  - lodash-es（数据处理与深拷贝）
  - screenfull（全屏控制）
  - 自定义请求封装（customRequest）
  - 子组件：ProSearch、ProForm、ProTypeItem、RowSetting、UIEditFrame
- 类型依赖：types/ProTable.d.ts 提供属性类型约束

```mermaid
graph LR
PT["ProTable.vue"] --> L["lodash-es"]
PT --> SF["screenfull"]
PT --> CR["customRequest"]
PT --> PS["ProSearch.vue"]
PT --> PF["ProForm.vue"]
PT --> PTI["ProTypeItem.vue"]
PT --> RS["RowSetting.vue"]
PT --> UIF["UIEditFrame.vue"]
```

**图表来源**
- [packages/components/ProTable.vue:156-165](file://packages/components/ProTable.vue#L156-L165)
- [packages/core/src/components/ProTable.vue:156-165](file://packages/core/src/components/ProTable.vue#L156-L165)

**章节来源**
- [packages/components/ProTable.vue:156-165](file://packages/components/ProTable.vue#L156-L165)
- [packages/core/src/components/ProTable.vue:156-165](file://packages/core/src/components/ProTable.vue#L156-L165)

## 性能考量
- 合理使用 autoFetch：避免不必要的首屏请求
- 列渲染优化：仅在需要时提供 render* 函数，减少不必要的虚拟 DOM 生成
- 分页参数格式化：format.formatCurrent 使用字符串表达式时会动态生成函数，建议尽量使用函数以提升性能
- 行设置本地存储：RowSetting 支持 localStorage 缓存，减少每次初始化成本

[本节为通用建议，不直接分析具体文件]

## 故障排查指南
- 请求路径为空：检查 request 配置是否正确传入
- 数据路径不匹配：确认 map.dataPath 与 map.totalPath 指向正确字段
- 删除后页码异常：组件会在删除最后一行时自动回退一页，确保分页 current 正确
- 表单校验失败：submit() 会先执行 validate，失败时会保持弹窗并切换加载状态
- UI 编辑模式：开启 uiEdit 时，部分区域会显示编辑框，注意与业务逻辑的兼容

**章节来源**
- [packages/components/ProTable.vue:738-741](file://packages/components/ProTable.vue#L738-L741)
- [packages/components/ProTable.vue:707-722](file://packages/components/ProTable.vue#L707-L722)
- [packages/components/ProTable.vue:578-587](file://packages/components/ProTable.vue#L578-L587)
- [packages/components/ProTable.vue:819-826](file://packages/components/ProTable.vue#L819-L826)

## 结论
ProTable 提供了完善的表格管理能力，涵盖搜索、分页、工具栏、行设置与表单弹窗。通过清晰的属性与事件设计，开发者可以灵活地集成远程数据与本地数据，并借助列配置实现复杂的渲染与交互需求。建议在实际项目中结合示例与类型声明，合理组织 columns 与请求配置，以获得最佳的开发体验与运行性能。

## 附录

### API 速查表
- 属性
  - columns: 列配置
  - hide: 区域隐藏开关
  - map: 数据映射
  - request/submitForm: 请求配置
  - search/form/table: 子组件传参
  - 其他：pageSize/toolBarActions/attrs/title/method/headers/autoFetch/format/modelValue/storage/uiEdit
- 事件
  - pageClick/uiConfig/search/searchReset/formReset/fetchFinish
- 插槽
  - header/title/tableTip
- 方法
  - search/fetchCurrent/pageSizeChange/setTotal/getTotal/getDatas/getSelection/finish/success/error/submitLoading/submit/fetch

**章节来源**
- [packages/components/ProTable.vue:195-266](file://packages/components/ProTable.vue#L195-L266)
- [packages/components/ProTable.vue:457-462](file://packages/components/ProTable.vue#L457-L462)
- [packages/components/ProTable.vue:37-72](file://packages/components/ProTable.vue#L37-L72)
- [packages/components/ProTable.vue:605-624](file://packages/components/ProTable.vue#L605-L624)
- [packages/components/ProTable.vue:753-830](file://packages/components/ProTable.vue#L753-L830)