ToolJet 添加组件（Widget）完整指南：从拖放入画布到查询数据绑定-开发者社区

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 教程《Adding a widget》为主线，系统讲解在 ToolJet 应用编辑器中添加组件的完整流程：从右侧Widget manager（组件管理器）搜索与拖放组件、画布上的缩放与重定位、向 Modal 中添加组件、调整表格列宽，再到通过检查器面板配置组件属性，最终把 PostgreSQL 查询结果通过{{queries.postgresql1.data}}双花括号表达式绑定到表格组件。读完本篇，你将掌握 ToolJet 低代码编辑器的核心交互方式与数据绑定原理，能够独立完成"连数据源 → 建查询 → 拖组件 → 绑数据"的完整应用搭建链路。

前置条件：本教程所处的上下文

本教程是 ToolJet 入门系列（位于 docs/docs/tutorial 目录）中的一环。在开始添加组件之前，假设你已经完成了以下前置步骤：

创建一个 ToolJet 应用并进入应用编辑器；
连接一个数据源（本教程以PostgreSQL为例）；
创建并运行一个名为fetch customers（或示例中的postgresql1）的查询，用于返回客户数据。

本篇文章的所有操作都发生在 ToolJet 编辑器的画布（Canvas）与右侧边栏中，无需编写任何前后端代码。

打开组件管理器：添加组件的入口

要添加组件，首先导航到右侧边栏的Widget manager（组件管理器）。它会列出所有可以添加到应用中的内置组件，并且提供了搜索功能，帮助你在组件数量较多时快速定位目标组件。

从仓库源码看，组件管理器由 ComponentsManagerTab.jsx 实现。它从componentTypes（组件类型列表）中动态生成组件清单，并使用Fuse.js模糊搜索（new Fuse(searchList, ...)，防抖 125ms）来支持搜索框的即时过滤，也就是说即便你不记得组件的完整名称，输入部分关键词也能匹配到目标组件。

组件管理器中的组件按分类组织，分类定义见 sectionConfig.js：

分类	包含的组件
Commonly used（常用）	Table、Button、Text、TextInput、DatetimePickerV2、Form
Buttons（按钮）	Button、ButtonGroupV2、PopoverMenu、FileButton
Data（数据）	Table、Chart、KeyValuePair
Layouts（布局）	Form、ModalV2、Container、Accordion、Tabs、Listview、Kanban、Calendar
Text inputs（文本输入）	TextInput、TextArea、EmailInput、PasswordInput、RichTextEditor
Number inputs（数字输入）	NumberInput、PhoneInput、CurrencyInput、RangeSliderV2、StarRating
Select inputs（选择输入）	TagsInput、DropdownV2、MultiselectV2、ToggleSwitchV2、RadioButtonV2、Checkbox、TreeSelect、Cascader
Date and time inputs（日期时间输入）	DaterangePicker、DatePickerV2、TimePicker、DatetimePickerV2
Navigation（导航）	Navigation、Link、Pagination、Steps
Media（媒体）	Icon、Image、SvgImage、PDF、Map、AudioRecorder、Camera
Presentation（展示）	Text、Tags、CircularProgressBar、ProgressBar、Timeline、Divider、VerticalDivider、Spinner、Statistics、Timer、JSONExplorer
Custom（自定义）	CustomComponent、Html、IFrame
Miscellaneous（其他）	FilePicker、CodeEditor、ColorPicker、BoundedBox、QrScanner、Chat、ReorderableList、JSONEditor
Legacy（旧版组件）	Modal、Datepicker、RadioButton、ToggleSwitch、DropDown、Multiselect、RangeSlider、ButtonGroup

组件的完整注册表位于 widgetConfig.js，每一个组件的配置（名称、属性、校验规则、默认值）都由对应的配置文件声明，例如表格组件的配置见 table.js。搜索时可以直接输入组件名，比如输入table即可快速筛选出 Table 组件。

拖放组件到画布

以本教程的场景为例：我们需要在应用中添加一个Table（表格）组件，用来展示上一步查询得到的客户数据。

操作步骤：

在右侧 Widget manager 中找到Table组件（可通过搜索框输入Table快速定位）；
按住鼠标左键，将组件拖拽到左侧画布（Canvas）上；
松开鼠标，组件即被放置到画布中。

ToolJet 的组件管理器使用 HTML5 拖放机制配合自定义的DragLayer（见 DragLayer）渲染拖拽时的视觉反馈。拖放完成后，组件会以网格化布局出现在画布上，自动吸附到网格线，方便后续对齐与排版。

调整组件大小与位置

组件放入画布后，可以自由缩放与重新定位，具体方式如下：

选中组件：单击画布上的组件即可将其选中，组件四周会出现选中边框与操作手柄；
调整大小：拖拽组件右下角（或边缘）的缩放手柄，即可横向、纵向或整体改变组件的宽高；
重新定位：直接拖拽组件本体，将其移动到画布中的任意网格位置。

从实现角度看，画布上组件的大小与位置调整基于网格系统，组件尺寸、坐标以网格单元为单位记录，相关逻辑集中在 AppCanvas/Grid 目录（如 Grid.jsx），确保组件在桌面与移动端布局切换时依然保持合理排布。

向 Modal 中添加组件

除了直接放在画布上，组件还可以添加到Modal（模态框）内部。ToolJet 中 Modal 本身也是一个组件，其内容区可以容纳其他组件。

操作步骤：

先添加 Modal 组件：从 Widget manager 中将Modal组件拖放到画布上。注意：在触发Show modal动作之前，必须先确保画布中已存在一个 Modal 组件；
触发 Show modal 动作：通过某个组件（例如 Button）的事件处理器触发Show modal action（详见 Actions 动作文档中的可用动作列表），让 Modal 在预览/运行时显示出来；
点击画布上的 Modal 区域：当 Modal 处于打开/可编辑状态时，点击其内容区域，使右侧边栏切换为对应的编辑上下文；
从 Widget manager 拖放组件到 Modal 内部：此时右侧 Widget manager 依然可用，将需要的组件直接拖入 Modal 内容区即可。

在仓库中，Modal 相关组件有新旧两套实现：Modal（旧版，位于 Modal.jsx）与ModalV2（新版，位于 ModalV2 目录）。Modal 组件配置中同样声明了Show modal/Close modal等动作（可在 WidgetManager 的 modal 配置中查看），事件处理器通过 Inspector 的 EventManager 挂接这些动作。推荐在新项目中使用ModalV2。

调整表格列宽

表格组件放置完成后，如果列内容较多，可以通过列的缩放手柄（resize handle）直接调整列宽：

将鼠标悬停在表头两列之间的分隔线上；
当光标变为可拖拽的缩放指针时，按住并左右拖动即可调整该列宽度；
松开鼠标完成调整，列宽会立即生效并持久化保存到组件定义中。

通过检查器面板修改组件属性

单击画布上的组件，右侧边栏会切换为Inspector（检查器）面板。检查器面板集中管理该组件的全部可配置项，包括：

Properties（属性）：组件的数据与功能配置，例如表格的 Title、Data（数据源）、Columns（列定义）、Loading state 等；
Styles（样式）：外观配置，如背景色、边框、圆角、内边距、CSS class 等；
Events（事件）：组件事件与动作绑定；
General（通用）：如 Tooltip（悬浮提示）等通用设置。

在检查器面板中，你可以直接修改属性值；以表格组件为例，可以配置要展示的列：

在Columns（列）配置中管理列集合；
列的显示顺序可以通过拖拽列名旁边的拖拽图标来调整；
每个列还可以独立配置列标题、数据类型、宽度、是否可排序等。

从源码看，检查器面板对每个属性的渲染基于组件配置中声明的type字段（如string、code、toggle、dropdownMenu、array等），并配套对应的校验规则（validation.schema）。例如表格的data属性被声明为type: 'code'，其校验 schema 为对象数组（{ type: 'array', element: { type: 'object' } }），默认值为[{ id: 1, name: 'Sarah', email: 'sarah@mail.com' }]，详见 table.js。这意味着数据字段接受 JSON 数组或任意可解析为对象数组的表达式。

将查询数据绑定到组件：双花括号表达式

现在进入本教程最核心的环节：把fetch customers查询返回的data对象连接到表格组件上。

绑定步骤

单击画布上的表格组件，打开右侧检查器面板；
找到Data（数据）属性，此时它的值是一个空数组[]；
在数据字段中输入单行 JavaScript 表达式，并用双花括号{{ }}包裹：{{queries.postgresql1.data}}
输入时编辑器会弹出变量建议下拉列表（自动补全），帮助你选择正确的变量路径；
由于查询在前面步骤中已经运行过，数据会立即渲染到表格中，无需重新发布应用。

双花括号绑定语法解析

ToolJet 中，几乎每个属性字段都支持双花括号{{ }}内的单行 JavaScript 表达式，这是一种声明式数据绑定机制：

{{queries.postgresql1.data}}：引用名为postgresql1的查询的返回数据（查询结果对象中的data数组）；
支持引用组件变量，如{{components.table1.selectedRow}}、{{components.textinput1.value}}；
支持引用全局变量、页面变量、环境变量以及运行任意 JS 表达式的结果。

从源码实现看，该机制由 CodeBuilder 负责解析：编辑器会识别以{{开头、以}}结尾的表达式（见 CodeBuilder/utils.js），并基于当前应用状态（组件值、查询结果、全局变量等）生成自动补全建议（suggestions），在输入时以下拉列表形式呈现。自动补全的具体过滤逻辑见 autocompleteExtensionConfig.js，它会在输入满足{{...}}包裹条件时收集组件与查询相关的提示（如queries.postgresql1.data、components.table1等）并实时展示，这正是文档中提到的"输入时代码会自动弹出变量建议下拉"的底层实现。

查询对象queries的层级结构为queries.<queryName>.<field>，其中：

引用路径	说明
`queries.<queryName>.data`	查询成功返回的数据
`queries.<queryName>.isLoading`	查询是否正在执行（布尔值）
`queries.<queryName>.rawData`	查询返回的原始响应数据
`queries.<queryName>.error`	查询执行失败时的错误信息

在绑定表格数据时，务必确认postgresql1查询已成功运行且返回的是对象数组（每行一个对象、对象键对应列名），这样表格会自动按对象的键生成列。

小结：完整的建表链路

至此，本教程完成了 ToolJet 中最经典的一条应用搭建链路：

连接数据源：创建 PostgreSQL 数据源连接；
创建并运行查询：在查询面板中编写fetch customers/postgresql1查询并运行，验证返回数据；
拖放组件：从右侧 Widget manager 将 Table 组件拖入画布；
布局调整：在画布上调整组件大小与位置，必要时放入 Modal 并调整表格列宽；
配置属性：通过检查器面板修改组件属性、管理列顺序；
绑定数据：在 Data 属性中输入{{queries.postgresql1.data}}将查询结果绑定到表格。

表格组件的更多高级用法——如服务端分页（server-side pagination）、行操作按钮（actions）、数据编辑（editing data）、动态列等——可继续查阅 Table 表格组件参考文档，该文档详细覆盖了表格组件的全部属性、事件与样式配置；如果你需要回顾查询创建步骤，可回到教程目录查看前置章节。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考