echarts

# ECharts Build ECharts artifacts that are easy to preview, revise, export, and share in OpenClaw workspaces. Prefer saving actual files over leaving the chart design only in chat. ## Workflow 1. If the user already has an ECharts option object, refine it and run `page`. 2. If the user has structured data in CSV, TSV, or JSON, run `table`. 3. If the user only has a small inline list, run `sample`. 4. If the user needs a static image, either add `--export-image png|svg` during build or run `node {baseDir}/scripts/render-image.mjs --input <artifact-dir> --type png|svg` afterward. `bun` can be used anywhere below where `node` appears. ## Quick Start Quick line or bar chart from inline data: ```bash node {baseDir}/scripts/build.mjs sample --chart line --categories Jan,Feb,Mar,Apr --series Revenue:120,160,210,260 --series Profit:24,30,42,51 --title "Revenue and Profit" --subtitle "Sample series" --out ./artifacts/revenue-profit ``` Generate a chart from a CSV, TSV, or JSON table: ```bash node {baseDir}/scripts/build.mjs table --input ./data/sales.csv --chart bar --x month --y revenue,profit --title "Monthly sales" --page-mode report --out ./artifacts/monthly-sales ``` Build and export a PNG in one step: ```bash node {baseDir}/scripts/build.mjs sample --chart line --categories Jan,Feb,Mar,Apr --series Revenue:120,160,210,260 --title "Quarterly trend" --renderer svg --export-image png --out ./artifacts/quarterly-trend ``` Build and export both PNG and SVG in one run: ```bash node {baseDir}/scripts/build.mjs sample --chart line --categories Jan,Feb,Mar,Apr --series Revenue:120,160,210,260 --title "Quarterly trend" --renderer svg --export-image png --export-image svg --out ./artifacts/quarterly-trend-both ``` Package an existing option file into a standalone preview page: ```bash node {baseDir}/scripts/build.mjs page --option ./option.json --renderer svg --theme paper --title "Release dashboard" --out ./artifacts/release-dashboard ``` Lint an option file before handing it off: ```bash node {baseDir}/scripts/lint-option.mjs ./artifacts/release-dashboard/chart.option.json ``` Export a static image from a generated artifact directory: ```bash node {baseDir}/scripts/render-image.mjs --input ./artifacts/monthly-sales --type png node {baseDir}/scripts/render-image.mjs --input ./artifacts/release-dashboard --type svg ``` ## 中文示例 销售趋势折线图： ```bash node {baseDir}/scripts/build.mjs sample --chart line --categories 1月,2月,3月,4月 --series 销售额:120,168,210,256 --series 毛利:32,45,58,73 --title "月度销售趋势" --subtitle "示例数据" --out ./artifacts/zh-sales-line ``` 值班热力图： ```bash node {baseDir}/scripts/build.mjs sample --chart heatmap --x-categories 周一,周二,周三,周四,周五 --y-categories 上午,下午,晚上 --matrix '4,6,7,5,3;7,8,9,6,5;3,4,6,5,4' --title "客服值班热力图" --out ./artifacts/zh-heatmap ``` 渠道转化桑基图： ```bash node {baseDir}/scripts/build.mjs sample --chart sankey --link "广告>注册:380" --link "自然流量>注册:240" --link "注册>激活:410" --link "激活>付费:126" --title "渠道转化流向" --out ./artifacts/zh-sankey ``` 股票 K 线： ```bash node {baseDir}/scripts/build.mjs sample --chart candlestick --categories 周一,周二,周三,周四 --ohlc '12,15,11,16;15,14,13,17;14,18,13,19;18,17,16,20' --title "示例 K 线" --out ./artifacts/zh-candlestick ``` 团队协作关系图： ```bash node {baseDir}/scripts/build.mjs sample --chart graph --link "产品>设计:8" --link "产品>前端:12" --link "前端>后端:10" --link "后端>运维:6" --node "产品:30:业务" --node "设计:24:设计" --node "前端:28:研发" --node "后端:28:研发" --node "运维:22:平台" --title "团队协作网络" --out ./artifacts/zh-graph ``` 多指标平行坐标： ```bash node {baseDir}/scripts/build.mjs sample --chart parallel --dimensions 响应时间,稳定性,成本,易用性 --series 方案A:88,93,52,74 --series 方案B:72,85,66,91 --series 方案C:64,90,80,69 --title "方案对比" --out ./artifacts/zh-parallel ``` 日历热力图： ```bash node {baseDir}/scripts/build.mjs sample --chart calendar --dates 2026-03-01,2026-03-02,2026-03-03,2026-03-04,2026-03-05,2026-03-06,2026-03-07 --values 12,18,9,20,16,24,14 --title "周活跃日历" --out ./artifacts/zh-calendar ``` 时间流带图： ```bash node {baseDir}/scripts/build.mjs sample --chart themeRiver --dates 2026-03-01,2026-03-02,2026-03-03,2026-03-04 --series 广告:120,140,130,150 --series 自然流量:90,105,115,118 --series 转介绍:30,42,40,46 --title "渠道流量流带图" --out ./artifacts/zh-theme-river ``` 瀑布变化图： ```bash node {baseDir}/scripts/build.mjs sample --chart waterfall --categories 新签,退款,扩容,流失 --values 120,-30,45,-10 --title "净变化瀑布图" --out ./artifacts/zh-waterfall ``` 南北区极坐标柱状图： ```bash node {baseDir}/scripts/build.mjs sample --chart polarBar --categories 华北,华东,华南,西南 --series 营收:120,98,140,110 --title "区域营收极坐标图" --out ./artifacts/zh-polar-bar ``` 玫瑰饼图： ```bash node {baseDir}/scripts/build.mjs sample --chart rosePie --labels 搜索,直接访问,社交,邮件 --values 420,310,180,90 --title "渠道结构玫瑰图" --out ./artifacts/zh-rose-pie ``` ## Artifacts The builder writes a stable file set: - `chart.spec.json`: normalized build request and mappings - `chart.option.json`: ECharts config kept as the source of truth - `chart.data.json`: normalized input rows when source data was provided - `chart.html`: standalone preview and export page - `manifest.json`: small index of generated files and settings - optional exported image such as `<fileBase>.png` or `<fileBase>.svg` Keep `chart.option.json` even when the user only asked for a preview page. It is the easiest artifact to diff, review, and reuse later. Static image exports can be created on demand with `scripts/render-image.mjs` or directly during build with one or more `--export-image` flags, and default to `<fileBase>.png` or `<fileBase>.svg` inside the artifact directory. `manifest.json` keeps single-image compatibility in `files.image`, and records multi-format exports in `files.images`. ## Input Modes ### `sample` Best for quick drafts from short lists. - `bar`, `line`, `area`, `polarBar`: use `--categories` plus one or more `--series Name:1,2,3` - `pictorialBar`: use `--categories` plus one or more `--series Name:1,2,3` - `pie`: use `--labels` plus `--values` - `rosePie`: use `--labels` plus `--values` - `funnel`: use `--labels` plus `--values` - `gauge`: use `--values`, optional `--labels`, optional `--maxes` or shared `--max-value` - `heatmap`: use `--x-categories`, `--y-categories`, and `--matrix` - `waterfall`: use `--categories` and `--values` - `calendar`: use `--dates` and `--values` - `themeRiver`: use `--dates` plus one or more `--series Name:1,2,3` - `candlestick`: use `--categories` and `--ohlc open,close,low,high;...` - `boxplot`: use `--categories` and `--boxes low,q1,median,q3,high;...` - `sankey`: use repeated `--link Source>Target:Value` or a single `--links` list - `graph`: use repeated `--link Source>Target:Value`, with optional repeated `--node Name[:Size[:Group]]` - `tree`: use `--labels`, `--values`, and optional `--parents` - `parallel`: use `--dimensions MetricA,MetricB,...` plus one or more `--series Name:1,2,3` - `radar`: use `--indicators` plus one or more `--series Name:1,2,3` - `treemap`: use `--labels`, `--values`, and optional `--parents` - `sunburst`: use `--labels`, `--values`, and optional `--parents` ### `table` Best for real data files. - `bar`, `line`, `area`, `polarBar`: `--x <field>` and `--y field1,field2` - `pictorialBar`: `--x <field>` and `--y field1,field2` - `pie`: `--label <field>` and `--value <field>` - `rosePie`: `--label <field>` and `--value <field>` - `funnel`: `--label <field>` and `--value <field>` - `gauge`: `--value <field>` plus optional `--label`, `--max-field`, or shared `--max-value` - `heatmap`: `--x <field> --y <field> --value <field>` - `waterfall`: `--x <field> --value <field>` - `calendar`: `--date <field> --value <field>` - `themeRiver`: `--date <field> --value <field> --series-field <field>` - `candlestick`: `--x <field> --open <field> --close <field> --low <field> --high <field>` - `boxplot`: `--x <field> --low <field> --q1 <field> --median <field> --q3 <field> --high <field>` - `sankey`: `--source <field> --target <field> --value <field>` - `graph`: `--source <field> --target <field>` plus optional `--value`, `--source-group`, `--target-group`, `--source-size`, `--target-size` - `tree`: `--label <field> --value <field>` plus optional `--parent-field` - `parallel`: `--name-field <field> --y metric1,metric2,metric3` - `scatter`: `--x <field> --y <field>` plus optional `--series-field`, `--size-field`, `--label-field` - `radar`: `--name-field <field> --y metric1,metric2,metric3` - `treemap`: `--label <field> --value <field>` plus optional `--parent-field` - `sunburst`: `--label <field> --value <field>` plus optional `--parent-field` ### `page` Best when the option already exists and only needs a polished preview or export wrapper. - Accepts JSON option files - Preserves the option as JSON and wraps it in the standalone HTML template - Use `--renderer svg` when the final deliverable should stay vector-friendly ## Export Guidance - Use `--renderer svg` for vector exports, design reviews, and docs-friendly embeds. - Use `--renderer canvas` for crisp PNG output and heavier charts. - Use `--export-image png` or `--export-image svg` during `build.mjs` for one-step image output. - Repeat `--export-image` to export multiple formats in one run, for example `--export-image png --export-image svg`. - Use `node {baseDir}/scripts/render-image.mjs --input ./artifacts/chart-name --type png` for direct PNG export. - Use `node {baseDir}/scripts/render-image.mjs --input ./artifacts/chart-name --type svg` for direct SVG export from SVG-rendered pages. - `--export-image svg` requires `--renderer svg`. - When exporting multiple formats, `--image-out` must point to a directory or a path without an extension. - `render-image.mjs` auto-detects Chrome or Edge. If detection fails, pass `--browser-executable <path>` or set `ECHARTS_BROWSER_PATH`. - `chart.html` still includes buttons for PNG download, SVG download when SVG renderer is active, JSON download, and clipboard copy. - The generated page first tries the configured CDN and then common public mirrors. If the environment is fully offline, rerun with `--cdn <url>` pointing to a local or mirrored bundle. ## Authoring Rules - Choose the simplest chart that answers the question. Do not default to dashboards when one chart is enough. - Keep units in titles, axis names, or notes when the metric is ambiguous. - Use `references/chart-selection.md` when deciding between bars, pictorial bars, polar bars, lines, pies, rose pies, scatters, heatmaps, calendars, theme rivers, waterfalls, funnels, gauges, treemaps, sunbursts, candlesticks, boxplots, sankeys, graphs, trees, parallels, and radar charts. - Use `references/option-patterns.md` for JSON-safe option patterns such as data zoom, stacked series, donut layout, and mark lines. - Prefer JSON-safe config over formatter functions when possible. If function-based formatting is unavoidable, treat `chart.option.json` as the base and edit `chart.html` intentionally afterward. ## OpenClaw And ClawHub Norms - Write artifacts inside the current workspace, not into home-directory scratch paths. - Keep examples, templates, and published artifacts generic. Sanitize client data before sharing anything on ClawHub. - Do not hide key logic in chat-only prose. Save the option, page, and normalized data as files. - Keep the skill reusable: data samples should be fake or clearly synthetic, and commands should use `{baseDir}` instead of machine-specific paths. ## References - Read `references/chart-selection.md` for chart choice and data-shape guidance. - Read `references/option-patterns.md` for advanced JSON-safe option patterns and cleanup rules.