ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

ToolJet Events 深入解析:触发器类型、Action 全目录与事件链执行机制

ToolJet Events 深入解析:触发器类型、Action 全目录与事件链执行机制 ToolJet Events 深入解析触发器类型、Action 全目录与事件链执行机制【免费下载链接】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 文档站中 Events事件概念页展开先还原事件系统的核心模型——触发器、Action 与可串联的事件链再结合 App Builder 前端源码事件配置面板EventManager.jsx、Action 目录ActionTypes.js、事件执行引擎eventsSlice.js逐层剖析事件从配置到执行的完整链路。读完本文你将能够独立完成事件处理器的配置、理解事件在源码中的分派与按序执行机制并掌握onDataQuerySuccess等关键事件实现查询完成后再执行下一步的典型模式。一、什么是事件触发器、动作与事件链ToolJet 官方文档对事件的定义是Events 用于在触发器例如按钮点击、查询执行完成发生时运行查询、弹出告警等其它功能并且多个事件可以被串联chained起来执行一系列逻辑操作——例如一个查询完成后可以触发另一个事件去运行第二个查询以此类推。这样一次用户交互比如点击按钮就能引发一长串事件链。这句话里其实包含了三个核心概念概念含义源码/文档对应Trigger触发器触发事件的时机如按钮点击、页面加载、查询成功/失败组件元定义中的events表、data_query类型事件Action动作事件被触发后实际执行的操作如运行查询、显示告警ActionTypes.js 中的 22 个 Action事件链Chain一个事件的 Action 结果如查询完成再触发后续事件形成串联执行onDataQuerySuccess/onDataQueryFailure事件分派从源码结构看事件、事件源、Action 三者是松耦合的每个事件都记录自己挂在什么资源上事件源以及要做什么actionId执行引擎只负责按源筛选、按序执行不关心具体 Action 的内部实现。二、事件源Source组件、页面、查询在 EventManager.jsx 中事件面板通过sourceId挂载对象的 ID与eventSourceType源类型两个字段定位事件列表return event.sourceId sourceId event.target eventSourceType;eventSourceType在源码的埋点逻辑中显式分为三类见postHogEventType的 switch 分支component组件挂在具体组件上如按钮的onClick、输入框的onChangepage页面挂在页面上最典型的是onPageLoad页面加载完成****data_query查询**挂在数据查询上典型事件是onDataQuerySuccess与onDataQueryFailure它们是查询完成后再做事这一事件链模式的枢纽。这一点在事件执行引擎 eventsSlice.js 中可以直接印证。onEvent方法对不同事件名做了显式分派onPageLoad页面加载后执行对应页面下的 ActiononDataQuerySuccess/onDataQueryFailure查询成功或失败时执行挂在查询上的 Action一个包含onClick、onChange、onDoubleClick、onHover、onSubmit、onRowClicked、onCellValueChanged、onFocus、onBlur等约 60 个事件名的长列表统一走executeActionsForEventId通用执行路径——这就是各类组件事件各组件具体支持哪些事件见其各自文档的落点。此外还有若干特殊事件onTableActionButtonClicked表格行操作按钮点击、OnTableToggleCellChanged与OnTableButtonColumnClicked表格列内交互、onNavigationItemClicked导航项点击优先级为具体菜单项事件 组件级事件、onCalendarEventSelect/onCalendarSlotSelect日历组件。三、配置事件处理器New Event Handler 完整流程原文档给出的操作路径是进入按钮组件的配置面板点击New Event Handler定义 Event 和要执行的 ActionAction 可以是运行查询、显示告警甚至切换到另一个页面。结合 EventManager.jsx 源码把这个流程拆解成可验证的细节3.1 新建事件时的默认值addHandler函数显示点击 New Event Handler 后立即调用后端接口创建事件默认载荷为{ event: { eventId: selectedEventId, // 默认取组件元定义中第一个可用事件 actionId: show-alert, // 默认动作为显示告警 message: Hello world!, // 默认告警文案 alertType: info, // 默认为 Info 类型 component: eventMetaDefinition.name, }, name: getDefaultEventName(sourceEvents), // 命名为 Event #N 递增 eventType: eventSourceType, // component / page / data_query attachedTo: sourceId, // 挂载的资源 ID index: eventIndex 1, // 排序号 当前最大 index 1 }也就是说新建的事件默认是一个显示 Info 告警、文案 Hello world!的占位事件事件名自动取Event #1、Event #2……由getDefaultEventName解析已有Event #N名称后递增。创建请求最终落到 eventsSlice.js 的createAppVersionEventHandlers通过appVersionService.createAppVersionEventHandler(appId, versionId, event)持久化到 App Version成功后再写回前端 store 并显示在面板中。3.2 事件编辑面板的字段构成打开某个事件的编辑弹层后可配置项与源码中的表单字段一一对应字段说明源码依据Enable event启用开关对应event.disabled禁用后执行引擎直接跳过该事件executeAction开头if (event?.disabled) return falseEvent name事件显示名仅用于辨识handlerChanged(index, name, ...)Event事件下拉候选项来自组件/页面/查询的元定义eventMetaDefinition.events展示displayNamepossibleEvents构造逻辑Action动作下拉候选项来自 Action 目录按分组展示见下节groupedOptions按action.group聚合Run Only If条件表达式只有解析为真值时 Action 才执行executeAction中event.runOnlyIf→getResolvedValue判空Debounce防抖毫秒延迟指定毫秒后再执行默认留空例如填300表示 300ms 后执行事件参考文档 show-alert.mdhandlerChanged中对空值debounce的清理逻辑Duplicate / Delete复制自动追加 copy 命名、index 取最大值 1或删除duplicateHandler/removeHandler面板中的注释明确说明了排序语义indexis the source of truth for list position and trigger order——列表展示顺序和触发顺序都以index字段为准而不是存储数组的物理顺序。删除事件后 index 允许出现空洞复制/新建时都取max(index) 1以避免冲突。四、Action 全目录22 个内置动作分组速查原文档提到Action 可以是运行查询、显示告警、切换页面。完整的动作目录定义在 ActionTypes.js按group分为五组共 22 个 Action每个都带有actionId、分组和默认参数分组groupAction显示名actionId关键参数run-actionRun queryrun-queryqueryId 参数表run-actionReset queryreset-queryqueryIdrun-actionAbort queryabort-queryqueryIdrun-actionShow Alertshow-alertmessage、alertTypecontrol-componentControl componentcontrol-componentcomponent、action组件动作句柄control-componentShow modalshow-modalmodalcontrol-componentClose modalclose-modalmodalcontrol-componentSet table pageset-table-pagetable、pageIndex默认{{1}}control-componentScroll component into viewscroll-component-into-viewcomponentId、scrollBehavior默认 smooth、scrollBlock默认 nearestnavigationSwitch pageswitch-pagepagenavigationGo to appgo-to-app目标 App queryParamsnavigationOpen webpageopen-webpageurl、打开方式新标签/当前标签variableSet page variableset-page-variablekey、valuevariableUnset page variableunset-page-variablekeyvariableUnset all page variablesunset-all-page-variables—variableSet variableset-custom-variablekey、valuevariableUnset variableunset-custom-variablekeyvariableUnset all variablesunset-all-custom-variables—otherLogoutlogout—otherGenerate filegenerate-filefileTypecsv/plaintext/pdf、fileName、dataotherSet local storageset-localstorage-valuekey、valueotherCopy to clipboardcopy-to-clipboard待复制内容otherToggle app modetoggle-app-modeappMode执行端与这份目录完全对齐eventsSlice.js 的executeAction用switch (event.actionId)逐一实现。几个值得注意的实现细节show-alertmessage先经getResolvedValue做变量解析支持{{...}}表达式对象值会被JSON.stringifyalertType支持info/success/warning/error四种分别映射到不同的 toast 形态其中 warning 带⚠️图标run-query参数逐项解析后调用queryPanel.runQuery若选中的是模块Module输入对应的占位查询会先换算成画布上真实查询的 ID 再执行未选查询时抛出No query selected并写入调试器go-to-app编辑态下打开新标签前会弹确认框The app will be opened in a new tab as the action is triggered from the editor.查看态下直接_self跳转支持queryParams追加查询参数control-component通过组件元定义的actions列表找到动作句柄handle解析参数后以action(...args)方式调用组件暴露的方法Form 容器内的子组件会先定位父容器再取children——这是组件专属动作component-specific actions的底层机制generate-file支持 csv / plaintext / pdf 三种类型数据为空对象时文件名兜底为data.txt。每个 Action 的详细参数说明可查阅文档站 Actions Reference 目录如 Show Alert 参考页、Actions 总览以及各组件文档中列出的组件事件。五、事件链的执行机制按 index 串行 await事件可以串联在源码中的落地是executeActionsForEventId方法核心逻辑非常直白executeActionsForEventId: async (eventId, events [], mode, customVariables, moduleId canvas) { if (!events || !Array.isArray(events) || events.length 0) return; const filteredEvents events ?.filter((event) event?.event.eventId eventId !event?.event?.disabled) ?.sort((a, b) a.index - b.index); // 按 index 升序 for (const event of filteredEvents) { await get().eventsSlice.executeAction(event, mode, customVariables, moduleId); // 逐个 await } }这揭示了事件链的两个保证顺序性同一事件源下、同一eventId的多个事件按index升序执行阻塞性使用await串行等待每个 Action 的 Promise 完成前一个 Action如run-query未完成时不会开始下一个。因此先跑查询 A成功后再跑查询 B这类顺序依赖是可靠的。典型链路按钮 → 查询 → 成功告警原文档给出的完整示例——点击按钮刷新数据并在刷新成功后弹出确认告警——对应的正是文档中的事件配置截图其配置与执行路径为按钮的onClick事件component源Action run-query选择目标查询查询的onDataQuerySuccess事件data_query源Action show-alertalertTypesuccess。执行时组件点击经fireEvent→onComponentClickEvent→executeActionsForEventId(onClick, ...)触发查询查询成功后数据层回发onDataQuerySuccess事件onEvent中专门为其保留了await executeActionsForEventId(...)分支从而弹出刷新成功告警。失败场景则挂在onDataQueryFailure上天然构成成功/失败双分支。一个容易被忽略的工程细节fireEvent在执行前会先调用flushImplicitBatchEntries()把触发前仍在待提交批次中的组件写入可能来自本组件或别的组件先刷落盘——否则事件 Action 会读到过期状态。这保证了用户刚改完输入值再点击按钮这类场景下事件读到的是最新值。六、出错时的行为内置错误日志事件/Action 执行失败不会静默失败。executeAction中run-query、go-to-app、control-component等分支捕获异常后统一调用logError最终写入调试器debugger日志头会带上完整的定位信息[Page 页面名] [Component 组件名] [Event 事件ID] [Action 动作ID] [Query 查询名] [Event 事件ID] [Action 动作ID] // 查询源事件logError会根据sourceId反查组件名/查询名并区分错误归属Component Event/Event Errors with query/Event Errors with page因此事件链中任何一环出错都能在看板调试器里按页 → 组件/查询 → 事件 → 动作四级定位。七、配置入口与相关资源组件/页面/查询上的事件在画布中选中目标对象打开 Inspector配置面板点击New Event Handler按启用开关 → 事件名 → Event → Action → Run Only If / Debounce → Action 专属参数的顺序配置即可具体某组件支持哪些事件以其各自文档为准见 ToolJet 概念目录。查询与查询事件的上下文事件链的起点通常是一个查询查询的创建与参数机制见 Queries 概念页。RunJS 触发 Action除可视化配置外Action 还可以从 JavaScript 代码RunJS 查询中触发适合基于用户交互或定时任务动态发起动作见 Actions 概念页。源码入口事件面板 UI 在 EventManager.jsxAction 目录在 ActionTypes.js执行引擎与持久化在 eventsSlice.js。综上ToolJet 的事件系统 事件源组件/页面/查询× 事件名触发时机× Action22 个内置动作通过index排序 串行 await 提供可预测的事件链并以runOnlyIf、disabled、debounce三个字段提供条件执行、启停与防抖控制。理解这套模型后从按钮刷新数据到复杂多查询编排都可以用同一套配置范式完成。【免费下载链接】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),仅供参考
返回列表