feat: 添加 API 接口支持服务端生成图表图片

- 新增 Node.js + Express 后端服务 (server.js) - POST /api/chart: JSON 请求体生成图表 PNG - GET /api/chart: URL 参数生成图表 PNG - 支持所有前端配置参数(图表类型/主题/标签/堆叠/分割等) - 使用 @napi-rs/canvas + echarts 服务端渲染 - 自定义分辨率和像素倍率 - 添加 /api/health 和 /api/docs 接口 - 更新 README 文档，添加 API 使用说明
2026-07-16 11:33:39 +08:00
parent ad3e74e391
commit d4ce91efd1
5 changed files with 1773 additions and 51 deletions
@@ -1,9 +1,9 @@
 # 📊 数据可视化图表生成器

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

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

 ## ✨ 功能特性

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

 ### 📐 区域分割
@@ -23,37 +23,132 @@
 - 可自定义分割线样式（实线/虚线/点线）
 - 自动标注左右区域标签

+### 📡 API 接口
+- **POST /api/chart** - JSON 请求体生成图表（完整参数支持）
+- **GET /api/chart** - URL 参数生成图表（简单场景）
+- 返回 PNG 图片，支持自定义分辨率和像素倍率
+
 ### 📥 导出功能
- 导出为 PNG（2倍分辨率）
- 导出为 SVG（矢量格式）
+- Web UI 导出 PNG（2倍分辨率）
+- API 直接返回 PNG 图片流

 ## 🚀 快速开始

-### 本地运行
+### 启动服务

 ```bash
-# 克隆仓库
-git clone http://121.40.164.32:12007/hz4th_coder/data-chart-tool.git
-
-# 进入目录
 cd data-chart-tool
-
-# 启动本地服务器（任选其一）
-python3 -m http.server 8080
+npm install
+npm start
 # 或
-npx serve
+node server.js
 ```

-浏览器访问 `http://localhost:8080` 即可使用。
+服务默认运行在 `16023` 端口，可通过环境变量修改：

-### 在线使用
+```bash
+PORT=8080 node server.js
+```

-已部署在内部服务器：http://192.168.0.101:16023
+### Web UI
+
+浏览器访问 `http://localhost:16023` 即可使用可视化界面。
+
+### API 调用
+
+#### POST 方式（推荐）
+
+```bash
+curl -X POST http://localhost:16023/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:16023/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:16023/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)
+```
+
+## 📡 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 | 图片高度 |
+
+### GET /api/health
+
+健康检查，返回服务状态。
+
+### GET /api/docs
+
+返回 API 文档（JSON 格式）。

 ## 📝 数据格式

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

 ```
@@ -63,55 +158,34 @@ B, 15, 25, 35
 C, 20, 30, 40
 ```

-### 示例数据
-
-**季度销售对比：**
-```
-产品, Q1, Q2, Q3, Q4
-手机, 1200, 1800, 2100, 2500
-平板, 800, 950, 1100, 1300
-笔记本, 600, 750, 900, 1050
-```
-
-**年度增长趋势：**
-```
-指标, 2020年, 2021年, 2022年, 2023年, 2024年
-营收(万), 500, 680, 820, 1050, 1380
-利润(万), 80, 120, 160, 230, 350
-用户(千), 50, 85, 130, 200, 320
-```
-
-## 🎯 使用场景
-
-| 场景 | 说明 |
-|------|------|
-| 销售数据分析 | 对比不同产品、不同季度的销售表现 |
-| 年度趋势展示 | 展示多年份的指标变化趋势 |
-| 方案对比评估 | 使用区域分割功能对比两个方案 |
-| 团队绩效展示 | 多团队、多指标的综合对比 |
-
 ## 🛠️ 技术栈

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

 ## 📁 项目结构

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

 ## 🔧 开发计划

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

 ## 📄 License