# ldesign-pivot-table

**Repository Path**: ldesign-v1/ldesign-pivot-table

## Basic Information

- **Project Name**: ldesign-pivot-table
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-11
- **Last Updated**: 2026-04-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# @ldesign/pivot-table

数据透视表核心模块 - 多维数据分析、聚合、交叉分析

## 📋 项目简介

`@ldesign/pivot-table` 是一个功能完整的数据透视表核心库。它提供了多维数据分析、多种聚合函数、动态数据透视、高性能渲染等功能，适用于商业智能(BI)系统、数据分析平台、报表系统等场景。

## ✨ 核心特性

### 📊 数据分析
- **多维度分析** - 支持多行、多列维度组合
- **聚合函数** - 7种内置聚合函数（求和、计数、平均值、最大值、最小值、中位数、去重计数）
- **交叉分析** - 行列交叉透视分析
- **动态透视** - 拖拽调整维度，实时更新结果

### 🔍 数据处理
- **排序功能** - 支持列头排序（升序/降序）
- **过滤功能** - 支持字段值过滤
- **数据格式化** - 支持自定义值格式化
- **合计功能** - 行合计、列合计、总计

### 🎨 界面与交互
- **主题切换** - 亮色/暗色主题
- **斑马纹** - 可选的行斑马纹效果
- **事件系统** - 单元格点击、排序变化等事件
- **响应式设计** - 自适应容器大小

### ⚡ 性能优化
- **虚拟滚动** - 支持大数据量（10万+行）
- **增量计算** - 数据变化时增量更新
- **内存优化** - 智能内存管理

## 🚀 快速开始

### 安装

```bash
# 使用npm
npm install @ldesign/pivot-table

# 使用pnpm
pnpm add @ldesign/pivot-table

# 使用yarn
yarn add @ldesign/pivot-table
```

### 基础使用

```typescript
import { createPivotTable } from '@ldesign/pivot-table'

// 创建数据透视表实例
const pivotTable = createPivotTable({
  container: '#pivot-table',
  data: [
    { region: '华东', product: '手机', quarter: 'Q1', sales: 1000, profit: 200 },
    { region: '华东', product: '电脑', quarter: 'Q1', sales: 2000, profit: 400 },
    { region: '华北', product: '手机', quarter: 'Q1', sales: 800, profit: 160 },
    { region: '华东', product: '手机', quarter: 'Q2', sales: 1200, profit: 240 },
    { region: '华北', product: '电脑', quarter: 'Q2', sales: 1500, profit: 300 },
  ],
  rows: ['region'],
  columns: ['product'],
  values: [
    { field: 'sales', aggregator: 'sum', label: '销售额' },
    { field: 'profit', aggregator: 'sum', label: '利润' },
  ],
  theme: 'light',
  showRowTotals: true,
  showColTotals: true,
  sortable: true,
  striped: true,
})
```

### 事件监听

```typescript
// 单元格点击事件
pivotTable.on('cell-click', (cellInfo) => {
  console.log('点击单元格：', cellInfo)
  console.log('行维度：', cellInfo.rowKeys)
  console.log('列维度：', cellInfo.colKeys)
  console.log('单元格值：', cellInfo.value)
  console.log('原始数据：', cellInfo.records)
})

// 排序变化事件
pivotTable.on('sort-change', (sortConfig) => {
  console.log('排序配置变化：', sortConfig)
})

// 数据更新事件
pivotTable.on('data-change', (newData) => {
  console.log('数据已更新：', newData)
})
```

### 数据操作

```typescript
// 更新数据
pivotTable.updateData([
  { region: '华南', product: '平板', sales: 500, profit: 100 },
  { region: '华南', product: '手机', sales: 600, profit: 120 },
])

// 添加数据
pivotTable.appendData([
  { region: '西南', product: '电脑', sales: 800, profit: 160 },
])

// 清空数据
pivotTable.clearData()

// 获取当前数据
const currentData = pivotTable.getData()
```

### 配置更新

```typescript
// 更新行维度
pivotTable.setRows(['region', 'quarter'])

// 更新列维度
pivotTable.setColumns(['product'])

// 更新值字段
pivotTable.setValues([
  { field: 'sales', aggregator: 'avg', label: '平均销售额' },
])

// 切换主题
pivotTable.setTheme('dark')

// 切换聚合函数
pivotTable.setAggregator('sales', 'count')
```

### 导出功能

```typescript
// 导出为CSV
const csv = pivotTable.exportCSV()

// 导出为JSON
const json = pivotTable.exportJSON()

// 导出为Excel（需要xlsx库）
const excelBuffer = await pivotTable.exportExcel()
```

## 📁 项目结构

```
pivot-table/
├── packages/
│   ├── core/                    # 核心库
│   │   ├── src/
│   │   │   ├── index.ts        # 模块入口
│   │   │   ├── core/
│   │   │   │   ├── pivot-table.ts # 数据透视表核心类
│   │   │   │   └── event-emitter.ts # 事件总线
│   │   │   ├── engine/
│   │   │   │   ├── pivot-engine.ts # 透视引擎
│   │   │   │   └── aggregators.ts # 聚合函数
│   │   │   ├── renderer/
│   │   │   │   ├── dom-renderer.ts # DOM渲染器
│   │   │   │   └── style-manager.ts # 样式管理器
│   │   │   ├── theme/
│   │   │   │   ├── theme-manager.ts # 主题管理器
│   │   │   │   └── tokens.ts # 主题令牌
│   │   │   └── types/
│   │   │       └── index.ts # 类型定义
│   │   └── package.json
│   └── vue/                     # Vue组件封装
│       ├── src/
│       └── package.json
├── playground/                  # 演示应用
├── package.json                 # 项目配置
└── README.md                    # 项目文档
```

## 🔧 API 参考

### createPivotTable 函数

```typescript
createPivotTable(config: PivotTableConfig): PivotTableInstance
```

### PivotTable 类

#### 数据操作
- `updateData(data)` - 更新数据
- `appendData(data)` - 添加数据
- `clearData()` - 清空数据
- `getData()` - 获取当前数据

#### 配置操作
- `setRows(fields)` - 设置行维度
- `setColumns(fields)` - 设置列维度
- `setValues(fields)` - 设置值字段
- `setAggregator(field, aggregator)` - 设置聚合函数
- `setTheme(theme)` - 设置主题

#### 导出功能
- `exportCSV()` - 导出为CSV
- `exportJSON()` - 导出为JSON
- `exportExcel()` - 导出为Excel

#### 事件与销毁
- `on(event, handler)` - 监听事件
- `off(event, handler)` - 取消事件监听
- `destroy()` - 销毁实例

## 📊 聚合函数

| 函数名 | 说明 | 示例 |
|--------|------|------|
| `sum` | 求和 | `sales: [100, 200, 300] → 600` |
| `count` | 计数 | `sales: [100, 200, 300] → 3` |
| `avg` | 平均值 | `sales: [100, 200, 300] → 200` |
| `min` | 最小值 | `sales: [100, 200, 300] → 100` |
| `max` | 最大值 | `sales: [100, 200, 300] → 300` |
| `median` | 中位数 | `sales: [100, 200, 300] → 200` |
| `countDistinct` | 去重计数 | `sales: [100, 100, 200] → 2` |

## 🎨 主题配置

### 亮色主题
- 背景色：#ffffff
- 表头背景：#f8f9fa
- 边框颜色：#e9ecef
- 文字颜色：#212529
- 合计行背景：#e9ecef

### 暗色主题
- 背景色：#1a1a1e
- 表头背景：#2d2d30
- 边框颜色：#3e3e42
- 文字颜色：#e4e4e7
- 合计行背景：#3e3e42

## 📝 使用场景

1. **商业智能(BI)系统** - 销售数据分析、财务数据分析
2. **数据分析平台** - 多维度数据分析、交叉分析
3. **报表系统** - 动态报表生成、数据汇总
4. **运营分析** - 用户行为分析、转化率分析
5. **库存管理** - 库存周转分析、库存分布分析

## 🔗 相关模块

- `@ldesign/pivot-table-vue` - Vue组件封装
- `@ldesign/table` - 普通表格组件
- `@ldesign/chart` - 图表组件（用于数据可视化）
- `@ldesign/form` - 表单组件（用于数据过滤）

## 📄 许可证

MIT License

## 🤝 贡献指南

欢迎提交Issue和Pull Request。在提交代码前，请确保：

1. 代码符合项目编码规范
2. 添加相应的单元测试
3. 更新相关文档
4. 考虑性能优化（大数据量场景）

## 📞 联系方式

- 项目维护：LDesign Team
- 问题反馈：通过GitHub Issues提交
- 官方文档：[项目Wiki](https://github.com/ldesign/pivot-table/wiki)

---

**注意**：本模块支持大数据量（10万+行），采用虚拟滚动和增量计算技术保证性能。