c-snap

c-snap 是一个基于 Puppeteer 的命令行工具，旨在通过 Node.js 后端运行前端绘图逻辑，从而实现在服务端自动化生成图像。这使得原本依赖浏览器的前端可视化能力也能在后端使用，例如导出图表、绘图组件快照等。

A headless chart rendering CLI for ECharts and custom canvas functions using Puppeteer.

📦 安装

npm install -g c-snap

或作为项目依赖：

npm install c-snap --save-dev

安装成功后将获得 CLI 命令 c-snap。

💡 若在 Linux 或 Docker 中遇到安装/运行问题，请查看下方 兼容性说明。

🚀 使用指南

1. 渲染 ECharts 图表

支持 Echarts 的所有图标参数，包括在 .js 文件中配置函数（如 formatter）。

c-snap echarts -i option.json -o chart.png --width 1024 --height 768

# 1. 从 JSON 文件渲染图表
c-snap echarts -i option.json -o sales-chart.png --width 1024 --height 768

# 2. 从 JS 文件渲染图表（支持 ECharts 配置中的函数，如 formatter）
c-snap echarts -i option.js -o chart.svg --renderer svg

# 3. 输出 Base64 编码
c-snap echarts -i option.json --base64 > chart.base64.txt

# 4. 输出 SVG 图像
c-snap echarts -i option.json --renderer svg -o chart.svg

# 5. 传入内联 JSON 字符串
c-snap echarts -i '{"title":{"text":"Demo"},"xAxis":{"data":["A","B"]},"yAxis":{},"series":[{"type":"bar","data":[10,20]}]}' -o demo.png

此命令使用无头浏览器渲染 ECharts 配置项并导出图像。

📌 .json 文件格式说明

如果您的 ECharts 配置项为 JSON 格式，请使用 .json 文件作为输入。 .json文件就是echarts的配置项，可以直接使用。

option.json 示例：

{
  "title": {
    "text": "温度",
    "left": "center"
  },
  "tooltip": {
    "trigger": "axis"
  },
  "grid": {
    "left": "10%",
    "right": "10%",
    "bottom": "15%",
    "containLabel": true
  },
  "xAxis": {
    "type": "category",
    "boundaryGap": false,
    "data": [
      "2025-05-12 11:10:00",
      "2025-05-12 12:10:00",
      "2025-05-12 13:10:00",
      "2025-05-12 14:10:00",
      "2025-05-12 15:10:00",
      "2025-05-12 16:10:00",
      "2025-05-12 17:10:00",
      "2025-05-12 18:10:00"
    ],
    "axisLabel": {
      "interval": 0,
      "rotate": 45
    }
  },
  "yAxis": {
    "type": "value",
    "min": 0,
    "max": 30
  },
  "series": [
    {
      "name": "温度",
      "type": "line",
      "data": [
        25,
        25,
        25,
        25,
        25,
        25,
        25,
        25
      ],
      "label": {
        "show": true
      },
      "lineStyle": {
        "width": 2
      },
      "showSymbol": true
    }
  ]
}

📌 .js 文件格式特别说明（支持函数）

如果您的 ECharts 配置需要包含 JavaScript 函数（如 formatter、label.formatter 等），请使用 .js 文件作为输入。

为了让 c-snap 在 Node.js 服务端读取您的配置，并将其安全地注入到浏览器环境中执行，您的 .js 文件必须遵循标准的 Node.js 模块导出规范：

• 必须使用 module.exports 导出最终的 ECharts 配置对象 (option)。
• 配置对象内部可以自由地使用 JavaScript 函数和变量。

option.js 示例：

// option.js

// 1. 定义动态值和函数
const seriesValue = 0.85;

// 2. 定义配置对象，包含函数
const option = {
  title: {
    text: '使用 JS 文件格式化',
    subtext: '支持自定义函数'
  },
  tooltip: {
    trigger: 'item',
    // 示例：使用函数定义 toolTip 格式
    formatter: function (params) {
      return params.name + '的销量: ' + params.value;
    }
  },
  xAxis: {
    data: ['衬衫', '羊毛衫', '裤子']
  },
  yAxis: {},
  series: [
    {
      name: '销量',
      type: 'bar',
// 示例：使用变量
      data: [seriesValue, 0.5, 0.2]
    }
  ]
};

// 3. 【必须】使用 module.exports 导出配置对象
module.exports = option;

📌 参数说明

| Flag | Description | Default | | -------------- | ------------------------------------------------------ | ------------ | | -i, --input | Path to JSON file or JSON string of the ECharts option | (required) | | -o, --output | Output file path (PNG) | output.png | | --width | Chart viewport width in pixels | 800 | | --height | Chart viewport height in pixels | 600 | | --base64 | Output Base64 string to stdout instead of file | false | | --renderer | Rendering mode: canvas or svg | canvas | | -h, --help | Show help | |

2. 执行自定义绘图函数

c-snap diy <functionName> -i params.json -o result.png

示例：

c-snap diy drawProgressWithIcon -i data.json -o bar.png

📌 通用参数说明

| 参数 | 说明 | |------------------| -------------------------------------- | | <functionName> | 执行的全局函数名（目前仅支持 drawProgressWithIcon） | | -i, --input | JSON 字符串或 JSON 文件路径，作为绘图函数参数 | | -o, --output | 输出图片路径（默认 output.png） | | --width | 画布宽度（默认 800） | | --base64 | 是否输出为 base64 字符串（用于接口对接或数据嵌入） |

🎨 drawProgressWithIcon 函数说明

该函数用于绘制带图标的进度条列表，支持背景条、内外圆、文本与图标组合。

效果如下：

调用格式：

window.drawProgressWithIcon({ dataList: [...], option: {...} })

参数结构：

• dataList：数组，每项为一个进度条对象，支持以下字段：

  • percent (number)：进度百分比，0-100。
  • text (string)：显示的文本，默认 ${percent}%。
  • barColor (string)：进度条颜色，默认 #006d8d。
  • textColor (string)：文本颜色，默认 #fff。
  • textPos (string)：文本位置，可为 inner 或 end，默认 inner。
  • img (string)：图标路径（支持 base64 或本地绝对路径，会自动转为 base64）。

• option：通用样式设置：

  • bg (string)：进度条背景颜色，默认 #e0e0e0。
  • dataItemHeight (number)：每一行的高度，默认 80。

示例参数（data.json）：

{
  "option": {
    "bg": "#eeeeee",
    "dataItemHeight": 60
  },
  "dataList": [
    {
      "percent": 80,
      "text": "任务完成",
      "barColor": "#4caf50",
      "textColor": "#fff",
      "img": "/absolute/path/to/icon.png"
    },
    {
      "percent": 60,
      "text": "下载中",
      "barColor": "#2196f3",
      "textPos": "end",
      "img": "data:image/png;base64,iVBORw0KGgoAAA..."
    }
  ]
}

✅ 本地图片路径将自动转换为 base64，以避免 Canvas 安全污染。

⚙️ Linux & Docker 使用指南

在 Linux 或 Docker 容器中运行时，puppeteer 可能因无法自动下载 Chromium 或缺少依赖而运行失败。

✅ 推荐方案：使用系统 Chromium + 设置环境变量

# 安装 Chromium
sudo apt update && sudo apt install -y chromium

# 跳过 Chromium 下载
export PUPPETEER_SKIP_DOWNLOAD=true

# 指定 Chromium 路径
export CHROMIUM_PATH=/usr/bin/chromium

# 然后安装 c-snap
npm install -g c-snap

✅ Dockerfile 示例

FROM node:18

# 安装系统 Chromium
RUN apt update && apt install -y chromium fonts-noto-cjk

# 设置 Puppeteer 环境变量
ENV PUPPETEER_SKIP_DOWNLOAD=true
ENV CHROMIUM_PATH=/usr/bin/chromium
ENV PATH="/usr/local/bin:${PATH}"

# 安装 c-snap
RUN npm install -g c-snap --registry=https://registry.npmmirror.com

CMD ["c-snap", "--help"]

💡 建议安装字体包（如 fonts-noto-cjk），以支持中文文本渲染。

❗ 常见问题

| 问题 | 解决方法 | | --------------------------- | ------------------------------------------------- | | c-snap: command not found | 添加 ENV PATH="/usr/local/bin:$PATH" 到 Dockerfile | | Failed to launch browser | 设置 CHROMIUM_PATH 并确保已安装系统浏览器 | | 图中文字乱码或缺字 | 安装字体：如 fonts-noto-cjk、fontconfig |