ToolJet App-Builder 完整指南从拖拽界面到查询、代码与发布的全流程实战【免费下载链接】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/ToolJetToolJet 的 App-Builder应用构建器是一款可视化低代码开发平台帮助你用拖拽的方式在几分钟内构建内部工具、仪表盘与业务应用。本文将以其官方概览文档 overview.md 为核心骨架完整串联创建 UI、创建查询、自定义代码、值引用、变量管理、GitSync 同步、版本发布与导入导出这八大实操主题并结合仓库前端源码frontend/src/AppBuilder给出底层实现佐证。读完本文你将掌握从设计界面 → 连接数据源 → 编写业务逻辑 → 发布上线的完整应用开发闭环。一、认识 App-Builder定位与核心能力App-Builder 是 ToolJet 的可视化开发环境。正如概览文档所述它的核心价值在于用直观的拖拽界面把想法变成可用的解决方案——无论是简单的表单还是复杂的数据仪表盘都能在数分钟内完成搭建。从源码结构看整个构建器由一组职责清晰的前端模块组成位于 frontend/src/AppBuilder 目录下画布Canvas应用界面渲染与组件摆放区域左侧边栏LeftSidebar包含页面管理、Inspector、Debugger、全局设置等对应 LeftSidebar.jsx查询面板QueryPanel底部用于创建和管理查询的区域对应 QueryPanel.jsx属性面板RightSideBar配置选中组件的属性与样式。一个典型的构建流程是三步走设计界面 → 连接数据源 → 通过可视化方式添加业务逻辑。当需求增长后还可以用自定义代码扩展应用并通过 GitSync 把应用与 Git 仓库同步以简化管理。后续所有实操内容均可在 version-3.0.0-LTS 的 app-builder 文档目录 中找到对应的完整指南。下面我们以客服台仪表盘Support Desk Dashboard为例逐步走完从零到发布的完整流程。二、用预置组件创建 UI构建客服台仪表盘ToolJet 提供了大量预置组件可加速内部工具的快速原型与部署。本节内容完整对应实操指南 create-ui.md。2.1 创建页头Header从右侧组件库拖拽一个Text文本组件到画布左上角点击组件在右侧的Properties Panel属性面板中把Data属性设置为Support Desk Dashboard调整字号为 24、字重为 bold、颜色为蓝色色值#408FCC再添加一个 Text 组件Data设置为Track and manage all your tickets in one place字号 14、颜色灰色#9B9B9B。所有组件的功能与样式属性都集中在属性面板中统一管理这是 App-Builder 配置的核心入口。2.2 票务统计卡片Statistics拖入Statistics统计组件在Primary value label中输入Created并在Primary value中填入数字将主标签颜色与主文字颜色设为蓝色#4A90E2关闭Hide secondary value即显示次要值重复上述步骤再添加 Pending、Closed 两张统计卡片。2.3 票务表格Table在画布上添加Table表格组件将Border Radius调整为 10在Data属性中填入如下示例数据注意使用{{ }}包裹 JavaScript 表达式这是 ToolJet 的求值语法{{ [{ ticketId: TCK1001, customerName: Jane Doe, issueType: Login Issue, priority: High, status: Open, lastUpdated: 2024-04-12 }, { ticketId: TCK1002, customerName: John Smith, issueType: Payment Failure, priority: Medium, status: Pending, lastUpdated: 2024-04-11 }, { ticketId: TCK1003, customerName: Alice Johnson, issueType: Feature Request, priority: Low, status: Closed, lastUpdated: 2024-04-10 }, { ticketId: TCK1004, customerName: Sarah Dunsworth, issueType: Feature Request, priority: High, status: Closed, lastUpdated: 2024-04-10 }, ] }}在表格上方再放一个 Text 组件Data设为Tickets字号 14、灰色#9B9B9B展开属性面板的Columns区段逐个点击列并修改其Column name例如把ticketId改为ticket ID、customerName改为customer name让表头更友好。2.4 添加新页面并复用组件点击左侧边栏的Pages页面默认存在一个Home页面先将其重命名为Dashboard点击图标新建页面并重命名为Customers在Dashboard页面上框选所有组件复制Mac 为 CMDCWindows 为 CtrlC并粘贴到Customers页面把 Tickets 对应的 Text 组件Data改为Customers并为表格填入客户数据{{[ { id: 1, name: John Doe, email: john.doeexample.com, phone: 1234567890, status: Active, issuesResolved: 0 }, { id: 2, name: John Smith, email: jane.smithexample.com, phone: 1234567891, status: Inactive, issuesResolved: 0 }, { id: 3, name: Alice Johnson, email: emily.johnsonexample.com, phone: 1234567892, status: Active, issuesResolved: 1 }, { id: 4, name: Michael Brown, email: michael.brownexample.com, phone: 1234567893, status: Inactive, issuesResolved: 4 }, { id: 5, name: Sarah Dunsworth, email: michael.brownexample.com, phone: 1234567893, status: Active, issuesResolved: 1 } ]}}2.5 切换应用主题点击左侧边栏的Settings设置按钮App mode默认是Auto。切换为dark后预览应用即可看到深色配色方案保持Auto则会跟随浏览器的颜色模式。至此客服台仪表盘的可视化界面已经完成。接下来我们要为它接入真实数据。三、创建查询让 UI 与数据源交互App-Builder 底部的Query Panel查询面板负责创建和管理与已连接数据源的交互包括发起 API 请求、查询数据库以及使用 JavaScript / Python 对结果做转换或数据处理。本节内容完整继承 create-queries.md 与 query-panel.md 两篇文档。3.1 面板结构Query Manager 与 Query Editor查询面板分为左右两区Query Manager查询管理器左侧列出应用内已创建的全部查询。点击按钮弹出数据源选择菜单也可点 Add new Data Source连接新数据源。面板顶部支持筛选按数据源与排序名称 A-Z / Z-A、类型 A-Z / Z-A、最后修改时间新旧排序旁边的搜索框可快速定位查询。悬停查询名称会浮现编辑重命名、复制、删除三个操作按钮。Query Editor查询编辑器右侧配置当前选中的查询。面板中的所有修改都会自动保存。前端实现中这两个区域分别对应 QueryManager.jsx 与 QueryPanel.jsx后者的组件结构可直接印证左侧管理器 右侧编辑器的双栏布局。3.2 创建并配置查询点击 Query Panel 中的按钮从数据源列表中选择目标数据源根据数据源类型可选择GUI 模式低代码只需选择Table name与Operations或SQL 模式手写 SQL点击编辑器顶部的查询名称区域可输入描述性名称例如fetchUsers若查询需要参数点击Parameters标签旁的 Add按钮添加参数。每个参数需定义Name标识符与Default value默认值可为常量字符串、数字或对象语法为在查询中使用parameters.标识符且参数仅能在定义它的那个查询内使用。例如PostgreSQL 查询fetchUsers从allUsers表按 id 取单个用户SELECT * FROM allUsers WHERE id {{parameters.id}}3.3 查询实例对 feature_requests 表做增删改查以下示例基于一个 PostgreSQL 数据源中的feature_requests表。读取数据Read创建查询getAllRequestsSELECT * FROM feature_requests;在面板下方的Preview区可直接查看返回数据。把结果绑定到组件非常简单——在 Table 组件的Data属性中引用查询即可{{queries.getAllRequests.data}}插入数据Insert创建查询addNewRequestINSERT INTO feature_requests (id, title, description, votes, priority) VALUES (10, Toggle Component, We need a toggle component in future release., 0, 2);查询中也可以直接插入组件值用双花括号传入即可INSERT INTO feature_requests (id, title, description, votes, priority) VALUES (10, {{components.textinput1.value}}, {{components.textinput2.value}}, 0, 2);更新数据Update基于 Table 组件选中行来更新记录UPDATE feature_requests SET title Updated Feature Title, description Updated Feature Description, votes 15, priority 2 WHERE id {{components.table1.selectedRow.id}};删除数据Delete基于参数删除DELETE FROM feature_requests WHERE votes {{parameters.minimumVotes}};3.4 转换Transformations与事件Events转换取回数据后往往需要格式化过滤无用字段、转换数据类型等。ToolJet 支持用 JavaScript 或 Python 编写转换逻辑。事件处理把查询与应用事件串联实现动态交互。例如给updateRequest添加Query Success事件让它运行成功后自动触发getAllRequests从而让相关组件立即展示最新数据。查询可挂载的事件有Query Success与Query Failure两种。3.5 高级设置与调试Preview / RunPreview按钮可先测试查询、以Raw或JSON格式查看结果不会在应用内触发Run按钮才会真正在应用中执行查询。点击清除按钮可重置预览数据。Run this query on application load?是否在应用加载时自动执行该查询。Request confirmation before running query?执行前弹窗确认Yes/No防止误操作造成数据变更。Show notification on success?成功时显示 toast 通知可自定义成功消息内容与展示时长秒。四、使用自定义代码从 fx 到 Run JavaScript / Python在 ToolJet 中代码是增强与定制应用的有力手段既有fx这样的轻量动态表达式也有Run JavaScript code/Run Python code查询承载的复杂逻辑。本节完整对应 using-code.md。4.1 用 fx 动态改变组件属性在画布上拖入Number Input与Button组件点击 Button 在属性面板找到Disable条件旁的fx按钮输入{{components.numberinput1.value ? false : true}} //replace numberinput1 with the name of your check box component当 Number Input 没有输入值时按钮即被禁用。同样的原理可以编程式地设置一系列属性根据文本输入改变按钮颜色{{components.textinput1.value available ? #375FCF : #FF0000}}根据复选框控制图片组件可见性{{components.checkbox1.value ? true : false}}4.2 表格单元格转换在 Table 组件的Columns下点击列名进入Transformations默认值为{{cellValue}}加入 JavaScript 即可动态改写单元格值例如四舍五入{{cellValue 4.5 ? 5 : 4}}4.3 用 Run JavaScript code 转换查询结果在 Query Panel 点击Add并选择Run JavaScript code可以执行查询、读取数据并做转换await queries.restapi1.run(); // replace restapi1 with your query name let value queries.restapi1.getData(); // replace restapi1 with your query name function filterProductsByBrandAndRating(value.products, brand, minRating) { return products.filter(product product.brand brand product.rating minRating);} return filterProductsByBrandAndRating(value.products, Apple, 4.5) //use JavaScript code to refine the data4.4 借助 Moment.js 设置默认日期在 Datepicker 组件的Default value中输入{{moment().format(DD/MM/YYYY);}}即可把今天的日期DD/MM/YYYY 格式设为默认值。4.5 基于登录用户展示数据点击左侧边栏的Inspector展开Globals手风琴即可查看所有全局值。例如让更新 IT 工单按钮仅对 admin 可见——在按钮Visibility属性的fx中输入{{globals.currentUser.groups.includes(admin) ? true : false }}五、访问与引用值双花括号求值体系ToolJet 通过{{ }}双花括号语法在 App-Builder 中访问值或嵌入 JavaScript 代码。所有可访问的值都可以在左侧边栏的Inspector标签中查看——它按树形结构列出 queries查询、components组件、globals全局、variables变量、page页面等命名空间方便你确认数据绑定是否正确。本节内容完整继承 accessing-values.md。5.1 典型取值场景查询数据{{queries.getSalesData.data}}取getSalesData查询的返回数据组件数据{{components.table1.selectedRow.id}}取table1选中行的 id全局变量{{globals.theme.name}}取当前主题名用于动态调整样式。从源码看Inspector 的实现位于 LeftSidebarInspector.jsx与 LeftSidebar.jsx 中注册的侧边栏条目一一对应。5.2 左侧边栏的更多能力左侧边栏是导航与应用配置的枢纽主要包括Pages单个应用内管理多个页面增强组织结构与用户导航Inspector检视查询与组件关联的数据是调试与数据处理的核心工具Debugger记录并展示查询执行期间的错误如数据库不可达、REST API URL 错误可点击右上角图钉固定面板或用Clear清空全部错误分为All Log全部日志与Errors仅错误两个区段Global Settings配置应用级设置如 app slug、Header 可见性、维护模式等。实践建议多用 Inspector 核对数据绑定与排查数据流问题用 Debugger 维持应用平稳运行、快速定位错误按需在 Global Settings 中调整应用行为以适配不同用户或组织需求。六、创建与管理变量状态管理的两种途径在应用开发中管理状态与用户交互跟踪数据点、按用户过滤数据、记录偏好与导航历史等至关重要。ToolJet 的变量variables与页面变量page variables让应用内状态可以动态存取。本节完整继承 variables.md。6.1 设置变量与页面变量设置方式有事件与Run JavaScript code 查询两种通过事件添加事件处理器选择Set variable动作在Action Options中定义变量的 Key 与 Value页面变量则使用Set page variable动作。通过代码在 Run JavaScript code 查询中调用setVariable(key, value)页面变量对应setPageVariable(key, value)。6.2 用例一统计用户访问页面次数创建一个名为countVisits的 Run JavaScript code 查询function incrementPageVisit() { if (!page.variables.visitCount) { actions.setPageVariable(visitCount, 1); } else { actions.setPageVariable(visitCount, Number(page.variables.visitCount) 1); } } incrementPageVisit();然后新建名为Product Listing的页面 → 给该页面添加On page load事件处理器Action 选择Run Query并指向countVisits。此后每次用户进入该页面visitCount都会自动更新。6.3 用例二避免查询加载时表格出现 loading 状态创建两个查询getData与updateData给getData添加Query Success事件动作选setVariable把返回数据queries.getData.data存入变量loadedData在 Table 组件的Data属性中输入{{variables.loadedData}}在updateData查询上添加两个Query Success事件第一个运行getData第二个用其返回数据更新loadedData。这样表格会持续展示loadedData中的存量数据在数据拉取或更新期间不再出现加载指示器。七、版本控制与发布从开发到生产Version Control版本控制让应用可以维护多个版本、进行迭代开发并有序部署同时保障稳定性实现新功能或修复的平滑上线。例如你可以为某个新特性创建独立版本进行实验不影响已发布应用充分测试后再发布该版本从而把对用户的干扰降到最低。各版本彼此隔离并可关联不同的环境development / staging / production。本节内容完整继承 version-control.md。创建版本通过顶栏的App Version Manager下拉打开版本列表已发布版本名称显示为绿色→ 点击底部Create new version→ 输入Version Name→ 在Create version from下拉中选择作为起点的版本默认自动选最近创建的版本→ 确认创建。重命名版本在版本管理器中选中版本点击版本名旁的编辑图标修改名称。删除版本在版本管理器的下拉中找到目标版本点击删除图标移除注意已发布的版本不可删除。与之配套的顶栏能力详见 toolbar.md应用名点击顶栏左侧的应用名称即可修改桌面/移动布局一键切换画布模式在组件属性面板的Devices区段可分别打开Show on mobile/Show on desktop控制组件在两种视图下的可见性Changes Saved所有修改自动保存顶栏显示保存状态App Environment通过 Env 下拉在 Development / Staging / Production 环境间切换Undo / Redo撤销或重做画布操作也支持键盘快捷键Share应用发布后生成唯一 URL 分享链接也可编辑 URL slug 个性化Preview在新标签页预览当前版本Release仅在 Production 环境下显示用于发布当前版本。注意已发布版本会被锁定禁止编辑ToolJet 会提示你新建版本再做修改防止把未完成的应用误推上线。八、GitSync把应用与 Git 仓库同步GitSync是 ToolJet 的付费功能Paid feature它把工作区中的应用与 Git 仓库无缝同步强化版本控制、环境迁移与备份管理同时支持云托管与自托管两类 Git 提供商也可配置自定义分支。详见 gitsync overview 与配置指南 gitsync-config.md。核心使用场景应用迁移通过把变更推送到 Git 仓库在多个 ToolJet 实例之间如从 dev 到 staging 再到 production轻松迁移应用无需手工重复配置应用备份推送到 Git 仓库即为应用建立了带版本历史的安全备份机制可防范应用/版本被误删或损坏。在 App-Builder 顶栏中Gitsync图标位于版本下拉菜单旁点击即可与 GitHub 仓库同步。它配合上述的版本控制构成了代码化管理 可视化构建的完整应用交付链路。九、导入与导出应用跨工作区复用ToolJet 支持把整个应用以 JSON 文件的形式导出并在其他工作区导入。本节完整继承 import-export-apps.md。导出应用进入 Dashboard仪表盘点击应用右上角的设置图标点击Export app按钮选择Export All导出该应用所有版本或Export selected version仅导出当前选中版本结果均为 JSON 文件勾选Export ToolJet table schema可一并导出关联的 ToolJet Database 表结构——导入到新工作区时会自动重建这些表。导入应用进入 Dashboard点击Create new app按钮上的省略号三个点选择Import选择此前导出的 JSON 文件即可完成导入。除了手动导出GitSync 与版本控制为应用的迁移与备份提供了更工程化的替代路径。十、源码视角App-Builder 的前端实现脉络为便于深入理解这里给出与上述功能对应的前端源码入口均位于 frontend/src/AppBuilderLeftSidebar.jsx左侧边栏主组件从其导入清单可以看到 Pages、LeftSidebarInspector、GlobalSettings、Debugger、DependencyViewer依赖查看器等模块的注册方式以及pinned、selectedSidebarItem、queryPanelHeight等由全局 store 管理的 UI 状态LeftSidebarInspector.jsxInspector 面板实现负责呈现 queries / components / globals / variables / page 等命名空间QueryPanel.jsx 与 QueryManager.jsx底部查询面板与查询管理器的实现对应前文的双栏结构与筛选排序能力query-panel.md 文档对 Query Manager 的筛选/排序/搜索以及 Query Editor 的改名、参数、Preview、Run、转换、设置与事件做了更细的说明可作为深入阅读的下一站。结语围绕 App-Builder 概览文档 提供的八条实操链路本文完整走通了 ToolJet 应用从组件拼装 UI → 查询连接数据源 → 自定义代码增强 → 变量与值管理 → 版本发布 → GitSync 同步 → 导入导出的全流程。你可以直接按顺序阅读各篇进阶文档创建 UIcreate-ui、创建查询create-queries、使用自定义代码using-code、访问与引用值accessing-values、管理变量variables、GitSyncgitsync overview、版本控制version-control与导入导出import-export-apps在动手实践中逐步构建出属于你自己的第一个业务应用。【免费下载链接】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），仅供参考