# ProTable 重新设计（参考 VbenAdmin BasicTable）

## 1. 设计目标

基于 Element UI Table 的 ProTable 参考 [Vben Admin BasicTable](https://doc.vvbin.cn/components/table.html) 进行重新设计，在保持 Vue 2.7 + Element UI 技术栈的前提下，对齐 VbenAdmin 的 API 设计、功能特性和使用体验。

## 2. 功能对比

| 功能 | VbenAdmin BasicTable | 当前 ProTable | 差距 |
|------|----------------------|---------------|------|
| **基础** |
| 列配置 | BasicColumn | ProColumn | 命名/字段需对齐 |
| 数据源 | dataSource / api | 支持 | 已对齐 |
| 分页 | pagination | 支持 | 已对齐 |
| 加载状态 | loading | 支持 | 已对齐 |
| 边框/条纹 | bordered / striped | 支持 | 已对齐 |
| **标题与工具栏** |
| 标题 | title | 支持 | 已对齐 |
| 标题帮助 | titleHelpMessage | 支持 | 已对齐 |
| 工具栏 | #toolbar | 支持 | 已对齐 |
| 表格设置 | tableSetting (redo/size/setting/fullScreen) | 部分 | 仅 redo，缺 size/setting/fullScreen |
| **列选择** |
| 行选择 | rowSelection | 支持 | 已对齐 |
| 跨页选择 | clearSelectOnPageChange | 支持 | 已对齐 |
| **列配置** |
| 列宽 | width / minWidth | 支持 | 已对齐 |
| 列宽限制 | maxWidth | 已支持 | 已对齐 |
| 默认隐藏 | defaultHidden | 支持 | 已对齐 |
| 列头帮助 | helpMessage | 支持 | 已对齐 |
| 权限控制 | auth | 无 | 需新增 |
| **表格能力** |
| 序号列 | showIndexColumn / indexColumnProps | 支持 | 已对齐 |
| 操作列 | actionColumn | 支持 | 已对齐 |
| 树形表格 | isTreeTable / treeProps | 支持 | 已对齐 |
| 合并单元格 | - | spanMethod | 已支持 |
| 可编辑单元格 | edit / editComponent | 无 | 需新增 |
| 合计行 | showSummary / summaryFunc | 无 | 需新增 |
| 列拖拽 | canColDrag | 无 | 可选 |
| 行拖拽 | canRowDrag | 无 | 可选 |
| **搜索表单** |
| 搜索表单 | useSearchForm / formConfig | 无 | 需新增 |
| **TableActionType** |
| setProps | ✓ | ✓ | 已对齐 |
| reload | ✓ | ✓ | 已对齐 |
| reload(opt) | 支持 FetchParams | 支持 | 已对齐 |
| getDataSource | ✓ | ✓ | 已对齐 |
| getRawDataSource | ✓ | ✓ | 已对齐 |
| setTableData | ✓ | ✓ | 已对齐 |
| getColumns / setColumns | ✓ | ✓ | 已对齐 |
| setPagination | ✓ | ✓ | 已对齐 |
| getSelectRowKeys / getSelectRows | ✓ | ✓ | 已对齐 |
| clearSelectedRowKeys | ✓ | ✓ | 已对齐 |
| setSelectedRowKeys | ✓ | ✓ | 已对齐 |
| deleteSelectRowByKey | ✓ | ✓ | 已对齐 |
| updateTableDataRecord | ✓ | ✓ | 已对齐 |
| deleteTableDataRecord | ✓ | ✓ | 已对齐 |
| insertTableDataRecord | ✓ | ✓ | 已对齐 |
| getPaginationRef | ✓ | ✓ | 已对齐 |
| getShowPagination / setShowPagination | ✓ | ✓ | 已对齐 |
| expandAll / collapseAll | ✓ | ✓ | 已对齐 |
| redoHeight | ✓ | ✓ | 已对齐 |
| getForm | ✓ | 无 | 需新增（搜索表单时） |

## 3. API 设计对齐

### 3.1 BasicColumn → ProColumn 命名与字段

| VbenAdmin BasicColumn | ProTable ProColumn | 说明 |
|-----------------------|--------------------|------|
| title | title | 一致 |
| dataIndex | dataIndex | 一致 |
| key | key | 一致 |
| width | width | 一致（ProTable 支持 number 比例） |
| minWidth | minWidth | 一致 |
| maxWidth | maxWidth | 已支持 |
| fixed | fixed | 一致 |
| align | align | 一致 |
| defaultHidden | defaultHidden | 已实现（控制列默认隐藏，可通过列设置显示） |
| helpMessage | helpMessage | 已实现（列头右侧帮助文案） |
| auth | auth | 需新增 |
| ifShow | ifShow | 一致 |
| format | format | 需新增（或与 customRender 对齐） |
| edit / editRow / editComponent | - | 需新增（可编辑表格） |

### 3.2 TableActionType 方法补齐（当前状态）

```ts
interface TableActionType {
  // 已对齐 VbenAdmin 的方法
  setProps: (props: Partial<ProTableProps>) => void
  reload: (opt?: FetchParams) => Promise<void>
  /** 重新计算表格高度/布局（Element UI doLayout） */
  redoHeight: () => void
  setLoading: (loading: boolean) => void
  getDataSource: () => Record<string, unknown>[]
  getRawDataSource: () => Record<string, unknown>
  setTableData: (data: Record<string, unknown>[]) => void
  getColumns: () => ProColumn[]
  setColumns: (columns: ProColumn[] | string[]) => void
  setPagination: (info: Partial<{ page: number; pageSize: number; total: number }>) => void
  getSelectRowKeys: () => (string | number)[]
  getSelectRows: () => Record<string, unknown>[]
  clearSelectedRowKeys: () => void
  setSelectedRowKeys: (keys: (string | number)[]) => void
  deleteSelectRowByKey: (key: string | number) => void
  updateTableData: (index: number, key: string, value: unknown) => void
  updateTableDataRecord: (rowKey: string | number, record: Record<string, unknown>) => Record<string, unknown> | void
  deleteTableDataRecord: (rowKey: string | number | (string | number)[]) => void
  insertTableDataRecord: (record: Record<string, unknown>, index?: number) => Record<string, unknown> | void
  getPaginationRef: () => { page: number; pageSize: number; total: number } | false
  getShowPagination: () => boolean
  setShowPagination: (show: boolean) => void | Promise<void>
  expandAll?: () => void
  collapseAll?: () => void
}
```

### 3.3 reload 增强

```ts
// VbenAdmin 支持
reload(opt?: FetchParams) => Promise<void>

interface FetchParams {
  page?: number
  pageSize?: number
  searchInfo?: Record<string, unknown>
}
```

## 4. 实现优先级

### P0 - 核心对齐（必做）

1. **TableActionType 方法补齐（已完成）**
   - setSelectedRowKeys / deleteSelectRowByKey
   - getRawDataSource
   - updateTableData / updateTableDataRecord / deleteTableDataRecord / insertTableDataRecord
   - getPaginationRef / getShowPagination / setShowPagination
   - redoHeight

2. **reload 增强（已完成）**
   - 已支持 `reload({ page, pageSize, searchInfo })`

3. **ProColumn 扩展（已完成）**
   - defaultHidden
   - helpMessage

### P1 - 体验增强

4. **tableSetting 完善**
   - size：密度切换（medium/small/large）
   - setting：列设置（显示/隐藏、固定、排序）
   - fullScreen：全屏

5. **auth 权限控制**
   - 列级 auth 控制显示（需接入项目权限体系）

### P2 - 高级功能

6. **搜索表单**
   - useSearchForm + formConfig
   - getForm

7. **可编辑表格**
   - edit / editRow / editComponent

8. **合计行**
   - showSummary / summaryFunc

## 5. 技术方案

### 5.1 列设置组件（ColumnSetting）

- 弹窗展示可配置列列表
- 支持：显示/隐藏、固定、排序
- 与 showIndexColumn、rowSelection 联动

### 5.2 密度切换

- 暴露 size 到 tableSetting.size
- 切换 medium / small / large 传给 el-table

### 5.3 全屏

- 使用 Fullscreen API 或全屏 class
- 表格容器包裹一层，全屏时占满视口

### 5.4 数据操作方法

- updateTableDataRecord：按 rowKey 查找并替换
- deleteTableDataRecord：按 rowKey 查找并删除
- insertTableDataRecord：按 index 插入

## 6. 文件结构

```
src/ProTable/
├── ProTable.vue          # 主组件
├── useProTable.ts        # Hook
├── types/
│   └── index.ts          # 类型定义
├── components/           # 可选子组件
│   ├── TableSetting.ts   # 工具栏设置（刷新/密度/列设置/全屏）
│   └── ColumnSetting.vue # 列配置弹窗
├── hooks/
│   └── useTableData.ts   # 数据 CRUD 逻辑
```

## 7. 变更影响

- **向后兼容**：新增 API 均为可选，原有用法不破坏
- **示例**：需更新 Basic、UseProTable 等示例
- **文档**：ProTable.md 需同步更新