企业官网建设流程全解析

ToolJet 教程：使用 Widget 管理器添加、配置并绑定数据到组件

【免费下载链接】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 可视化应用构建教程系列中的一环，聚焦于如何在右侧的Widget 管理器中查找、拖放、调整与配置内置组件（Widget），并将上一步查询（Query）返回的数据通过双花括号表达式绑定到 Table 表格组件上。读完本篇，你将掌握 ToolJet 画布上的组件拖放、尺寸调整、Modal 内嵌组件、列宽调整、属性检查器（Inspector）操作以及{{queries.xxx.data}}动态数据绑定的完整实战流程。

前置上下文：本教程在整体流程中的位置

本指南属于 ToolJet 2.50.0-LTS 版本教程系列中的一环。在开始添加 Widget 之前，建议你先完成系列中的前置步骤，以便文中涉及的fetch customers查询与 PostgreSQL 数据源真实可用：

1. 创建应用：ToolJet 应用将 Widget、数据源（Data source）与查询（Query）三者绑定在一起。
2. 添加数据源：连接 PostgreSQL 数据库。
3. 构建查询：创建SELECT * FROM customers;查询并运行。

在 ToolJet 中，应用由三部分组成：Widgets（表格、按钮、下拉框等 UI 组件）、Data sources（可连接的数据库、API 与外部服务）以及Queries（用于访问已连接数据源）。本篇文章要完成的，正是"把查询结果可视化地呈现在界面上"这一关键环节。

打开 Widget 管理器

要添加组件，请导航到应用编辑器右侧边栏的Widget manager（组件管理器）。它会列出所有可添加到应用的内置组件，例如表格（Table）、按钮（Button）、下拉框（Dropdown）等。

当组件数量较多时，可以使用面板顶部的搜索功能快速定位你想要的组件——输入关键字即可过滤组件列表，无需在长列表中手动翻找。

从源码结构看，该面板在仓库中的实现位于 ComponentsManagerTab.jsx，配套的 sectionConfig.js 负责定义组件的分区与分类展示逻辑；而组件本身的类型定义集中在 WidgetManager/componentTypes.js，每个组件的元信息（默认属性、事件、校验规则等）则存放在 WidgetManager/configs 与 WidgetManager/widgets 目录中。

拖放 Widget 到画布

接下来，我们把一个table（表格）组件添加到应用中，用来展示上一步查询获取到的客户数据。

操作方式非常简单：从 Widget 管理器中将目标组件直接拖拽（Drag and Drop）到中间的画布（Canvas）区域，松开鼠标后组件即被放置到画布上。

画布采用的是基于网格（Grid）的响应式布局，组件被放置后会自动吸附到网格单元上，方便对齐与排版。

调整 Widget 的大小与位置

组件放入画布后，可以随时进行缩放（Resize）与重新定位（Reposition）：

• 调整大小：选中组件，拖动其边缘或角落的调整手柄（resize handle）即可改变宽高。
• 重新定位：按住组件主体拖动，即可在画布内移动到任意位置。

在 ToolJet 中，画布上的组件坐标与尺寸由网格系统统一管理，相关实现可参考 Grid.jsx 及其工具函数 gridUtils.js，其中定义了组件在画布上的行列定位与尺寸换算逻辑。

向 Modal 中添加 Widget

有时我们希望把表单或详情内容放在弹窗（Modal）里，而不是直接铺在页面上。要向 Modal 添加组件，需要借助Show modal action（显示弹窗动作）。

:::info 在触发Show modal action之前，必须先向画布添加一个modal（弹窗）组件。 :::

完整步骤如下：

1. 从 Widget 管理器将一个modal widget添加到画布上；
2. 触发Show modal action（该动作属于 ToolJet 内置的可用动作之一，详细动作列表见 actions 教程，其中包含 Show alert、Run query、Open webpage、Goto app、Show modal、Close modal、Copy to clipboard、Set localStorage、Generate file 等）；
3. 点击画布空白区域，让右侧边栏切换回Widget manager；
4. 再次从右侧的 Widget 管理器中拖放组件到弹窗内部即可。

这里有一个容易混淆的细节：触发Show modal动作的入口不止一处——为组件事件绑定处理器时，可在组件检查器（Inspector）中点击Add handler；为查询事件绑定处理器时，则需选中查询、切换到advanced标签页后点击Add handler。两者最终都能调用到 Show modal 这类内置动作。

调整表格列宽

表格组件放置好后，你可能需要调整各列的显示宽度。ToolJet 支持直接使用**列的调整手柄（resize handle）**来拖拽改变列宽，这与常规表格编辑器的体验一致。

修改 Widget 属性

点击画布上的组件，右侧边栏会打开**检查器（Inspector）**面板（即属性面板）。在这里可以修改组件的一系列属性（Properties），例如标题、数据、事件处理器等。Inspector 的实现位于 Inspector.jsx。

针对 Table 组件，我们可以配置其列来展示客户数据。其中列的显示顺序可以通过拖动列名旁边的拖拽图标来调整，不需要手动编辑配置。

将查询数据连接到 Widget

现在进入本篇的核心环节：把fetch customers查询返回的data对象绑定到表格组件上。

1. 点击表格组件，在右侧打开 Inspector 面板；
2. 找到data属性，此时它的值是一个空数组[]；
3. 在data字段中输入以下表达式：

{{queries.postgresql1.data}}

关于这个表达式，有几点需要理解：

• 双花括号语法：与编辑器中的几乎所有字段一样，data字段支持在双花括号内书写单行 JavaScript 代码，ToolJet 会将其求值后作为属性值使用。这种机制让组件属性具备完全动态的能力——不仅限于查询数据，任何可访问的变量、表达式都可以在此求值。
• 变量提示：在字段中输入代码时，系统会以下拉列表的形式实时给出变量建议，帮助你快速补全变量名，避免手写拼错。
• 查询结果即时呈现：由于在前面的步骤中我们已经运行过该查询，绑定完成后，表格会立即显示出查询返回的数据，无需重新运行查询。

至此，本教程已经完成了从连接 PostgreSQL 数据库 → 编写查询 → 添加表格组件 → 绑定查询数据并可视化展示的完整闭环。表格组件除了展示数据外，还支持服务端分页、操作按钮、数据编辑等更丰富的自定义能力，可进一步参考仓库中 widgets 目录 下的组件文档继续深入学习。

小结

通过本文，你掌握了 ToolJet 应用编辑器中组件的完整操作链路：

下一步，你可以继续学习教程系列中的 变换（Transformations）、调试器（Debugger） 或 分享与部署，进一步打磨你的第一个 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