data-chart-tool/README.md

# 📊 数据可视化图表生成器

一个简洁强大的数据可视化工具，支持 **Web UI** 和 **API** 两种方式生成精美的对比图表和表格图片。

![License](https://img.shields.io/badge/license-MIT-blue.svg)
![Version](https://img.shields.io/badge/version-1.8.0-green.svg)

## ✨ 功能特性

### 📈 图表类型
- **柱状图** - 支持单系列/多系列对比
- **折线图** - 支持平滑曲线、面积填充
- **混合图** - 柱状图+折线图组合展示

### 📋 表格功能
- **表格图片生成** - 根据数据生成精美的表格图片
- **多种主题** - 与图表共享5种主题风格
- **自定义样式** - 字体大小、斑马纹、边框等可配置
- **中文支持** - 完美支持中文内容显示

### 🎨 自定义配置
- **主题风格** - 5种预设主题（默认/深色/马卡龙/渐变/复古）
- **颜色自定义** - 每个系列可单独设置颜色
- **顺序调整** - 拖拽即可调整系列显示顺序（Web UI）
- **显示选项** - 图例、网格线、数据标签、堆叠模式等

### 📐 区域分割
- 支持左右区域分割，适合对比分析（如：2023年 vs 2024年）
- 可自定义分割线样式（实线/虚线/点线）
- 自动标注左右区域标签

### 🖼️ 双图合并
- 将两张图表合并到一张图片中，适合对比/汇总场景
- 支持**横排（左右并排）** 和 **竖排（上下堆叠）**，一键切换实时预览
- 两张图可独立配置：数据、标题、图表类型、主题、图例/网格/标签/堆叠
- 支持导出 PNG

### 📡 API 接口
- **POST /api/chart** - JSON 请求体生成图表（完整参数支持）
- **GET /api/chart** - URL 参数生成图表（简单场景）
- **POST /api/table** - JSON 请求体生成表格图片
- **GET /api/table** - URL 参数生成表格图片
- **POST /api/combine** - 双图合并（横排/竖排）生成一张图片
- 返回 PNG 图片，支持自定义分辨率和像素倍率

### 📥 导出功能
- 导出设置：分辨率预设（原始/1920×1080/1280×720/1024×768/800×600/自定义）
- 自定义分辨率手动输入，页面实时居中预览保存后的图
- 分辨率历史记忆（最近5个，localStorage 持久化，一键复用）
- 文件名默认按日期时间自动命名（每次不同），支持手动命名
- Web UI 导出 PNG / 图表模式支持 SVG
- API 直接返回 PNG 图片流

## 🚀 快速开始

### 启动服务

```bash
cd data-chart-tool
npm install
npm start
# 或
node server.js
```

服务默认运行在 `16016` 端口，可通过环境变量修改：

```bash
PORT=8080 node server.js
```

### Web UI

浏览器访问 `http://localhost:16016` 即可使用可视化界面。

### API 调用

#### POST 方式（推荐）

```bash
curl -X POST http://localhost:16016/api/chart \
  -H "Content-Type: application/json" \
  -d '{
    "data": "产品, Q1, Q2, Q3, Q4\n手机, 1200, 1800, 2100, 2500\n平板, 800, 950, 1100, 1300",
    "chartType": "bar",
    "title": "季度销售对比",
    "theme": "default",
    "width": 800,
    "height": 500
  }' -o chart.png
```

#### GET 方式

```bash
curl "http://localhost:16016/api/chart?data=产品,Q1,Q2\n手机,100,200\n平板,150,250&type=bar&title=测试" -o chart.png
```

#### Python 调用示例

```python
import requests

resp = requests.post('http://localhost:16016/api/chart', json={
    "data": "月份, 营收, 利润\n1月, 500, 80\n2月, 680, 120\n3月, 820, 160",
    "chartType": "line",
    "title": "增长趋势",
    "theme": "dark",
    "showLabel": True,
    "width": 900,
    "height": 500
})

with open('chart.png', 'wb') as f:
    f.write(resp.content)
```

### 生成表格图片

#### POST 方式

```bash
curl -X POST http://localhost:16016/api/table \
  -H "Content-Type: application/json" \
  -d '{
    "data": "姓名, 部门, 职位, 薪资\n张三, 技术部, 工程师, 15000\n李四, 产品部, 产品经理, 18000\n王五, 设计部, UI设计师, 16000",
    "title": "员工信息表",
    "theme": "default"
  }' -o table.png
```

#### GET 方式

```bash
curl "http://localhost:16016/api/table?data=产品,价格,库存\n手机,2999,100\n平板,1999,50&title=产品列表" -o table.png
```

## 📡 API 文档

### POST /api/chart

通过 JSON 请求体生成图表图片。

**请求参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| data | string | ✅ | - | CSV 格式数据（`\n` 换行，第一行表头，第一列横坐标） |
| chartType | string | - | bar | 图表类型：`bar` / `line` / `bar-line` |
| title | string | - | "" | 图表标题 |
| theme | string | - | default | 主题：`default` / `dark` / `macarons` / `gradient` / `retro` |
| showLegend | boolean | - | true | 是否显示图例 |
| showGrid | boolean | - | true | 是否显示网格线 |
| showLabel | boolean | - | false | 是否显示数据标签 |
| stackMode | boolean | - | false | 是否堆叠模式 |
| smoothLine | boolean | - | true | 折线图是否平滑 |
| enableSplit | boolean | - | false | 是否启用区域分割 |
| splitIndex | number | - | 3 | 分割位置索引 |
| leftLabel | string | - | "左侧" | 左侧区域标签 |
| rightLabel | string | - | "右侧" | 右侧区域标签 |
| splitStyle | string | - | "solid" | 分割线样式：`solid` / `dashed` / `dotted` |
| width | number | - | 800 | 图片宽度(px) |
| height | number | - | 500 | 图片高度(px) |
| pixelRatio | number | - | 2 | 像素倍率（清晰度） |

**返回：** `image/png` 二进制流

### GET /api/chart

通过 URL 参数生成图表（适合简单场景）。

| 参数 | 说明 |
|------|------|
| data | CSV 数据（换行用 `\n` 表示） |
| type | 图表类型 |
| title | 图表标题 |
| theme | 主题风格 |
| width | 图片宽度 |
| height | 图片高度 |

### POST /api/table

通过 JSON 请求体生成表格图片。

**请求参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| data | string | ✅ | - | CSV 格式数据（`\n` 换行，第一行表头） |
| title | string | - | "" | 表格标题 |
| theme | string | - | default | 主题：`default` / `dark` / `macarons` / `gradient` / `retro` |
| fontSize | number | - | 14 | 字体大小 |
| cellPadding | number | - | 12 | 单元格内边距 |
| borderWidth | number | - | 1 | 边框宽度 |
| stripeRows | boolean | - | true | 是否斑马纹 |
| pixelRatio | number | - | 2 | 像素倍率（清晰度） |
| maxWidth | number | - | 1200 | 最大宽度(px) |

**返回：** `image/png` 二进制流

### GET /api/table

通过 URL 参数生成表格图片。

| 参数 | 说明 |
|------|------|
| data | CSV 数据（换行用 `\n` 表示） |
| title | 表格标题 |
| theme | 主题风格 |
| fontSize | 字体大小 |
| stripeRows | 是否斑马纹 |

### GET /api/health

健康检查，返回服务状态。

### GET /api/docs

返回 API 文档（JSON 格式）。

## 📝 数据格式

第一行为**表头**（系列名称），第一列为**横坐标值**，支持逗号、制表符分隔：

```
类别, 系列1, 系列2, 系列3
A, 10, 20, 30
B, 15, 25, 35
C, 20, 30, 40
```

## 🛠️ 技术栈

- **ECharts 5.5.0** - 图表渲染引擎
- **@napi-rs/canvas** - Node.js 服务端 Canvas 渲染
- **Express** - Web 服务框架
- **原生 HTML/CSS/JS** - 前端无框架依赖

## 📁 项目结构

```
data-chart-tool/
├── server.js       # Node.js 后端（API 服务）
├── app.js          # 前端核心逻辑
├── index.html      # Web UI 主页面
├── style.css       # 样式文件
├── package.json    # 依赖管理
└── README.md       # 项目说明
```

## 🔧 开发计划

- [x] 支持 API 生成图表图片
- [x] 支持表格图片生成
- [ ] 支持饼图、雷达图等更多图表类型
- [ ] 支持从 Excel/CSV 文件导入
- [ ] 支持数据编辑和实时预览
- [ ] 添加更多主题风格
- [ ] 支持图表模板保存和分享
- [ ] 支持 SVG 格式服务端导出

## 📄 License

MIT License

---

Made with ❤️ by 黄庄4号程序员