building-tables

构建表格和数据网格

目的

此技能支持系统地创建表格和数据网格，从简单的 HTML 表格到可处理数百万行数据的企业级虚拟化网格。它根据数据量和所需功能提供清晰的决策框架，确保所有实现都具备最佳性能、可访问性和响应式设计。

适用场景

在以下情况下启用此技能：

• 创建表格、数据网格或类似电子表格的界面
• 显示表格或结构化数据
• 实现排序、筛选或分页功能
• 处理大型数据集或解决性能问题
• 构建行内编辑或数据录入界面
• 需要行选择或批量操作
• 实现数据导出（CSV、Excel、PDF）
• 确保表格可访问或具备响应式行为

快速决策框架

根据数据量选择实现层级：

<100 rows        → Simple HTML table with progressive enhancement
100-1,000 rows   → Client-side features (sort, filter, paginate)
1,000-10,000     → Server-side operations with API pagination
10,000-100,000   → Virtual scrolling with windowing
>100,000 rows    → Enterprise grid with streaming and workers

有关详细的选择标准，请参阅 references/selection-framework.md。

核心实现模式

第 1 层：基础表格（<100 行）

适用于简单的只读数据展示：

• 使用语义化 HTML <table> 结构
• 通过 CSS 添加响应式行为
• 如有需要，实现客户端排序
• 有关模式，请参阅 references/basic-tables.md

示例：examples/simple-responsive-table.tsx

第 2 层：交互式表格（100-10K 行）

适用于功能丰富的交互场景：

• 添加筛选、分页和选择功能
• 实现行内编辑或模态编辑
• 对最多 1K 行数据执行客户端操作
• 超过 1K 行时切换为服务端操作
• 请参阅 references/interactive-tables.md

示例：examples/sortable-filtered-table.tsx

第 3 层：高级网格（10K+ 行）

适用于海量数据集：

• 实现虚拟滚动
• 使用服务端聚合
• 添加分组和层级结构
• 考虑企业级解决方案
• 请参阅 references/advanced-grids.md

示例：examples/virtual-scrolling-grid.tsx

性能优化

关键性能阈值：

• 客户端操作：<1,000 行（即时，<50ms）
• 服务端操作：1,000-10,000 行（API 响应时间 <200ms）
• 虚拟滚动：10,000+ 行（60fps，内存占用恒定）
• 流式处理：100,000+ 行（渐进式渲染）

要对性能进行基准测试：

# Generate test data
python scripts/generate_mock_data.py --rows 10000

# Analyze rendering performance
node scripts/analyze_performance.js

有关优化策略，请参阅 references/performance-optimization.md。

功能实现

排序

• 单列或多列排序
• 自定义排序逻辑（数值、日期、自然排序）
• 可视化指示器和键盘支持
• 请参阅 references/sorting-filtering.md

筛选和搜索

• 特定列筛选器（文本、范围、选择）
• 跨所有列的全局搜索
• 高级筛选逻辑（AND/OR）
• 请参阅 references/sorting-filtering.md

分页

• 小型数据集使用客户端分页
• 大型数据集使用服务端分页
• 无限滚动替代方案
• 请参阅 references/pagination-strategies.md

选择和批量操作

• 单行或多行选择
• 范围选择（Shift+单击）
• 批量操作工具栏
• 请参阅 references/selection-patterns.md

行内编辑

• 单元格级或行级编辑
• 验证和错误处理
• 乐观更新
• 请参阅 references/editing-patterns.md

导出

• CSV、Excel、PDF 格式
• 保留格式和编码
• 对大型导出任务进行流式处理
• 运行 scripts/export_table_data.py

可访问性要求

WCAG 合规的基本要求：

• 使用结构恰当的语义化 HTML
• 交互式表格采用 ARIA 网格模式
• 完整的键盘导航
• 屏幕阅读器播报

验证可访问性：

node scripts/validate_accessibility.js

完整要求请参阅 references/accessibility-patterns.md。

响应式设计

四种经过验证的策略：

1. 水平滚动 - 简单且能保留结构
2. 卡片堆叠 - 在移动设备上将行转换为卡片
3. 优先级列 - 隐藏不太重要的列
4. 截断并展开 - 默认紧凑显示，按需查看详情

实现方式请参阅 examples/responsive-patterns.tsx。 详情请参阅 references/responsive-strategies.md。

库推荐

首选：TanStack Table（无头）

最适合自定义设计和完全掌控：

• 以 TypeScript 为先，开发体验出色
• 包体积小（约 15KB）
• 与框架无关
• 支持虚拟滚动

npm install @tanstack/react-table

设置方法请参阅 examples/tanstack-basic.tsx。

企业级：AG Grid

最适合功能齐全的解决方案：

• 可处理数百万行
• 内置高级功能
• 社区版（免费）+ 企业版（付费）
• 类似 Excel 的用户体验

npm install ag-grid-react

设置方法请参阅 examples/ag-grid-enterprise.tsx。

详细对比请参阅 references/library-comparison.md。

设计令牌集成

表格使用 design-tokens 技能实现一致的主题：

• 用于背景、边框和状态的颜色令牌
• 用于单元格内边距的间距令牌
• 用于文本样式的排版令牌
• 用于层次效果的阴影令牌

支持浅色、深色、高对比度和自定义主题。 切换主题请参阅 design-tokens 技能。

可运行示例

从符合需求的示例开始：

simple-responsive-table.tsx    # Basic HTML table
sortable-filtered-table.tsx    # With sorting and filtering
paginated-server-table.tsx      # Server-side pagination
virtual-scrolling-grid.tsx      # High-performance for 100K+ rows
editable-data-grid.tsx         # Inline editing with validation
grouped-aggregated-table.tsx   # Hierarchical with aggregations

测试工具

生成测试数据：

python scripts/generate_mock_data.py --rows 100000 --columns 20

基准测试性能：

node scripts/analyze_performance.js --rows 10000

验证无障碍性：

node scripts/validate_accessibility.js

后续步骤

1. 确定数据量和功能需求
2. 选择合适的实现层级
3. 在 TanStack Table（灵活性）和 AG Grid（功能）之间做出选择
4. 从相应的示例文件开始
5. 逐步实现核心功能
6. 测试性能和无障碍性
7. 为移动设备应用响应式策略