@aspire-ui/element-component-pro 1.0.25 → 1.0.27

package/docs/ProTable-Redesign.md

@@ -0,0 +1,214 @@
+# 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 需同步更新