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 Mode1.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 提供四种模式模式核心逻辑视觉表现适用场景Stack堆叠不同系列的柱体在纵向上垂直叠加每个类别显示一根总柱柱内分段表示各系列数值展示各类别总值的同时对比各系列在其中的贡献Group分组同一类别下不同系列柱体并排摆放各系列柱体互不重叠、紧邻排列直接比较同类别下不同系列的具体数值Overlay覆盖不同系列柱体在同一位置重叠柱体重叠显示仅靠颜色与透明度区分逐类精细对比不同系列的数值关系Relative相对柱体按比例高度展示相对占比每类柱体总高固定100%各系列按比例分配强调各类别内各系列的相对比重在 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/Mary值分别绘制为独立的折线适合对比多个指标在同一时间维度上的走势。四、带注解的折线图Line Chart With Annotations在折线图基础上可以通过layout.annotations为特定数据点添加文字标注、箭头等说明信息。示例使用type: scatter与mode: linesmarkers组合出折线 数据点标记的展示效果并为每个数据点配置了一个指向该点的箭头注解{ data: [ { x: [Jan, Feb, Mar], y: [100, 80, 40], type: scatter, mode: linesmarkers } ], 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(indexy, columnsx, valuesvalue)将长表转成矩阵再构造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隶属于AD、E、F均隶属于B而B又隶属于A形成两层嵌套的层级树。运行效果见 icicle.png。十、3D 网格3D Meshmesh3d通过三维空间中的顶点坐标绘制三维曲面常用于科学或工程数据可视化。示例给出四个顶点坐标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关键链路如下依赖与渲染引擎组件基于plotly.js-dist-min^2.29.1与react-plotly.js^2.6.0构建依赖声明见 frontend/package.json通过createPlotlyComponent(Plotly)创建 React 封装Chart.jsx。JSON 校验与解析启用plotFromJson后组件先用isStringValidJson校验 JSON Description 的合法性合法时取.data作为数据系列、.layout ?? {}作为布局Chart.jsx。布局合并策略最终传给 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.jsxannotations、dragmode、barmode等字段也会被透传Chart.jsx。交互与暴露变量点击数据点时组件通过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。性能处理渲染部分被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的图例、颜色条、副坐标轴等能力——只需保证返回的是合法 JSONToolJet 组件即可原样透传给底层渲染引擎。小结本文完整覆盖了 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考