企业官网建设流程全解析

ToolJet Chart 组件配置指南：从基础属性到 Plotly JSON Schema 的完整实战

【免费下载链接】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

Chart 组件是 ToolJet 应用构建器中用于数据可视化的核心组件，本文基于 Chart 组件官方文档 展开，系统讲解其属性面板中的每一项配置：从标题、图表类型、数据格式，到 Plotly JSON Schema 高级模式、暴露变量、事件与样式。读完本文，你将掌握如何在 ToolJet 中配置一张折线图、柱状图或饼图，并通过fx动态表达式、事件与暴露变量实现数据联动和交互。

概览：Chart 组件能做什么

Chart 组件底层基于 Plotly.js，通过react-plotly.js工厂封装 Plotly 核心库，并针对 ToolJet 的主题变量（背景色、网格线、坐标轴、文字颜色）做了自动适配：

import Plotly from 'plotly.js-dist-min'; import createPlotlyComponent from 'react-plotly.js/factory'; const Plot = createPlotlyComponent(Plotly);

组件的默认尺寸为宽 20 格、高 400px，默认图表类型为line（折线图）。其所有配置项的元数据定义在 frontend/src/AppBuilder/WidgetManager/widgets/chart.js 中，本文接下来的所有属性、默认值和取值选项均与这份配置文件一一对应。

基础属性（Properties）

Title（标题）

在Title属性中输入文本，该文本会显示在 Chart 组件顶部。默认值为This title can be changed（"这个标题可以修改"）。

在源码中，标题会传入 Plotly 的layout.title对象，并自动使用主题文字颜色渲染：

title: { text: chartTitle, font: { color: modifiedTextColor }, },

标题还支持通过fx动态绑定，例如绑定一个查询返回值或组件状态，使其随数据变化。

Chart type（图表类型）

通过下拉框选择图表类型，可选值为：

你也可以点击fx输入一个逻辑表达式，动态返回line、pie或bar。从源码看，图表类型实际就是传入 Plotly 的 tracetype字段：饼图会构建values（来自y）和labels（来自x），而折线图和柱状图则构建x、y数组并应用marker.color：

if (chartType === 'pie') { newData = [{ type: chartType, values: rawData.map((item) => item['y']), labels: rawData.map((item) => item['x']), }]; } else { newData = [{ type: chartType || 'line', x: rawData.map((item) => item['x']), y: rawData.map((item) => item['y']), marker: { color: modifiedMarkerColor }, }]; }

Chart data（图表数据）

数据必须是 JSON 格式，且包含x和y两个键。组件同时支持字符串和对象两种 JSON 数据类型——即你可以直接粘贴一段 JSON 字符串，也可以绑定一个返回对象/数组的表达式。

示例：

[ { "x": "Jan", "y": 100}, { "x": "Feb", "y": 80}, { "x": "Mar", "y": 40}, { "x": "Apr", "y": 100}, { "x": "May", "y": 80}, { "x": "Jun", "y": 40} ]

从 Chart.jsx 的computeChartData函数可以看到数据解析的健壮性处理：如果传入的是字符串则先尝试JSON.parse，解析失败或不是数组时自动回退为空数组，避免图表渲染崩溃：

if (typeof rawData === 'string') { try { rawData = JSON.parse(dataString); } catch (err) { rawData = []; } } if (!Array.isArray(rawData)) { rawData = []; }

实际使用中，最典型的做法是将Chart data绑定到某个数据查询（Query）的结果，例如{{queries.restapi1.data}}，查询返回后图表会自动刷新。

Marker Color（标记颜色）

仅对折线图和柱状图可用，用于定义线条或柱子的颜色。默认值为var(--cc-primary-brand)（ToolJet 主题品牌色）。点击fx可以输入动态代码返回颜色值。饼图不提供该属性，其颜色由 Plotly 自动分配。

Plotly JSON Chart Schema（Plotly JSON 图表模式）

这是 Chart 组件最强大的高级能力。开启Use Plotly JSON Schema开关后，组件不再使用简化的Chart data+Chart type配置，而是直接接受完整的 Plotly figure JSON（包含data和layout两部分），从而支持多系列、双坐标轴、注解（annotations）、自定义拖拽模式（dragmode）等复杂图表。开关同样支持fx动态控制。

开启后，属性面板还会额外出现两个配置项：

• JSON description：填写 Plotly figure 的 JSON 描述。默认值如下，展示了标准结构：

{ "data": [ { "x": ["Jan", "Feb", "Mar"], "y": [100, 80, 40], "type": "bar" } ] }

• Bar mode：柱状图模式下拉框，可选stack（堆叠）、group（分组，默认）、overlay（叠加）、relative（相对）。

从源码看，开启 Plotly JSON 模式后，data直接取自 JSON 中的data数组，layout取自 JSON 中的layout对象，并且 ToolJet 会自动为 layout 注入主题化的坐标轴、网格线、边距等默认值，同时保留用户 layout 中自定义的xaxis2、yaxis2等额外坐标轴（见 Chart.jsx）：

const jsonChartData = isDescriptionJson ? JSON.parse(jsonData).data : []; const chartLayout = isDescriptionJson ? (JSON.parse(jsonData).layout ?? {}) : {};

在 Plotly JSON 模式下，标题也优先取自 layout 的title字段（chartLayout?.title ?? title）。

提示：JSON description 中也可以包含layout，例如设置"layout": { "title": "月度销量", "dragmode": "zoom" }，ToolJet 会将其与自身计算出的 layout 合并。

暴露变量（Exposed variables）

Chart 组件向应用暴露以下变量，可通过{{components.chart1.xxx}}在任何支持 JS 表达式的地方访问：

其中clickedDataPoint是点击事件产生的对象，包含以下字段（见 Chart.jsx）：

注意：文档中表格列的变量名为clickedDataPoints，而组件实际暴露的变量名为clickedDataPoint（单数形式），且额外包含dataSeriesName字段。这是文档与实现的一个细微差异，实际开发中以clickedDataPoint为准。

组件还暴露了一个可调用的动作clearClickedPoint（{{components.chart1.clearClickedPoint()}}），用于将clickedDataPoint重置为空对象（{}），定义见 chart.js。

选项（Options）

从源码看，这三个开关最终都作用到 Plotly layout 上：showAxes控制坐标轴的visible，showGridLines控制坐标轴的showgrid，而loadingState为true时组件渲染一个 Bootstrap spinner 替代图表本体（见 Chart.jsx）：

xaxis: { showgrid: showGridLines, visible: showAxes, ... }, yaxis: { showgrid: showGridLines, visible: showAxes, ... },

注意：Show axes和Show grid lines仅在非饼图（chartType !== 'pie'）时出现在属性面板（见 Inspector/Components/Chart.jsx）。

事件（Events）

在源码中，这两个事件分别绑定到 Plotly 的onClick与onDoubleClick回调。点击事件会先通过handleClick组装clickedDataPoint暴露变量，再调用fireEvent('onClick')；双击事件直接触发fireEvent('onDoubleClick')。需要注意的是，当组件处于禁用状态（disabledState）时，两个事件都不会触发：

const handleClick = useCallback((data) => { if (!disabledState && data.length > 0) { // 组装 clickedDataPoint 并 setExposedVariable fireEvent('onClick'); } }, []);

事件触发后，可以在事件处理器中连接 ToolJet 的各种 Action（如显示告警、运行查询、切换组件状态等）。关于所有 Action 的详细说明，可参阅 Action Reference 文档（原文档以/docs/category/actions-reference指向动作参考分类，仓库中对应的核心说明见 actions 目录）。

设备可见性（Devices）

样式（Styles）

以下样式属性控制组件的外观：

从源码看，padding会作为 Plotly layout 的四个方向边距（margin: { l, r, b, t }）传入，visibility: false时组件整体display: none，disabledState则同时阻止点击/双击事件并设置data-disabled属性（见 Chart.jsx）：

margin: { l: padding, r: padding, b: padding, t: padding, },

背景色还会自动适配明暗主题：当背景为白色（#fff）且处于暗色模式时，会替换为深色#1f2936，并据此自动计算前景文字颜色（亮背景用黑色文字，暗背景用白色文字）。

综合实战：构建一张可交互的月度销量图

把以上配置串起来，一个典型的实现步骤如下：

1. 拖入 Chart 组件到画布，默认即生成名为chart1的组件；
2. 配置 Chart data：输入月度销量 JSON，或绑定查询{{queries.salesQuery.data}}；
3. 选择 Chart type为bar，并设置Marker color为主题品牌色；
4. 打开 Loading state的fx，输入{{queries.salesQuery.isLoading}}，查询加载时图表自动显示 spinner；
5. 添加事件：在On data point click上挂一个"显示告警" Action，消息写{{components.chart1.clickedDataPoint.dataLabel + ': ' + components.chart1.clickedDataPoint.dataValue}}，点击柱状图即可看到对应月份的数值；
6. 按设备适配：在移动端视图中显示，开启Show on mobile；
7. 如果需要双系列或双 Y 轴等高级图表，开启Use Plotly JSON Schema，在JSON description中编写完整的 Plotly figure。

小结

Chart 组件在 ToolJet 中承担了全部的数据可视化职责，其配置体系可归纳为三层：

1. 基础层——Title、Chart type、Chart data、Marker color，满足折线/柱状/饼图的快速可视化；
2. 高级层——Use Plotly JSON Schema直接透传完整 Plotly figure，解锁多系列、多坐标轴、注解等全部 Plotly 能力；
3. 交互层——On data point click/On double click事件配合clickedDataPoint暴露变量与clearClickedPoint动作，实现点击数据点驱动的业务联动。

所有配置项均可在属性面板中通过fx动态绑定表达式，实现真正的"数据驱动图表"。相关配置元数据（默认值、类型、选项）可在 frontend/src/AppBuilder/WidgetManager/widgets/chart.js 中随时查阅，渲染实现细节则集中在 frontend/src/AppBuilder/Widgets/Chart.jsx。

【免费下载链接】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