Skip to content

Commit 2d23352

Browse files
hotlonghotlong
authored
Merge pull request #32 from objectql/copilot/update-table-component-aggrid
2 parents 89be29c + 3864374 commit 2d23352

File tree

8 files changed

+2531
-587
lines changed

8 files changed

+2531
-587
lines changed

‎docs/AG_GRID_MIGRATION.md‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
# AG Grid Migration Guide
2+
3+
## Overview
4+
5+
We have successfully migrated from TanStack Table to AG Grid (v35.0.0) for the frontend table component. AG Grid provides enterprise-grade features with better performance and more comprehensive functionality out of the box.
6+
7+
## What Changed
8+
9+
### Before (TanStack Table)
10+
- Manual implementation of pagination, sorting, filtering
11+
- Custom drag-and-drop with @dnd-kit libraries
12+
- Limited built-in features
13+
- More boilerplate code required
14+
15+
### After (AG Grid)
16+
- Built-in pagination, sorting, filtering
17+
- Native row dragging and column resizing
18+
- Advanced features like row grouping, aggregation (available in enterprise version)
19+
- Less code, more features
20+
21+
## Features Implemented
22+
23+
### ✅ Core Features
24+
25+
1. **Row Selection**
26+
- Checkbox-based multi-row selection
27+
- Header checkbox for select all/deselect all
28+
- Custom checkbox renderer using our UI components
29+
30+
2. **Sorting**
31+
- Click column headers to sort
32+
- Multi-column sorting support
33+
- Custom sort indicators
34+
35+
3. **Filtering**
36+
- Built-in column filters
37+
- Quick filter (search across all columns)
38+
- Custom filter UI integration
39+
40+
4. **Pagination**
41+
- Custom pagination controls (hidden AG Grid default)
42+
- Configurable page sizes (10, 20, 30, 40, 50)
43+
- First/Previous/Next/Last navigation
44+
45+
5. **Drag and Drop**
46+
- Row reordering via drag handle
47+
- Visual feedback during drag
48+
- Managed by AG Grid internally
49+
50+
6. **Column Management**
51+
- Column visibility toggle
52+
- Column resizing
53+
- Fixed column widths where needed
54+
55+
7. **Custom Cell Renderers**
56+
- Status badges with icons
57+
- Editable input cells
58+
- Dropdown selectors
59+
- Action menus
60+
- Clickable links
61+
62+
8. **Theme Integration**
63+
- Custom CSS theme matching ObjectOS design system
64+
- Dark mode support via `ag-theme-alpine-dark`
65+
- Tailwind CSS variable integration
66+
67+
## Usage
68+
69+
### Basic DataTable Component
70+
71+
```tsx
72+
import { DataTable, schema } from '@objectos/ui';
73+
import { z } from 'zod';
74+
75+
const sampleData: z.infer<typeof schema>[] = [
76+
{
77+
id: 1,
78+
header: "Example",
79+
type: "Type",
80+
status: "Done",
81+
target: "10",
82+
limit: "15",
83+
reviewer: "John Doe",
84+
},
85+
// ... more rows
86+
];
87+
88+
function MyComponent() {
89+
return <DataTable data={sampleData} />;
90+
}
91+
```
92+
93+
### Custom AG Grid Table
94+
95+
```tsx
96+
import { AgGridTable } from '@objectos/ui';
97+
// Use the same schema and data
98+
```
99+
100+
## File Structure
101+
102+
```
103+
packages/ui/src/
104+
├── components/
105+
│ ├── data-table.tsx # Main DataTable component (AG Grid)
106+
│ ├── ag-grid-table.tsx # Alternative export name
107+
│ └── data-table-old.tsx # Backup of TanStack implementation
108+
├── styles/
109+
│ └── ag-grid-theme.css # Custom AG Grid theme
110+
└── styles.css # Imports AG Grid theme
111+
```
112+
113+
## Theme Customization
114+
115+
The AG Grid theme is customized in `packages/ui/src/styles/ag-grid-theme.css` to match the ObjectOS design system:
116+
117+
```css
118+
.ag-theme-alpine-dark {
119+
--ag-background-color: hsl(var(--background));
120+
--ag-foreground-color: hsl(var(--foreground));
121+
--ag-header-background-color: hsl(var(--muted));
122+
/* ... more variables */
123+
}
124+
```
125+
126+
## Advanced Features (Available)
127+
128+
AG Grid v35 provides many advanced features that can be enabled:
129+
130+
### 1. Server-Side Row Model
131+
For handling large datasets with server-side pagination, sorting, and filtering.
132+
133+
### 2. Column Grouping
134+
Group related columns together with expandable headers.
135+
136+
### 3. Row Grouping & Aggregation
137+
Group rows by column values and show aggregated data.
138+
139+
### 4. Context Menu
140+
Custom right-click menu for rows and cells.
141+
142+
### 5. Cell Editing
143+
Built-in editors for different data types.
144+
145+
### 6. Export
146+
Export to CSV/Excel (enterprise feature).
147+
148+
## Migration Checklist for Developers
149+
150+
If you're updating a component to use AG Grid:
151+
152+
- [ ] Replace TanStack Table imports with AG Grid imports
153+
- [ ] Convert column definitions to `ColDef[]` format
154+
- [ ] Update cell renderers to AG Grid's `ICellRendererParams` interface
155+
- [ ] Replace `useReactTable` hook with AG Grid's `AgGridReact` component
156+
- [ ] Update event handlers (e.g., `onRowClicked` → `onCellClicked`)
157+
- [ ] Remove @dnd-kit dependencies if only used for table drag-drop
158+
- [ ] Test pagination, sorting, and filtering
159+
- [ ] Verify theme matches design system
160+
161+
## Performance Benefits
162+
163+
1. **Virtual Scrolling**: Only renders visible rows
164+
2. **Efficient Updates**: Smart change detection
165+
3. **Optimized Filtering**: Built-in filter caching
166+
4. **Better Memory Management**: Recycles DOM nodes
167+
168+
## Known Limitations
169+
170+
1. **Bundle Size**: AG Grid adds ~500KB to the bundle (but removes @dnd-kit and TanStack Table)
171+
2. **Learning Curve**: Different API than TanStack Table
172+
3. **Enterprise Features**: Some features require AG Grid Enterprise license
173+
174+
## Resources
175+
176+
- [AG Grid Documentation](https://www.ag-grid.com/react-data-grid/)
177+
- [AG Grid v35 Release Notes](https://www.ag-grid.com/changelog/)
178+
- [Column Properties](https://www.ag-grid.com/react-data-grid/column-properties/)
179+
- [Cell Renderers](https://www.ag-grid.com/react-data-grid/component-cell-renderer/)
180+
181+
## Support
182+
183+
For questions or issues:
184+
1. Check AG Grid docs
185+
2. Review the implementation in `packages/ui/src/components/data-table.tsx`
186+
3. Create an issue in the ObjectOS repository

‎docs/AG_GRID_MIGRATION_CN.md‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
# AG Grid 迁移指南 (中文版)
2+
3+
## 概述
4+
5+
我们已成功将前端表格组件从 TanStack Table 迁移到 AG Grid (v35.0.0)。AG Grid 提供企业级功能，具有更好的性能和开箱即用的全面功能。
6+
7+
## 变更内容
8+
9+
### 之前 (TanStack Table)
10+
- 需要手动实现分页、排序、过滤
11+
- 使用 @dnd-kit 库进行自定义拖放
12+
- 内置功能有限
13+
- 需要更多样板代码
14+
15+
### 之后 (AG Grid)
16+
- 内置分页、排序、过滤
17+
- 原生行拖动和列调整大小
18+
- 高级功能如行分组、聚合（企业版可用）
19+
- 更少的代码，更多的功能
20+
21+
## 已实现的功能
22+
23+
### ✅ 核心功能
24+
25+
1. **行选择**
26+
- 基于复选框的多行选择
27+
- 标题复选框用于全选/取消全选
28+
- 使用我们的 UI 组件的自定义复选框渲染器
29+
30+
2. **排序**
31+
- 点击列标题进行排序
32+
- 支持多列排序
33+
- 自定义排序指示器
34+
35+
3. **过滤**
36+
- 内置列过滤器
37+
- 快速过滤（跨所有列搜索）
38+
- 自定义过滤器 UI 集成
39+
40+
4. **分页**
41+
- 自定义分页控件（隐藏 AG Grid 默认值）
42+
- 可配置页面大小（10、20、30、40、50）
43+
- 首页/上一页/下一页/末页导航
44+
45+
5. **拖放**
46+
- 通过拖动手柄重新排序行
47+
- 拖动期间的视觉反馈
48+
- 由 AG Grid 内部管理
49+
50+
6. **列管理**
51+
- 列可见性切换
52+
- 列大小调整
53+
- 需要时固定列宽
54+
55+
7. **自定义单元格渲染器**
56+
- 带图标的状态徽章
57+
- 可编辑输入单元格
58+
- 下拉选择器
59+
- 操作菜单
60+
- 可点击链接
61+
62+
8. **主题集成**
63+
- 与 ObjectOS 设计系统匹配的自定义 CSS 主题
64+
- 通过 `ag-theme-alpine-dark` 支持深色模式
65+
- Tailwind CSS 变量集成
66+
67+
## 使用方法
68+
69+
### 基本 DataTable 组件
70+
71+
```tsx
72+
import { DataTable, schema } from '@objectos/ui';
73+
import { z } from 'zod';
74+
75+
const sampleData: z.infer<typeof schema>[] = [
76+
{
77+
id: 1,
78+
header: "示例",
79+
type: "类型",
80+
status: "完成",
81+
target: "10",
82+
limit: "15",
83+
reviewer: "张三",
84+
},
85+
// ... 更多行
86+
];
87+
88+
function MyComponent() {
89+
return <DataTable data={sampleData} />;
90+
}
91+
```
92+
93+
### 自定义 AG Grid 表格
94+
95+
```tsx
96+
import { AgGridTable } from '@objectos/ui';
97+
// 使用相同的 schema 和数据
98+
```
99+
100+
## 文件结构
101+
102+
```
103+
packages/ui/src/
104+
├── components/
105+
│ ├── data-table.tsx # 主 DataTable 组件 (AG Grid)
106+
│ ├── ag-grid-table.tsx # 备用导出名称
107+
│ └── data-table-old.tsx # TanStack 实现的备份
108+
├── styles/
109+
│ └── ag-grid-theme.css # 自定义 AG Grid 主题
110+
└── styles.css # 导入 AG Grid 主题
111+
```
112+
113+
## 主题定制
114+
115+
AG Grid 主题在 `packages/ui/src/styles/ag-grid-theme.css` 中定制，以匹配 ObjectOS 设计系统：
116+
117+
```css
118+
.ag-theme-alpine-dark {
119+
--ag-background-color: hsl(var(--background));
120+
--ag-foreground-color: hsl(var(--foreground));
121+
--ag-header-background-color: hsl(var(--muted));
122+
/* ... 更多变量 */
123+
}
124+
```
125+
126+
## 高级功能（可用）
127+
128+
AG Grid v35 提供许多可以启用的高级功能：
129+
130+
### 1. 服务器端行模型
131+
用于处理大型数据集，支持服务器端分页、排序和过滤。
132+
133+
### 2. 列分组
134+
将相关列组合在一起，带有可展开的标题。
135+
136+
### 3. 行分组和聚合
137+
按列值对行进行分组并显示聚合数据。
138+
139+
### 4. 上下文菜单
140+
为行和单元格提供自定义右键菜单。
141+
142+
### 5. 单元格编辑
143+
为不同数据类型提供内置编辑器。
144+
145+
### 6. 导出
146+
导出到 CSV/Excel（企业功能）。
147+
148+
## 开发者迁移清单
149+
150+
如果您要更新组件以使用 AG Grid：
151+
152+
- [ ] 将 TanStack Table 导入替换为 AG Grid 导入
153+
- [ ] 将列定义转换为 `ColDef[]` 格式
154+
- [ ] 将单元格渲染器更新为 AG Grid 的 `ICellRendererParams` 接口
155+
- [ ] 将 `useReactTable` 钩子替换为 AG Grid 的 `AgGridReact` 组件
156+
- [ ] 更新事件处理程序（例如，`onRowClicked` → `onCellClicked`）
157+
- [ ] 如果仅用于表格拖放，则移除 @dnd-kit 依赖项
158+
- [ ] 测试分页、排序和过滤
159+
- [ ] 验证主题是否匹配设计系统
160+
161+
## 性能优势
162+
163+
1. **虚拟滚动**：仅渲染可见行
164+
2. **高效更新**：智能变更检测
165+
3. **优化过滤**：内置过滤缓存
166+
4. **更好的内存管理**：回收 DOM 节点
167+
168+
## 已知限制
169+
170+
1. **打包大小**：AG Grid 增加约 500KB 到打包文件（但移除了 @dnd-kit 和 TanStack Table）
171+
2. **学习曲线**：与 TanStack Table 不同的 API
172+
3. **企业功能**：某些功能需要 AG Grid Enterprise 许可证
173+
174+
## 资源
175+
176+
- [AG Grid 文档](https://www.ag-grid.com/react-data-grid/)
177+
- [AG Grid v35 发布说明](https://www.ag-grid.com/changelog/)
178+
- [列属性](https://www.ag-grid.com/react-data-grid/column-properties/)
179+
- [单元格渲染器](https://www.ag-grid.com/react-data-grid/component-cell-renderer/)
180+
181+
## 支持
182+
183+
如有问题或疑问：
184+
1. 查看 AG Grid 文档
185+
2. 查看 `packages/ui/src/components/data-table.tsx` 中的实现
186+
3. 在 ObjectOS 仓库中创建问题

0 commit comments

Comments
 (0)