企业官网建设流程全解析

ToolJet Chart 组件 Plotly JSON Chart Schema 实战指南：从 Bar Mode 到九类高级图表配置

【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 🚀项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet

导读

本文以 ToolJet 官方文档 charts-examples.md 为主体，系统讲解 Chart 组件在启用Plotly JSON Chart Schema后如何通过纯 JSON 配置实现折线图、柱状图、K 线图、等高线图、热力图、冰柱图与 3D 网格等高级可视化。读者将掌握 Plotly JSON 中data与layout的组织规则、barmode四种布局模式的区别，并理解 Chart 组件底层（Chart.jsx）如何解析与渲染这份 JSON，从而在 ToolJet 中自由组合出满足业务需求的复杂图表。

一、Plotly JSON Chart Schema 与 Bar Mode

1.1 启用 Plotly JSON 模式

在 Chart 组件的属性面板中，打开Use Plotly JSON Schema开关后，组件不再使用默认的x/y键值数据格式，而是接受一段完整的 Plotly JSON 描述。这段 JSON 的核心结构由两个顶层字段组成：

• data：一个数组，其中每个元素描述一条数据系列（trace），包含x、y、type等字段；
• layout（可选）：描述图表的整体布局，如标题、坐标轴、注解（annotations）与barmode等。

ToolJet 底层在 Chart.jsx 中通过isStringValidJson校验 JSON 合法性，随后用JSON.parse(jsonData).data取出数据系列、用JSON.parse(jsonData).layout ?? {}取出布局配置，再交给 Plotly 渲染引擎绘制。

1.2 Bar Mode 的四种布局模式

Bar Mode选项仅在启用 Plotly JSON 模式、且 JSON 中提供了面向柱状图的 schema 时出现，专门用于调整柱状图中各条柱的排布方式。它只影响柱状图的布局，无法作用于折线图、饼图等其他图表类型。ToolJet 提供四种模式：

在 JSON 的layout字段中，barmode属性即对应上述四种模式，例如"barmode": "stack"表示堆叠模式（详见下文 Bar 示例）。从 Chart.jsx 的源码可以看到，组件会把属性面板中选定的barmode直接写入传给 Plotly 的layout对象。

二、JSON 描述的基本组织规则

在JSON Description输入框中，值的核心必须是data数组，数组内每个对象通过x、y给出轴数据，并在末尾用type字段声明图表类型。需要额外布局配置时，再补充顶层layout对象。下面按图表类型逐一给出完整可用的 JSON 示例。

三、折线图（Line）

折线图用于展示数据随时间变化的趋势与模式。在 JSON 中声明两条type: "line"的系列即可绘制多条折线：

{ "data": [ { "x": ["Jan", "Feb", "Mar"], "y": [100, 80, 40], "type": "line" }, { "x": ["Jan", "Feb", "Mar"], "y": [300, 30, 20], "type": "line" } ] }

运行效果可参考文档配套截图 line-v2.png。两条系列共享相同的x轴刻度（Jan/Feb/Mar），y值分别绘制为独立的折线，适合对比多个指标在同一时间维度上的走势。

四、带注解的折线图（Line Chart With Annotations）

在折线图基础上，可以通过layout.annotations为特定数据点添加文字标注、箭头等说明信息。示例使用type: "scatter"与mode: "lines+markers"组合出"折线 + 数据点标记"的展示效果，并为每个数据点配置了一个指向该点的箭头注解：

{ "data": [ { "x": ["Jan", "Feb", "Mar"], "y": [100, 80, 40], "type": "scatter", "mode": "lines+markers" } ], "layout": { "title": "Monthly Performance", "annotations": [ { "x": "Jan", "y": 100, "xref": "x", "yref": "y", "text": "January: 100", "showarrow": true, "arrowhead": 2, "ax": 0, "ay": -30 }, { "x": "Feb", "y": 80, "xref": "x", "yref": "y", "text": "February: 80", "showarrow": true, "arrowhead": 2, "ax": 0, "ay": -30 }, { "x": "Mar", "y": 40, "xref": "x", "yref": "y", "text": "March: 40", "showarrow": true, "arrowhead": 2, "ax": 0, "ay": -30 } ] } }

注解对象中的关键字段含义如下：

• x/y：注解锚定的数据点坐标；
• xref/yref：坐标参照系，"x"/"y"表示相对数据轴定位；
• text：注解显示的文本内容；
• showarrow：是否显示指向数据点的箭头；
• arrowhead：箭头样式编号；
• ax/ay：箭头终点（文字一侧）相对锚点的偏移量。

从源码看，Chart.jsx 会将chartLayout.annotations原样合并进最终传给 Plotly 的layout，因此 JSON 中所有 Plotly 官方支持的注解属性都可以直接生效。运行效果见 line-chart-with-annotations.png。

五、柱状图（Bar）

柱状图用于比较不同类别的数据，或观察变量在各分组间的变化。示例展示了横向堆叠柱状图：两个动物园（SF Zoo 与 LA Zoo）的动物数量以orientation: "h"横向绘制，并通过layout.barmode: "stack"启用堆叠模式，marker字段则分别配置了柱体填充色（半透明）与描边色、描边宽度：

{ "data": [ { "name": "SF Zoo", "type": "bar", "x": [20, 14, 23], "y": ["giraffes", "orangutans", "monkeys"], "marker": { "line": { "color": "rgba(55, 128, 191, 1.0)", "width": 1 }, "color": "rgba(55, 128, 191, 0.6)" }, "orientation": "h" }, { "name": "LA Zoo", "type": "bar", "x": [12, 18, 29], "y": ["giraffes", "orangutans", "monkeys"], "marker": { "line": { "color": "rgba(255, 153, 51, 1.0)", "width": 1 }, "color": "rgba(255, 153, 51, 0.6)" }, "orientation": "h" } ], "layout": { "barmode": "stack" } }

要点说明：

• name用于标识数据系列，会显示在图例中；
• marker.line.color与marker.color支持rgba()半透明颜色，重叠区域可产生视觉混合效果；
• orientation取值"h"（横向）或"v"（纵向）；
• 将layout.barmode切换为"group"、"overlay"、"relative"即可对应第一节介绍的其余三种布局模式。

运行效果见 bar-v2.png。另外，ToolJet 的 Chart 组件在未启用 Plotly JSON 模式时，也会将属性面板中的Marker Color直接写入系列的marker.color（见 Chart.jsx），两种配置方式最终走的是同一条渲染链路。

六、蜡烛图（Candlestick）

蜡烛图用于分析股票、货币等金融标的在特定时间区间内的价格波动。每条蜡烛包含开盘（open）、收盘（close）、最高（high）、最低（low）四个价格：

{ "data": [ { "x": ["2024-04-02", "2024-04-03", "2024-04-04"], "close": [120, 125, 130], "high": [125, 130, 135], "low": [115, 120, 125], "open": [115, 120, 125], "type": "candlestick" } ] }

x为交易日期（ISO 格式字符串），open、high、low、close四个数组按下标一一对应。运行效果见 candlestick.png。

在实际业务中，蜡烛图数据通常来自数据库查询。ToolJet 提供了配套的数据转换实践（见 transforming-data-for-charts.md）：先用查询从 ToolJet DB 的List rows操作取出原始表数据，再用RunJS查询把行式数据重构成上述data数组，并通过JSON.stringify(result)返回，最后在 JSON Description 中绑定{{queries.<RunJS 查询名>.data}}完成渲染。这种做法把"取数、转换、绘图"三步解耦，便于复用与调试。

七、等高线图（Contour）

等高线图用二维平面上的等高线表示三维数据，常用于科学计算与工程数据可视化。z是一个二维矩阵，矩阵元素对应坐标网格(x[i], y[j])上的取值：

{ "data": [ { "x": [1, 2, 3, 4], "y": [1, 2, 3, 4], "z": [[1, 2, 3, 4], [2, 3, 4, 5], [3, 4, 5, 6], [4, 5, 6, 7]], "type": "contour" } ] }

这里z为 4×4 矩阵，对角线方向数值递增，对应地形成一条条平行等值线。运行效果见 contour.png。

八、热力图（Heatmap）

热力图通过颜色强度揭示数据点在二维空间中的密度或大小，适合展示实验矩阵、相关矩阵等场景：

{ "data": [ { "z": [[1, 20, 30], [20, 1, 60], [30, 60, 1]], "x": ["Experiment 1", "Experiment 2", "Experiment 3"], "y": ["Trial 1", "Trial 2", "Trial 3"], "type": "heatmap" } ] }

x、y分别定义行列标签，z矩阵中的每个值对应一个单元格的颜色强度。当数据来自数据库时，官方推荐用RunPy查询配合 pandas 完成行列透视（pivot），示例见 transforming-data-for-charts.md 中的热力图章节——先以df.pivot(index='y', columns='x', values='value')将长表转成矩阵，再构造z、x、y与type: "heatmap"输出。运行效果见 heatmap.png。

九、冰柱图（Icicle）

冰柱图以嵌套的矩形结构展示层级数据，用于直观理解整体中各部分的相对大小。它通过labels（节点名称）与parents（父节点名称）两个数组描述层级关系，根节点的parents值为空字符串：

{ "data": [ { "labels": ["A", "B", "C", "D", "E", "F"], "parents": ["", "A", "A", "B", "B", "B"], "type": "icicle" } ] }

上述结构表示：A为根节点，C隶属于A；D、E、F均隶属于B，而B又隶属于A，形成两层嵌套的层级树。运行效果见 icicle.png。

十、3D 网格（3D Mesh）

mesh3d通过三维空间中的顶点坐标绘制三维曲面，常用于科学或工程数据可视化。示例给出四个顶点坐标，alphahull用于控制曲面包络的紧致程度：

{ "data": [ { "x": [0, 1, 2, 0], "y": [0, 0, 1, 2], "z": [0, 2, 0, 1], "alphahull": 5, "type": "mesh3d" } ] }

其中x、y、z三个等长数组共同定义顶点在三维空间中的位置。运行效果见 3d-mesh.png。

十一、从源码看 JSON 如何被解析与渲染

理解底层实现有助于排查配置问题。Chart 组件的核心渲染逻辑集中在 frontend/src/AppBuilder/Widgets/Chart.jsx，关键链路如下：

1. 依赖与渲染引擎：组件基于plotly.js-dist-min（^2.29.1）与react-plotly.js（^2.6.0）构建，依赖声明见 frontend/package.json，通过createPlotlyComponent(Plotly)创建 React 封装（Chart.jsx）。

2. JSON 校验与解析：启用plotFromJson后，组件先用isStringValidJson校验 JSON Description 的合法性；合法时取.data作为数据系列、.layout ?? {}作为布局（Chart.jsx）。

3. 布局合并策略：最终传给 Plotly 的layout是"组件默认布局 + 用户 JSON 布局"的合并结果（Chart.jsx）：

   • 组件会注入plot_bgcolor、paper_bgcolor（跟随组件背景色）、title、showlegend、xaxis/yaxis（含showgrid、visible、automargin等）；
   • 用户 JSON 中的chartLayout.xaxis/chartLayout.yaxis通过展开运算符覆盖默认值，因而可精细控制坐标轴；
   • 额外的xaxis2、yaxis2、yaxis3等多轴配置会被动态识别并补充默认样式（Chart.jsx）；
   • annotations、dragmode、barmode等字段也会被透传（Chart.jsx）。

4. 交互与暴露变量：点击数据点时，组件通过fireEvent('onClick')触发On data point click事件，并将xAxisLabel、yAxisLabel、dataLabel、dataValue、dataPercent、dataSeriesName写入暴露变量clickedDataPoint，可在其他组件中以{{components.chart1.clickedDataPoint}}访问（Chart.jsx）；双击图表区域则触发On double click事件。组件还暴露chartTitle、xAxisTitle、yAxisTitle变量，并额外提供clearClickedPoint()方法用于清空点击状态（Chart.jsx）。

5. 性能处理：渲染部分被memo包裹，并通过isEqual做深比较，仅在data、layout、config实际变化时才重渲染，避免每次点击触发的重渲染造成事件失效或性能抖动（Chart.jsx）。

十二、与 Chart 组件其他配置的配合

Plotly JSON 模式与 Chart 组件的常规属性是互补关系：

• Chart type：常规模式下通过下拉框选择line、pie、bar，也可用fx表达式动态返回类型；启用 Plotly JSON 后，图表类型由 JSON 中每个系列的type字段决定。
• Chart data：常规模式要求x/y键的 JSON 数组（见 chart.md 中的示例），而 Plotly JSON 模式在JSON Description中提供整段 schema。
• Marker Color：作用于常规模式下的折线/柱状图配色；JSON 模式下改用marker.color实现更细粒度的控制。
• Show axis / Show grid lines：控制坐标轴与网格线显隐，JSON 模式同样受其约束。
• Loading state：开启后组件显示加载中的 spinner，常与查询的isLoading状态绑定。

Chart 组件的完整属性、事件与暴露变量清单，可查阅 docs/docs/widgets/chart/chart.md。

十三、扩展阅读

• 若要了解如何用 RunJS / RunPy 将数据库原始行数据转换为本文各示例所需的 JSON 结构（含饼图、折线图、蜡烛图、热力图四个完整实战案例），请阅读 transforming-data-for-charts.md。
• Plotly 官方维护着完整的 JSON Chart Schema 规范与更多图表类型示例；本文给出的九类 schema 均为该规范的子集，可在其基础上扩展layout的图例、颜色条、副坐标轴等能力——只需保证返回的是合法 JSON，ToolJet 组件即可原样透传给底层渲染引擎。

小结

本文完整覆盖了 ToolJet Chart 组件 Plotly JSON 模式下的全部官方示例：从barmode的四种柱状布局，到折线、带注解折线、柱状、蜡烛、等高线、热力、冰柱与 3D 网格共九类图表的可直接复用的 JSON schema，并结合 Chart.jsx 源码揭示了数据解析、布局合并、事件与暴露变量的底层机制。将本文的 JSON 片段粘贴到JSON Description并绑定真实数据，即可在 ToolJet 中快速搭建出专业级的数据可视化页面。

【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 🚀项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet