hz4th_coder
e62aac539b
- 后端新增 POST /api/combine 接口（chart1/chart2 + direction/gap/pixelRatio/background）
- 前端新增 🖼️ 双图合并模式：两张图独立配置数据/标题/类型/主题
- 横排（左右等高三张图）或竖排（上下等宽），一键切换实时预览
- 修复 @napi-rs/canvas echarts 渲染需先 toBuffer 再 dispose 的关键问题
- 更新 README/API 文档
265 lines
7.6 KiB
Markdown
265 lines
7.6 KiB
Markdown
# 📊 数据可视化图表生成器
|
||
|
||
一个简洁强大的数据可视化工具，支持 **Web UI** 和 **API** 两种方式生成精美的对比图表和表格图片。
|
||
|
||
|
||
|
||
|
||
## ✨ 功能特性
|
||
|
||
### 📈 图表类型
|
||
- **柱状图** - 支持单系列/多系列对比
|
||
- **折线图** - 支持平滑曲线、面积填充
|
||
- **混合图** - 柱状图+折线图组合展示
|
||
|
||
### 📋 表格功能
|
||
- **表格图片生成** - 根据数据生成精美的表格图片
|
||
- **多种主题** - 与图表共享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 图片，支持自定义分辨率和像素倍率
|
||
|
||
### 📥 导出功能
|
||
- Web UI 导出 PNG（2倍分辨率）
|
||
- 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号程序员
|