# ProTable 智能表格

<cite>
**本文引用的文件**
- [ProTable.vue](file://packages/components/ProTable.vue)
- [ProTableEdit.vue](file://packages/components/ProTableEdit.vue)
- [ProSearch.vue](file://packages/components/ProSearch.vue)
- [ProForm.vue](file://packages/components/ProForm.vue)
- [ProSelect.vue](file://packages/components/ProSelect.vue)
- [ProCheckBox.vue](file://packages/components/ProCheckBox.vue)
- [ProTable.d.ts](file://types/ProTable.d.ts)
- [ProTable 示例视图](file://src/views/ProTable.vue)
- [表格渲染示例视图](file://src/views/TableRender.vue)
- [ProSearch 示例视图](file://src/views/ProSearch.vue)
- [ProForm 示例视图](file://src/views/ProForm.vue)
- [主入口 main.js](file://src/main.js)
- [组件注册入口 index.js](file://packages/index.js)
- [请求封装 request.js](file://packages/libs/request.js)
- [国际化混入 locale.js](file://packages/mixin/locale.js)
- [包配置 package.json](file://package.json)
</cite>

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

## 简介
ProTable 是一个面向业务的智能数据表格组件，集成了搜索、分页、工具栏、弹窗表单、批量操作、国际化、全屏等功能，并通过统一的请求封装与后端交互。它支持列级渲染（表格、搜索、表单）、列配置记忆与重置、动态列过滤、操作列按钮、表单校验与提交、以及与 ProSearch、ProForm 等周边组件的无缝协作。组件现已支持全局映射配置，允许在应用级别设置默认的数据路径和分页配置，并与组件级配置协同工作。

## 项目结构
本仓库采用多包/多模块组织方式，ProTable 及其周边组件位于 packages/components 下，示例页面位于 src/views 中，类型声明位于 types 目录，全局安装与注入逻辑在 packages/index.js 中完成。

```mermaid
graph TB
subgraph "应用入口"
A["src/main.js"]
B["packages/index.js"]
end
subgraph "组件库"
C["packages/components/ProTable.vue"]
D["packages/components/ProTableEdit.vue"]
E["packages/components/ProSearch.vue"]
F["packages/components/ProForm.vue"]
G["packages/components/ProSelect.vue"]
H["packages/components/ProCheckBox.vue"]
end
subgraph "示例页面"
I["src/views/ProTable.vue"]
J["src/views/TableRender.vue"]
K["src/views/ProSearch.vue"]
L["src/views/ProForm.vue"]
end
subgraph "工具与类型"
M["packages/libs/request.js"]
N["packages/mixin/locale.js"]
O["types/ProTable.d.ts"]
P["package.json"]
end
A --> B
B --> C
B --> D
B --> E
B --> F
B --> G
B --> H
I --> C
J --> C
K --> E
L --> F
C --> M
C --> N
D --> M
D --> N
G --> M
G --> N
H --> M
H --> N
C -. 全局映射配置 .-> A
G -. 全局映射配置 .-> A
H -. 全局映射配置 .-> A
```

**图表来源**
- [主入口 main.js:16-20](file://src/main.js#L16-L20)
- [组件注册入口 index.js:16-19](file://packages/index.js#L16-L19)
- [ProTable.vue:268-291](file://packages/components/ProTable.vue#L268-L291)
- [ProSelect.vue:45-60](file://packages/components/ProSelect.vue#L45-L60)
- [ProCheckBox.vue:60-75](file://packages/components/ProCheckBox.vue#L60-L75)

**章节来源**
- [主入口 main.js:1-23](file://src/main.js#L1-L23)
- [组件注册入口 index.js:1-69](file://packages/index.js#L1-L69)

## 核心组件
- ProTable：智能数据表格，内置搜索、分页、工具栏、弹窗表单、操作列、列设置记忆与重置、全屏等能力。
- ProTableEdit：可编辑表格模式，支持行增删改、批量操作、实时校验、保存等。
- ProSearch：搜索面板，基于列配置生成搜索控件，支持格式化与联动。
- ProForm：弹窗内嵌表单，支持列级渲染、表单校验、提交与成功回调。
- ProSelect：选择器组件，支持远程数据加载和本地数据展示。
- ProCheckBox：复选框组组件，支持远程数据加载和本地数据展示。
- request：统一请求封装，支持字符串/对象/函数三种请求形式，自动拼装 GET 参数与 POST body。
- locale：国际化混入，提供 t/$t 方法。

**章节来源**
- [ProTable.vue:154-850](file://packages/components/ProTable.vue#L154-L850)
- [ProTableEdit.vue:1-1298](file://packages/components/ProTableEdit.vue#L1-L1298)
- [ProSearch.vue](file://packages/components/ProSearch.vue)
- [ProForm.vue](file://packages/components/ProForm.vue)
- [ProSelect.vue:1-170](file://packages/components/ProSelect.vue#L1-L170)
- [ProCheckBox.vue:1-158](file://packages/components/ProCheckBox.vue#L1-L158)
- [ProTable.d.ts:1-59](file://types/ProTable.d.ts#L1-L59)
- [请求封装 request.js:1-78](file://packages/libs/request.js#L1-L78)
- [国际化混入 locale.js:1-18](file://packages/mixin/locale.js#L1-L18)

## 架构总览
ProTable 通过统一的请求封装与后端交互，结合列配置的"表格/搜索/表单"三态渲染，形成"配置驱动"的数据表格解决方案。其核心流程如下：

```mermaid
sequenceDiagram
participant U as "用户"
participant PT as "ProTable"
participant PS as "ProSearch"
participant PF as "ProForm"
participant REQ as "request 封装"
participant S as "服务端"
U->>PT : 打开页面/点击刷新
PT->>REQ : 发起请求(含分页与搜索条件)
REQ->>S : GET/POST 请求
S-->>REQ : 返回数据(含 data 与 total)
REQ-->>PT : 解析响应(按 mergedMap.dataPath/mergedMap.totalPath)
PT-->>U : 渲染表格与分页
U->>PS : 修改搜索条件并提交
PS-->>PT : 触发 search/reset 事件
PT->>PT : 重置页码/合并条件
PT->>REQ : 再次请求
REQ-->>PT : 返回新数据
PT-->>U : 更新表格
U->>PT : 点击"新建/编辑"
PT->>PF : 打开弹窗并传入列与数据
PF-->>PT : 提交表单(校验通过)
PT->>REQ : 提交表单
REQ-->>PT : 成功/失败消息
PT-->>U : 提示并刷新
```

**图表来源**
- [ProTable.vue:605-830](file://packages/components/ProTable.vue#L605-L830)
- [ProSearch.vue](file://packages/components/ProSearch.vue)
- [ProForm.vue](file://packages/components/ProForm.vue)
- [请求封装 request.js:39-77](file://packages/libs/request.js#L39-L77)

## 详细组件分析

### ProTable 组件
- 功能概览
  - 搜索区：基于列配置生成搜索控件，支持格式化、范围选择、联动等。
  - 工具栏：支持新建、刷新、全屏、列设置等动作，支持自定义扩展。
  - 表格区：根据列配置渲染表格，支持固定列、排序、tooltip、列过滤。
  - 分页区：支持页码与页大小变更，自动计算总条目。
  - 弹窗表单：统一的 CRUD 流程，支持新建/编辑/查看。
  - 国际化：内置多语言键位，支持 t/$t。
  - 全屏：支持容器级全屏，切换时自动加/减 body 类名。
  - **全局映射配置**：支持通过 $PRO_IVIEW 设置全局数据路径和分页配置。
- 关键属性与行为
  - 列配置：columns 支持 renderTable/renderSearch/renderForm/action 等字段；支持 children 实现复杂表头。
  - 数据映射：map.current/pageSize/dataPath/totalPath/message/success 控制分页与数据路径。
  - **合并映射**：mergedMap 优先使用组件级配置，其次使用 $PRO_IVIEW 全局配置，最后使用默认值。
  - 请求：request 支持字符串、对象、函数；method/headers/submitForm/submitForm.method 等。
  - 隐藏控制：hide.search/toolBar/page/table 控制区域显隐。
  - 事件：search/searchReset/fetchFinish/pageClick/uiConfig 等。
- 数据流与渲染
  - columnFilter：根据 notShow* 与 render* 字段动态生成表格/搜索/表单列。
  - renderTableSelf：递归处理 children，注入渲染器。
  - fetch：统一请求入口，支持 format.formatCurrent 动态构造分页参数。
  - tableAction/typeAction：处理"新建/编辑/删除"等动作，调用 customRequest 并刷新。
- 与周边组件集成
  - 与 ProSearch：通过 searchColumns 传递列配置，双向绑定 form。
  - 与 ProForm：通过 formDialog 打开弹窗，传入 formColumns 与 proFormData。
  - 与 UIEditFrame：在开发模式下提供可视化配置与导出。

```mermaid
classDiagram
class ProTable {
+props : columns, request, map, hide, submitForm, search, form, table
+data : innerValue, showTableColumns, formDialog, loading, total, page
+computed : toolBarList, tableColumns, searchColumns, formColumns, mergedMap
+methods : fetch(), search(), searchReset(), tableAction(), successHandle()
}
class ProSearch {
+props : columns, value
+events : search, reset
}
class ProForm {
+props : columns, type, dialog, value
+methods : validate(), reset()
}
class Request {
+call(request, method, datas, headers) Promise
}
class GlobalConfig {
+$PRO_IVIEW : {format, map}
+map : {current, pageSize, dataPath, totalPath, message, success}
}
ProTable --> ProSearch : "使用"
ProTable --> ProForm : "使用"
ProTable --> Request : "请求封装"
ProTable --> GlobalConfig : "合并配置"
```

**图表来源**
- [ProTable.vue:195-422](file://packages/components/ProTable.vue#L195-L422)
- [ProTable.vue:268-291](file://packages/components/ProTable.vue#L268-L291)
- [ProSearch.vue](file://packages/components/ProSearch.vue)
- [ProForm.vue](file://packages/components/ProForm.vue)
- [请求封装 request.js:39-77](file://packages/libs/request.js#L39-L77)

**章节来源**
- [ProTable.vue:154-850](file://packages/components/ProTable.vue#L154-L850)
- [ProTable.d.ts:1-59](file://types/ProTable.d.ts#L1-L59)

### ProTableEdit 可编辑表格
- 功能概览
  - 行级编辑：点击单元格进入编辑态，支持快捷键导航、实时校验、错误提示。
  - 行级控制：左侧控制列支持新增、复制、删除、恢复、刷新等。
  - 批量操作：勾选后支持复制、删除、刷新、恢复等。
  - 保存：统一保存接口，对比新增/修改/删除集合，支持保存路径映射。
  - 校验：基于 async-validator，支持字段级规则与整体校验。
- 关键点
  - editTableRender：将列转换为可编辑渲染器，注入 onUpdate:modelValue/check。
  - editList：记录每个单元格的编辑状态与校验结果。
  - addRow/copyRow/deleteRow/recoveryRow/refreshRow：行级 CRUD。
  - saveData：保存并刷新，支持分页边界处理。

```mermaid
flowchart TD
Start(["进入编辑态"]) --> ClickCell["点击单元格"]
ClickCell --> CanEdit{"允许编辑?"}
CanEdit --> |否| Normal["显示正常内容"]
CanEdit --> |是| Edit["进入编辑态<br/>FocusItem/自定义编辑器"]
Edit --> OnInput["输入/失焦触发校验"]
OnInput --> Validate["async-validator 校验"]
Validate --> HasError{"存在错误?"}
HasError --> |是| ShowError["显示错误提示"]
HasError --> |否| Save["等待保存或继续编辑"]
Save --> SaveClick{"点击保存?"}
SaveClick --> |是| CallSave["调用保存接口"]
CallSave --> Reset["重置状态并刷新"]
SaveClick --> |否| Continue["继续编辑"]
Normal --> End(["结束"])
Reset --> End
Continue --> End
```

**图表来源**
- [ProTableEdit.vue:399-751](file://packages/components/ProTableEdit.vue#L399-L751)

**章节来源**
- [ProTableEdit.vue:1-1298](file://packages/components/ProTableEdit.vue#L1-L1298)

### ProSearch 搜索组件
- 功能概览
  - 基于列配置生成搜索控件，支持 DatePicker、Select 等。
  - 支持 format/formatWapper 对日期范围等进行格式化。
  - 支持外部 v-model 与内部状态同步。
- 使用要点
  - 在 ProTable 中通过 searchColumns 与 form 双向绑定。
  - 支持 reset 重置到初始值。

**章节来源**
- [ProSearch.vue](file://packages/components/ProSearch.vue)
- [ProTable 示例视图:11-16](file://src/views/ProTable.vue#L11-L16)
- [ProSearch 示例视图:1-59](file://src/views/ProSearch.vue#L1-L59)

### ProForm 弹窗表单
- 功能概览
  - 基于列配置生成表单项，支持 renderForm 自定义渲染。
  - 支持表单校验、提交、成功回调。
  - 与 ProTable 的 submitForm/request 协作完成 CRUD。
- 使用要点
  - 在 ProTable 中通过 formDialog 打开弹窗，传入 formColumns 与 proFormData。
  - 支持 form.value 默认值与外部传入合并。

**章节来源**
- [ProForm.vue](file://packages/components/ProForm.vue)
- [ProTable 示例视图:119-147](file://src/views/ProTable.vue#L119-L147)
- [ProForm 示例视图:1-198](file://src/views/ProForm.vue#L1-L198)

### ProSelect 选择器组件
- 功能概览
  - 支持远程数据加载和本地数据展示。
  - 自动合并组件级配置与全局映射配置。
  - 支持多种数据格式和模板渲染。
- 配置合并机制
  - dataPath/titlePath/valuePath 优先使用组件级 map 配置。
  - 若组件级配置不存在，则使用 $PRO_IVIEW 全局配置。
  - 若全局配置也不存在，则使用默认值。

**章节来源**
- [ProSelect.vue:1-170](file://packages/components/ProSelect.vue#L1-L170)

### ProCheckBox 复选框组件
- 功能概览
  - 支持远程数据加载和本地数据展示。
  - 自动合并组件级配置与全局映射配置。
  - 支持多选和单选模式。
- 配置合并机制
  - dataPath/titlePath/valuePath 优先使用组件级 map 配置。
  - 若组件级配置不存在，则使用 $PRO_IVIEW 全局配置。
  - 若全局配置也不存在，则使用默认值。

**章节来源**
- [ProCheckBox.vue:1-158](file://packages/components/ProCheckBox.vue#L1-L158)

### 请求封装与国际化
- 请求封装 request
  - 支持字符串 URL、对象配置（含 request/url/method/keys）、函数形式。
  - 自动拼装 GET 参数与 POST body，支持占位替换 ${var}。
  - 自动注入 Authorization 头（从查询参数提取）。
- 国际化 locale
  - 提供 t/$t 方法，组件内统一使用 $t 或 t 访问翻译。

**章节来源**
- [请求封装 request.js:1-78](file://packages/libs/request.js#L1-L78)
- [国际化混入 locale.js:1-18](file://packages/mixin/locale.js#L1-L18)

## 全局映射配置

### 配置概述
ProTable 及相关组件现已支持全局映射配置，允许在应用初始化时设置默认的数据路径和分页配置。这种设计使得开发者可以在应用级别统一配置数据结构，减少重复的组件级配置。

### 配置设置方式
全局映射配置通过在应用入口文件中设置 `$PRO_IVIEW` 全局属性来实现：

```javascript
// src/main.js
app.use(ProComponents, {
  pro_iview: {
    map: { 
      dataPath: "data", 
      totalPath: "totalRows" 
    }
  }
})
```

### 配置合并机制
组件会按照以下优先级顺序合并配置：

1. **组件级配置**：最高优先级，覆盖所有其他配置
2. **全局配置**：$PRO_IVIEW.pro_iview.map 中的配置
3. **默认值**：组件内部的默认配置

```mermaid
flowchart TD
A["组件级配置"] --> C["mergedMap 合并"]
B["$PRO_IVIEW 全局配置"] --> C
C --> D["最终生效配置"]
E["默认配置"] --> C
```

**图表来源**
- [ProTable.vue:268-291](file://packages/components/ProTable.vue#L268-L291)
- [ProSelect.vue:45-60](file://packages/components/ProSelect.vue#L45-L60)
- [ProCheckBox.vue:60-75](file://packages/components/ProCheckBox.vue#L60-L75)

### 支持的配置项
全局映射配置支持以下配置项：

- `current`：当前页参数名，默认值："current"
- `pageSize`：每页大小参数名，默认值："pageSize"
- `dataPath`：数据路径，默认值："data"
- `totalPath`：总数路径，默认值："totalRows"
- `message`：消息字段路径
- `success`：成功判断字段路径

### 使用示例
#### 应用级配置
```javascript
// src/main.js
app.use(ProComponents, {
  pro_iview: {
    map: {
      dataPath: "data.rows",
      totalPath: "data.total",
      current: "page",
      pageSize: "limit"
    }
  }
})
```

#### 组件级覆盖
```vue
<!-- 组件中覆盖全局配置 -->
<ProTable
  :map="{
    dataPath: 'result.data',
    totalPath: 'result.count'
  }"
/>
```

#### 默认配置回退
当组件级配置缺失时，会自动使用全局配置，如果全局配置也缺失，则使用组件内部默认值。

**章节来源**
- [主入口 main.js:16-20](file://src/main.js#L16-L20)
- [组件注册入口 index.js:16-19](file://packages/index.js#L16-L19)
- [ProTable.vue:268-291](file://packages/components/ProTable.vue#L268-L291)
- [ProSelect.vue:45-60](file://packages/components/ProSelect.vue#L45-L60)
- [ProCheckBox.vue:60-75](file://packages/components/ProCheckBox.vue#L60-L75)

## 依赖关系分析
- 运行时依赖
  - view-ui-plus：UI 组件库基础。
  - axios/lodash-es/dayjs/mousetrap/screenfull 等：网络、工具、日期、快捷键、全屏。
- 构建与打包
  - Vite/Vue3 生态，Turbo 多包管理。
- 组件注册
  - 通过 packages/index.js 将组件全局注册，并注入全局属性（$http、$dayjs、$lodash、$PRO_IVIEW）。

```mermaid
graph LR
P["package.json 依赖"] --> V["view-ui-plus"]
P --> AX["axios"]
P --> LO["lodash-es"]
P --> DJ["dayjs"]
P --> MT["mousetrap"]
P --> SF["screenfull"]
P --> VP["vue"]
P --> VR["vue-router"]
P --> VPJS["vue3-click-away"]
P --> DR["vuedraggable"]
IDX["packages/index.js"] --> C1["ProTable"]
IDX --> C2["ProTableEdit"]
IDX --> C3["ProSearch"]
IDX --> C4["ProForm"]
IDX --> C5["ProSelect"]
IDX --> C6["ProCheckBox"]
```

**图表来源**
- [包配置 package.json:20-47](file://package.json#L20-L47)
- [组件注册入口 index.js:12-42](file://packages/index.js#L12-L42)

**章节来源**
- [包配置 package.json:1-47](file://package.json#L1-L47)
- [组件注册入口 index.js:1-69](file://packages/index.js#L1-L69)

## 性能考虑
- 列渲染优化
  - 仅在需要时注入 render，避免重复包装。
  - children 递归处理，减少重复计算。
- 请求与分页
  - format.formatCurrent 支持动态构造分页参数，避免多余字段。
  - 仅在必要时发起请求（autoFetch、页码/页大小变更）。
- DOM 与样式
  - 使用 scoped CSS 与深度选择器，避免样式污染。
  - 全屏切换时仅对 body 添加/移除类名，降低重排成本。
- 编辑态优化（ProTableEdit）
  - 仅在编辑态渲染编辑器，正常态渲染纯文本。
  - 键盘导航与焦点管理减少不必要的重渲染。
- **全局配置缓存**
  - $PRO_IVIEW 全局配置在组件初始化时读取，避免重复计算。

## 故障排除指南
- 请求路径为空
  - 现象：控制台打印"请求路径为空"。
  - 处理：确保传入 request 属性或在 submitForm/request 中配置。
- 数据路径不匹配
  - 现象：表格无数据显示，提示"请检查数据路径和分页配置"。
  - 处理：确认 mergedMap.dataPath 与 mergedMap.totalPath 与后端一致。
  - **新增**：检查全局配置和组件级配置的合并结果。
- 成功判断失败
  - 现象：弹窗关闭但未刷新。
  - 处理：检查 mergedMap.success 或 form.success 的表达式与后端返回字段一致。
- 删除最后一行导致页码异常
  - 现象：删除后页码未回退。
  - 处理：组件已自动处理页码回退逻辑，若仍异常，请检查 total 与分页参数。
- 全屏样式问题
  - 现象：全屏后背景色异常。
  - 处理：确认全屏切换时 body 类名已正确添加/移除。
- **全局配置不生效**
  - 现象：组件仍然使用默认数据路径。
  - 处理：确认 $PRO_IVIEW 配置已在应用初始化时正确设置。

**章节来源**
- [ProTable.vue:665-741](file://packages/components/ProTable.vue#L665-L741)
- [ProTable.vue:578-586](file://packages/components/ProTable.vue#L578-L586)
- [ProTable.vue:844-849](file://packages/components/ProTable.vue#L844-L849)

## 结论
ProTable 通过"配置驱动 + 统一请求 + 周边组件协同"的架构，提供了从数据展示、搜索筛选、分页、编辑到国际化与全屏的完整能力。新增的全局映射配置功能进一步增强了组件的灵活性和可维护性，使得开发者可以在应用级别统一管理数据结构配置。其类型声明与示例页面有助于快速上手，同时保留了高度的可扩展性与可维护性。

## 附录

### API 与配置速查
- ProTable
  - 属性
    - columns：列配置数组（支持 renderTable/renderSearch/renderForm/actions 等）
    - request：请求配置（字符串/对象/函数）
    - map：{ current, pageSize, dataPath, totalPath, message, success }
    - hide：{ search, toolBar, page, table }
    - submitForm：新建/编辑提交配置
    - search/form/table：透传给 ProSearch/ProForm/View UI Table 的属性
    - autoFetch/toolBarActions/storage：行为与存储配置
  - 事件
    - search/searchReset/fetchFinish/pageClick/uiConfig
  - 方法
    - fetch()/search()/searchReset()/tableAction()/successHandle()/getDatas()/finish()
- ProTableEdit
  - 属性
    - columns、disabled、notShowLeftControls、addDirection、deleteOriginal、iviewTable、controls、autoFetch、editable、addDefaultValue、normalShowEdit、page、shortcuts、save
  - 事件
    - save
  - 方法
    - validateAll()/reset()/saveData()/addRow()/deleteRow()/refreshRow()/copyRow()
- **新增** ProSelect/ProCheckBox
  - 属性
    - request、method、map、first、list、modelValue、valueType
  - 计算属性
    - mergedMap：合并组件级配置与全局配置

**章节来源**
- [ProTable.d.ts:1-59](file://types/ProTable.d.ts#L1-L59)
- [ProTable.vue:195-266](file://packages/components/ProTable.vue#L195-L266)
- [ProTableEdit.vue:55-124](file://packages/components/ProTableEdit.vue#L55-L124)
- [ProSelect.vue:40-60](file://packages/components/ProSelect.vue#L40-L60)
- [ProCheckBox.vue:55-75](file://packages/components/ProCheckBox.vue#L55-L75)

### 使用示例索引
- ProTable 基础与列渲染
  - [ProTable 示例视图:1-306](file://src/views/ProTable.vue#L1-L306)
  - [表格渲染示例视图:1-51](file://src/views/TableRender.vue#L1-L51)
- ProSearch 与 ProForm 集成
  - [ProSearch 示例视图:1-59](file://src/views/ProSearch.vue#L1-L59)
  - [ProForm 示例视图:1-198](file://src/views/ProForm.vue#L1-L198)
- **新增** 全局映射配置
  - [主入口 main.js:16-20](file://src/main.js#L16-L20)
  - [组件注册入口 index.js:16-19](file://packages/index.js#L16-L19)