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/ToolJetChart 组件是 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 中本文接下来的所有属性、默认值和取值选项均与这份配置文件一一对应。基础属性PropertiesTitle标题在Title属性中输入文本该文本会显示在 Chart 组件顶部。默认值为This title can be changed这个标题可以修改。在源码中标题会传入 Plotly 的layout.title对象并自动使用主题文字颜色渲染title: { text: chartTitle, font: { color: modifiedTextColor }, },标题还支持通过fx动态绑定例如绑定一个查询返回值或组件状态使其随数据变化。Chart type图表类型通过下拉框选择图表类型可选值为选项对应值说明Lineline折线图默认Barbar柱状图Piepie饼图你也可以点击fx输入一个逻辑表达式动态返回line、pie或bar。从源码看图表类型实际就是传入 Plotly 的 tracetype字段饼图会构建values来自y和labels来自x而折线图和柱状图则构建x、y数组并应用marker.colorif (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 SchemaPlotly JSON 图表模式这是 Chart 组件最强大的高级能力。开启Use Plotly JSON Schema开关后组件不再使用简化的Chart dataChart 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.jsxconst 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 variablesChart 组件向应用暴露以下变量可通过{{components.chart1.xxx}}在任何支持 JS 表达式的地方访问变量说明访问方式chartTitle当前图表的标题{{components.chart1.chartTitle}}xAxisTitleX 轴标题{{components.chart1.xAxisTitle}}yAxisTitleY 轴标题{{components.chart1.yAxisTitle}}clickedDataPoint最近一次点击的数据点信息{{components.chart1.clickedDataPoint}}其中clickedDataPoint是点击事件产生的对象包含以下字段见 Chart.jsx字段说明xAxisLabel数据点的 X 轴标签yAxisLabel数据点的 Y 轴标签dataLabel数据点标签dataValue数据点数值dataPercent数据点占比dataSeriesName数据系列名称来自 Plotly trace 的name注意文档中表格列的变量名为clickedDataPoints而组件实际暴露的变量名为clickedDataPoint单数形式且额外包含dataSeriesName字段。这是文档与实现的一个细微差异实际开发中以clickedDataPoint为准。组件还暴露了一个可调用的动作clearClickedPoint{{components.chart1.clearClickedPoint()}}用于将clickedDataPoint重置为空对象{}定义见 chart.js。选项Options选项说明配置方式Loading state显示加载动画常用于与查询的isLoading状态联动开关或fx动态表达式Show axes显示/隐藏图表坐标轴开关或fx动态表达式默认开启Show grid lines显示/隐藏图表网格线开关或fx动态表达式默认开启从源码看这三个开关最终都作用到 Plotly layout 上showAxes控制坐标轴的visibleshowGridLines控制坐标轴的showgrid而loadingState为true时组件渲染一个 Bootstrap spinner 替代图表本体见 Chart.jsxxaxis: { showgrid: showGridLines, visible: showAxes, ... }, yaxis: { showgrid: showGridLines, visible: showAxes, ... },注意Show axes和Show grid lines仅在非饼图chartType ! pie时出现在属性面板见 Inspector/Components/Chart.jsx。事件Events事件触发时机On data point click用户点击图表数据点时触发On double click用户双击图表区域时触发在源码中这两个事件分别绑定到 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属性说明配置方式Show on desktop在桌面端视图中显示组件开关或fx动态表达式默认{{true}}Show on mobile在移动端视图中显示组件开关或fx动态表达式默认{{false}}样式Styles以下样式属性控制组件的外观属性说明配置方式Background color组件背景色选择颜色或fx返回 Hex 颜色值默认var(--cc-surface1-surface)Border color组件边框颜色选择颜色默认var(--cc-default-border)Paddings组件内边距输入数值默认50Border radius边框圆角输入数值或fx动态返回数值默认6Visibility组件可见性开关或fx动态表达式默认{{true}}Disables禁用组件禁用后不可交互开关或fx动态表达式默认{{false}}从源码看padding会作为 Plotly layout 的四个方向边距margin: { l, r, b, t }传入visibility: false时组件整体display: nonedisabledState则同时阻止点击/双击事件并设置data-disabled属性见 Chart.jsxmargin: { l: padding, r: padding, b: padding, t: padding, },背景色还会自动适配明暗主题当背景为白色#fff且处于暗色模式时会替换为深色#1f2936并据此自动计算前景文字颜色亮背景用黑色文字暗背景用白色文字。综合实战构建一张可交互的月度销量图把以上配置串起来一个典型的实现步骤如下拖入 Chart 组件到画布默认即生成名为chart1的组件配置 Chart data输入月度销量 JSON或绑定查询{{queries.salesQuery.data}}选择 Chart type为bar并设置Marker color为主题品牌色打开 Loading state的fx输入{{queries.salesQuery.isLoading}}查询加载时图表自动显示 spinner添加事件在On data point click上挂一个显示告警 Action消息写{{components.chart1.clickedDataPoint.dataLabel : components.chart1.clickedDataPoint.dataValue}}点击柱状图即可看到对应月份的数值按设备适配在移动端视图中显示开启Show on mobile如果需要双系列或双 Y 轴等高级图表开启Use Plotly JSON Schema在JSON description中编写完整的 Plotly figure。小结Chart 组件在 ToolJet 中承担了全部的数据可视化职责其配置体系可归纳为三层基础层——Title、Chart type、Chart data、Marker color满足折线/柱状/饼图的快速可视化高级层——Use Plotly JSON Schema直接透传完整 Plotly figure解锁多系列、多坐标轴、注解等全部 Plotly 能力交互层——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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考