ToolJet 2.50.0 LTS Button 组件完全指南属性、事件、组件专属动作与样式定制【免费下载链接】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/ToolJetButton按钮是 ToolJet 应用构建器中最基础也最常用的交互组件它的核心职责是触发动作无论是提交表单、跳转到其他页面还是运行一个数据查询几乎每个内部工具界面都离不开它。本篇指南以 docs/versioned_docs/version-2.50.0-LTS/widgets/button.md 为骨架结合 ToolJet 开源仓库中 Button 组件的实际源码与端到端测试系统讲解其属性、事件、组件专属动作CSA、暴露变量、附加操作、设备适配与样式定制读完你可以直接在应用画布上完成一个具备加载状态、动态显隐、可编程控制的工业级按钮。一、Button 组件的定位与使用场景在 ToolJet 中Button 组件用于触发某个动作trigger an action典型用途包括提交表单作为 Form 组件的提交按钮把表单数据写回数据库页面导航切换应用内的多页面视图触发查询点击后运行某个已配置的数据查询Query例如删除一条记录、发送消息。从源码配置看Button 组件的官方描述正是「Trigger actions: queries, alerts, set variables etc.」定义位于 frontend/src/AppBuilder/WidgetManager/widgets/button.js。组件默认尺寸为宽 4 格、高 40px拖入画布后即可通过右侧检查器Inspector进行配置。二、属性配置Properties2.1 Label标签Label 决定按钮上显示的文本接受任意字符串例如Submit。在组件配置中Label 对应properties.text字段类型为 code支持绑定表达式校验 schema 为 string定义见 button.js。2.2 Button text按钮文本PropertyDescriptionExpected ValueButton text用于设置按钮的标签文本任意String值Send Message、Delete或{{queries.xyz.data.action}}Loading state加载状态用于在按钮内容位置显示 spinner。通常配合查询的isLoading属性使用在查询运行期间展示加载状态打开开关On或点击fx以编程方式设置为{{true}}或{{false}}Button text 与 Label 本质上是同一配置项properties.text它支持动态绑定例如将按钮文本绑定到{{queries.xyz.data.action}}按钮文字就会随着查询结果实时变化。这一动态能力在源码中由setExposedVariable(buttonText, properties.text)实现见 frontend/src/AppBuilder/Widgets/Button.jsx。**Loading state加载状态**是按钮的常用进阶能力当某查询正在执行时按钮内容会替换为旋转 spinner避免用户重复提交。它对应properties.loadingState布尔开关源码见 button.js而渲染端在loading为 true 时渲染Loader color{computedLoaderColor} width16 /替代按钮文本见 Button.jsx。三、事件EventsButton 组件暴露两个内置事件EventDescriptionOn click用户点击按钮时触发On hover用户将鼠标光标悬停在按钮上时触发事件定义位于 button.js。每个事件都可以挂载一个或多个Action动作例如 Show alert弹出提示、Run query运行查询、Control component控制组件、Set variable设置变量、Open webpage打开网页等。关于全部动作的详细说明可查阅仓库中的 Action Reference 文档原始文档中的/docs/category/actions-reference指向的即是该系列文档。从渲染实现看点击与悬停分别通过handleClick触发fireEvent(onClick)和onMouseOver/onMouseLeave维护hovered状态并触发fireEvent(onHover)完成见 Button.jsx。值得注意的是点击处理还会派发一个submitForm自定义事件携带组件 id 与 moduleId供 Form 容器监听实现表单提交联动见 Button.jsx。四、组件专属动作Component Specific Actions, CSA组件专属动作允许你在运行时通过RunJS 查询或事件处理器以编程方式控制按钮相当于为组件提供了一套「遥控 API」ActionsDescriptionHow To Accessclick()控制按钮的点击行为在 RunJS 查询中执行await components.button1.click()或通过事件触发setText()设置组件标签文本在 RunJS 查询中执行await components.button1.setText(Update)或通过事件触发setVisibility()设置组件可见性在 RunJS 查询中执行await components.button1.setVisibility(false)或通过事件触发setLoading()设置组件加载状态在 RunJS 查询中执行await components.button1.setLoading(true)或通过事件触发setDisable()禁用组件在 RunJS 查询中执行await components.button1.setDisable(true)或通过事件触发这些动作与源码中的实现一一对应。在 Button.jsx 中组件通过setExposedVariables注册了click、setText、disable、visibility、loading五个内部函数随后又以独立的useEffect暴露了setLoading、setVisibility、setDisable三个「set 前缀」版本见 Button.jsx它们除了改变内部状态还会同步更新对应的暴露变量isLoading、isVisible、isDisabled。在组件注册表中button.jsclick、setText、setVisibility、setDisable、setLoading被声明为正式的 actions同时保留了三个标记为 deprecated 的旧动作disable、visibility、loading说明这是从早期版本演进后的 CSA 命名规范。实战示例跨组件控制在 RunJS 查询中写入以下代码即可实现「点击按钮 A动态修改按钮 B」的联动// 让按钮 B 显示为 Update 并进入加载状态 await components.button1.setText(Update); await components.button1.setLoading(true); // 查询完成后恢复 await components.button1.setLoading(false);端到端测试 buttonHappyPath.cy.js 完整覆盖了 CSA 流程通过selectCSA(button1, Set text, 500)设置文本、selectCSA(button1, Click)触发点击、selectCSA(button1, Disable)与selectCSA(button1, Loading)控制禁用和加载并断言按钮最终呈现disabled属性、btn-loading类名与文本内容可作为理解 CSA 语义的参考。五、暴露变量Exposed VariablesButton 组件会向应用全局暴露以下变量供其他组件或查询通过{{components.button1.xxx}}语法读取VariableDescriptionHow To AccessbuttonText存储按钮上显示的文本通过{{components.button1.buttonText}}动态访问isValid指示输入是否满足校验条件通过{{components.button1.isValid}}动态访问isLoading指示组件是否处于加载状态通过{{components.button1.isLoading}}动态访问isVisible指示组件是否可见通过{{components.button1.isVisible}}动态访问暴露变量的默认值在 button.js 中声明buttonText默认Button、isVisible默认true、isDisabled默认false、isLoading默认false。渲染端在运行时持续同步这些变量见 Button.jsx因此你可以在文本框的默认值、查询参数或另一个按钮的文本中直接引用{{components.button1.isLoading}}来实现状态联动。六、附加操作Additional ActionsActionDescriptionConfiguration OptionsLoading state启用加载 spinner常与isLoading搭配表示进行中的操作通过开关启用/禁用或点击fx输入逻辑表达式动态配置Visibility控制组件可见性通过开关启用/禁用或点击fx输入逻辑表达式动态配置Disable启用或禁用组件通过开关启用/禁用或点击fx输入逻辑表达式动态配置Tooltip悬停时提供附加信息提示设置字符串值进行显示字符串值例如Button to Submit Form这些附加操作在配置层面对应 button.js 中的loadingState、visibility、disabledState、tooltip属性均位于section: additionalActions分组。值得注意的是Tooltip 还支持tooltipFormat开关可在Plain text / Markdown / HTML三种渲染格式之间切换见 button.js让提示信息可以携带富文本样式。渲染端对禁用状态的处理值得关注disable与loading均会阻止点击canClick !disable !loading且按钮在禁用时透明度降为 50%并同步输出aria-disabled、aria-busy、aria-hidden无障碍属性见 Button.jsx兼顾了交互一致性与可访问性。七、设备适配DevicesShow on desktop使组件在桌面视图中可见。可通过开关设置或点击fx输入逻辑表达式动态配置。Show on mobile使组件在移动视图中可见。可通过开关设置或点击fx输入逻辑表达式动态配置。设备开关定义在 button.js 的others段默认配置为桌面显示showOnDesktop: {{true}}、移动端隐藏showOnMobile: {{false}}见 button.js。对于移动端优先的应用记得将 Show on mobile 打开。八、样式定制Styles8.1 Button 样式Button PropertyDescriptionConfiguration OptionsType设置按钮的填充方式选择Solid实心背景或Outline透明背景 轮廓Background设置组件背景色选择颜色或点击fx输入返回 Hex 颜色码的代码Text color设置组件中文本的颜色选择颜色或点击fx输入返回 Hex 颜色码的代码Border color设置组件边框颜色选择颜色或点击fx输入返回 Hex 颜色码的代码Loader color设置加载器颜色选择颜色或点击fx输入返回 Hex 颜色码的代码Icon为组件选择一个图标启用图标可见性、选择图标与图标颜色也可用fx编程设置Border radius修改组件圆角输入数字或点击fx输入返回数值的代码Box shadow设置组件阴影属性选择阴影颜色并调整相关属性或用fx编程设置这些样式在配置层面对应 button.js 的styles段。有几个值得展开的细节Type 双态与条件渲染Type 只有primarySolid与outlineOutline两个取值。源码中当类型为 primary 时使用品牌色背景var(--cc-primary-brand)为 outline 时背景强制透明transparent见 Button.jsx。同时 Background、Hover background、Box shadow 等样式仅在 primary 类型下渲染通过conditionallyRender控制避免无效配置。Hover 背景模式除文档表格外仓库还提供了hoverBackgroundModeAuto/Manual与hoverBackgroundColor两个悬停态配置见 button.jsAuto 模式由getModifiedColor自动推导悬停色Manual 模式允许你指定精确颜色见 Button.jsx。文字排印字体大小默认 14px、行高为字号 × 1.42、图标尺寸为行高 × 0.8字号与字重normal/medium/bold/lighter/bolder均可独立配置见 Button.jsx 与 button.js。图标与内容对齐Icon 支持图标可见性开关、图标选择与颜色图标方向direction与内容对齐方式contentAlignment可组合出「图标在左/右 左/中/右对齐」的多种布局见 Button.jsx。8.2 Container 样式Padding内边距启用Default选项可保持标准内边距。代码中padding取值default或none见 button.js当高度为 36px 且 padding 为 default 时按钮高度取 36px否则在设定高度基础上 4px 以容纳内边距见 Button.jsx。九、端到端验证测试如何确认组件行为ToolJet 仓库为 Button 组件维护了专门的 Cypress 端到端测试 buttonHappyPath.cy.js可用于验证本指南中几乎所有特性属性验证修改 Label 后断言画布按钮文本变化并通过检查器树确认组件重命名生效Loading state 验证打开 Additional Actions 手风琴切换 Loading state断言按钮出现btn-loading类名关闭后类名消失见 buttonHappyPath.cy.js事件验证为 On click 添加 Show alert 动作后点击画布按钮断言 toast 提示弹出见 buttonHappyPath.cy.js样式验证通过verifyWidgetColorCss断言背景色、文字色、加载器颜色的实际 CSS 值并通过border-radius断言圆角样式见 buttonHappyPath.cy.js删除操作验证覆盖了从右侧面板删除与键盘 Backspace 删除两种方式删除后断言组件不可见且刷新后依然消失见 buttonHappyPath.cy.js。配套的工具函数 cypress-tests/cypress/support/utils/button.js 还提供了组件复制场景下的数据校验addBasicData/verifyBasicData验证 Label、Tooltip、背景色在复制后完整继承。十、综合实战构建一个带加载态与动态控制的按钮结合上述全部能力一个典型的「提交并禁用」按钮配置流程如下拖入组件从左侧组件面板把 Button 拖到画布默认名button1绑定文本在 Properties 中把 Button text 设置为Submit Order或绑定{{queries.createOrder.data.action}}绑定加载态打开 Loading state 开关并点击fx输入{{queries.createOrder.isLoading}}使查询运行期间按钮自动显示 spinner 并禁止重复点击配置事件在 On click 事件中添加 Run query 动作选择createOrder查询若需先校验可再添加 Show alert动态控制若想在特定业务条件下强制禁用按钮在 RunJS 查询中写入await components.button1.setDisable({{globals.currentUser.role ! admin}})样式微调Type 选择 Solid调整 Background、Border radius如6、Box shadow必要时通过 Icon 增加视觉提示并在 Container 中保持 Padding 为 Default。运行预览后按钮会在查询执行时自动进入加载态、完成后恢复整个交互完全由声明式配置驱动无需编写任何传统的前端逻辑。结语Button 组件虽然基础却是 ToolJet 交互体系中最具代表性的「触发器」它同时具备事件动作On click / On hover、组件专属动作CSA、暴露变量、加载态与完善的样式系统能够以纯配置方式覆盖提交、导航、查询触发等绝大多数内部工具场景。通过本指南结合 Button 组件源码、组件配置注册表 与端到端测试你既可以在界面上快速完成配置也能深入理解其底层实现为更复杂的组件联动与二次开发打下基础。【免费下载链接】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），仅供参考