ToolJet Tabs 组件使用指南属性配置、事件触发、组件特定动作与样式定制version-2.50.0-LTS【免费下载链接】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/ToolJetTabs 是 ToolJet 应用编辑器中用于组织页面空间的核心布局组件它把多个容器收纳进可切换的标签页中每个标签页内部又可以继续拖入任意其他组件非常适合构建概览/详情/设置这类多视图应用。读完本文你将掌握 Tabs 组件的完整属性定义、事件与组件特定动作CSA的调用方式、暴露变量的动态访问方法以及从源码层面理解其渲染与状态管理原理。Tabs 组件概述Tabs组件包含一组预定义的容器用户可以通过点击标签在多个容器之间切换。每个标签页本质上就是一个容器可以在其中放置不同的组件因此它天然具备分区布局 内容复用的能力例如在同一个页面内组织表单的不同分组、工作台的多个功能面板等。在 ToolJet 前端仓库中Tabs 组件的运行时代码位于 frontend/src/AppBuilder/Widgets/Tabs/Tabs.jsx其配置清单属性、事件、样式、动作、暴露变量统一声明在 frontend/src/AppBuilder/WidgetManager/widgets/tabs.js后续各节会结合这两份源码逐步展开。:::caution 受限组件 为了避免布局过于复杂Calendar日历和Kanban看板这两个组件被限制通过拖拽放入 Tabs 组件中。如果构建者在 Tabs 内尝试添加上述组件将看到如下错误提示Restricted component cannot be used as a child component within the Tabs.:::该限制并不是运行时行为而是编辑器的拖拽校验逻辑在 frontend/src/AppBuilder/WidgetManager/configs/restrictedWidgetsConfig.js 中定义了Tabs: [Calendar, Kanban]的映射编辑器在拖拽放置时会根据这张白名单/黑名单表拦截非法的父子组合。属性PropertiesTabsTabs属性用于增删 Tabs 组件中的容器。数组中的每个对象代表一个标签页包含唯一的id、title标签标题以及可选的disabled禁用单个标签。该字段期望接收一个对象数组示例{{[ { title: Home, id: 0 }, { title: Profile, id: 1,disabled:true }, { title: Settings, id: 2 } ]}}在源码 tabs.js 中该属性被定义为一个code类型的字段其校验 schema 要求元素必须是包含id的对象id允许字符串或数字默认值即上面的 Home / Profile / Settings 三项。运行时组件会为未提供id的标签页按数组下标自动补齐 id见 Tabs.jsx因此即使只写{ title: A }也能正常工作。为 Tabs 添加背景色你可以使用backgroundColor属性为每个标签页指定不同的颜色值可以是十六进制颜色码也可以是颜色名称{{[ { title: Home, id: 0, backgroundColor: #81D4FA }, { title: Profile, id: 1, backgroundColor: blue }, { title: Settings, id: 2, backgroundColor: #ecf0f1} ]}}该颜色的生效逻辑在 Tabs.jsx当currentTab变化时组件会从parsedTabs中找到当前 tab 的backgroundColor命中则作为标签内容区的背景色否则回退到样式面板中的commonBackgroundColor默认var(--cc-surface1-surface)。默认标签页Default tabDefault tab属性用于指定组件初始激活的标签页取值必须与上方 Tabs 数组中某个容器的id一致。默认值为0。在运行时代码中默认标签页不仅决定初始渲染还会被持续监听一旦parsedDefaultTab变化组件会同步切换当前激活标签Tabs.jsx。此外还有一层防御逻辑——如果配置的默认 id 不存在于可见标签列表中会自动回退到第一个可见标签Tabs.jsx避免应用启动时出现空白页。隐藏标签Hide tabHide tab用于隐藏上方 Tabs 属性中定义的所有标签标题即标签导航栏本身。它接受布尔值既可以通过开关设置也可以点击fx按钮以编程方式配置。从源码看该值会经过resolveWidgetFieldValue解析Tabs.jsx因此支持{{true}}这类动态表达式为true时导航栏display: none组件退化为只显示当前标签内容的区域容器。仅渲染激活标签页Render only active tab当开启该选项时组件只会渲染当前激活的标签页内容关闭时则渲染全部标签页内容。源码中对应的渲染判定位于shouldRenderTabContentTabs.jsx开启时仅currentTab匹配的标签页进入渲染关闭时所有标签页都会渲染页面切换时仅通过 CSS 控制显隐。需要注意文档描述该选项默认开启而 tabs.js 中renderOnlyActiveTab的defaultValue为false即从当前仓库源码看默认渲染全部标签页实际行为以所部署版本为准。其他可用属性源码补充除文档列出的属性外Tabs 组件在 tabs.js 中还有以下常用属性属性类型默认值说明scrollToTopOnTabSwitchtogglefalse切换标签时是否将内容区滚动到顶部仅在渲染全部标签页renderOnlyActiveTab为 false时可见。实现见 Tabs.jsxdynamicHeighttogglefalse开启后标签内容高度随内容自动伸缩仅查看模式生效useDynamicOptionstogglefalse开启后tabs数组可绑定动态数据源数据变化时标签列表实时更新loadingStatetogglefalse开启后组件显示骨架屏shimmer与加载动画disabledStatetogglefalse锁定整个组件禁止交互inert化处理visibilitytoggletrue组件整体显隐控制collapseWhenHiddentogglefalse隐藏时是否折叠占用空间tooltip/tooltipFormatcode / switch空 /plainText为组件设置提示文案支持纯文本、Markdown 与 HTML此外每个标签页在内部还维护了icon、iconVisibility、loading、disable、visible、fieldBackgroundColor等字段见 tabs.js分别控制标签图标、单个标签的加载/禁用/显隐状态与独立背景色。事件EventsTabs 组件暴露以下事件事件描述On tab switch当标签页发生切换时触发在运行时无论是用户点击标签还是通过 CSA 调用setTab切换组件都会调用fireEvent(onTabSwitch)Tabs.jsx 与 Tabs.jsx从而触发你在事件面板中绑定的处理器。事件处理器中可以执行任意 ToolJet 动作例如切换页面、运行查询、设置全局变量或调用其他组件的动作详细动作清单可参考 Action Reference 相关文档。组件特定动作Component Specific ActionsCSATabs 组件支持通过组件特定动作CSA进行编程式控制。CSA 既可以在事件处理器中触发也可以通过 RunJS 查询调用动作描述访问方式setTab通过组件特定动作设置 Tabs 组件当前的标签页使用 RunJS 查询执行组件特定动作如await components.tabs1.setTab(1)在 tabs.js 的动作清单中setTab接收一个id参数。其实现位于 Tabs.jsx切换前会比较当前标签若目标 id 不同则更新currentTab、同步暴露currentTab/currentTabTitle变量、触发onTabSwitch事件并清空画布选中状态。除了文档中的setTab源码还内置了更多 CSAtabs.js动作参数说明setVisibilityvaluetoggle设置组件整体可见性setDisablevaluetoggle设置组件整体禁用状态setLoadingvaluetoggle设置组件加载状态setTabDisabletabId、value禁用/启用单个标签页setTabLoadingtabId、value设置单个标签页的加载状态setTabVisibilitytabId、value显示/隐藏单个标签页其中tabId参数为动态选项选项来源是component.definition.properties.tabItems.value即当前组件定义的标签列表。暴露变量Exposed Variables变量描述访问方式currentTab保存 Tabs 组件当前选中标签页的 id通过 JS 动态访问{{components.tabs1.currentTab}}源码中currentTab由 React state 驱动并通过setExposedVariables同步给外部Tabs.jsx因此你可以在任意查询、条件表达式或文本渲染中读取它例如根据当前标签页动态切换数据源查询条件。除currentTab外组件还暴露了currentTabTitle当前标签标题、isVisible、isDisabled、isLoading等变量tabs.js方便在 Inspector 面板和表达式中引用。动作Actions在事件处理器中动作列表为 Tabs 组件提供了快捷操作入口动作描述属性setTab设置当前标签页id该动作与 CSA 的setTab底层共用同一实现setCurrentTab 暴露变量更新 onTabSwitch事件触发区别仅在于触发入口动作Actions在事件面板中通过可视化配置CSA 则在 RunJS 或表达式中以代码方式调用。设备可见性Devices属性描述期望值Show on desktop控制组件在桌面端视图是否可见通过开关设置或点击fx输入逻辑表达式动态配置Show on mobile控制组件在移动端视图是否可见通过开关设置或点击fx输入逻辑表达式动态配置这两个开关对应 tabs.js 中的showOnDesktop/showOnMobile配置默认值分别为{{true}}与{{false}}即默认桌面端显示、移动端隐藏。样式Styles样式描述Highlight color通过输入十六进制颜色码或使用取色器更改选中标签的高亮颜色Tab width标签宽度可设置为auto自适应或equally split均分Visibility开关控制组件可见性可通过fx编程配置。为{{false}}时应用部署后组件不可见默认{{true}}Disable默认关闭开启后锁定组件使其不可交互。可通过fx设置为{{true}}时组件被锁定默认{{false}}:::info 任何带有fx按钮的属性都可以进行编程式配置。 :::在源码层面Tabs 的样式定义比文档更丰富tabs.js 将样式分为Tabs与Container两个手风琴分组Tabs 分组headerBackground导航栏背景、divider分隔线颜色、unselectedText未选中文字颜色默认#375FCF、selectedText选中文字颜色、hoverBackground悬停背景、unselectedIcon/selectedIcon图标颜色、accent选中标签下划线强调色默认品牌色、tabWidthauto/split、transition切换动效slide滑动 /none无。Container 分组commonBackgroundColor标签内容区公共背景色、border边框、borderRadius圆角默认 6、boxShadow阴影、paddingdefault/none。其中tabWidth: split时每个标签按可见标签数均分宽度计算公式为100 / visibleCountTabs.jsxtransition: slide时标签内容区采用 300ms 的 transform/opacity 过渡动画Tabs.jsx。实战建议组合使用事件与 CSA一个典型的联动场景是在 Tabs 的On tab switch事件中运行一个查询查询条件引用{{components.tabs1.currentTab}}从而让不同标签页展示不同数据集同时通过 RunJS 调用await components.tabs1.setTab(1)在表单提交成功后自动跳转到结果标签页。这种事件驱动 编程控制的组合方式可以覆盖绝大多数多视图内部工具页面的交互需求。【免费下载链接】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），仅供参考 ToolJet Tabs 组件使用指南：属性配置、事件触发、组件特定动作与样式定制（version-2.50.0-LTS）
ToolJet Tabs 组件使用指南属性配置、事件触发、组件特定动作与样式定制version-2.50.0-LTS【免费下载链接】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/ToolJetTabs 是 ToolJet 应用编辑器中用于组织页面空间的核心布局组件它把多个容器收纳进可切换的标签页中每个标签页内部又可以继续拖入任意其他组件非常适合构建概览/详情/设置这类多视图应用。读完本文你将掌握 Tabs 组件的完整属性定义、事件与组件特定动作CSA的调用方式、暴露变量的动态访问方法以及从源码层面理解其渲染与状态管理原理。Tabs 组件概述Tabs组件包含一组预定义的容器用户可以通过点击标签在多个容器之间切换。每个标签页本质上就是一个容器可以在其中放置不同的组件因此它天然具备分区布局 内容复用的能力例如在同一个页面内组织表单的不同分组、工作台的多个功能面板等。在 ToolJet 前端仓库中Tabs 组件的运行时代码位于 frontend/src/AppBuilder/Widgets/Tabs/Tabs.jsx其配置清单属性、事件、样式、动作、暴露变量统一声明在 frontend/src/AppBuilder/WidgetManager/widgets/tabs.js后续各节会结合这两份源码逐步展开。:::caution 受限组件 为了避免布局过于复杂Calendar日历和Kanban看板这两个组件被限制通过拖拽放入 Tabs 组件中。如果构建者在 Tabs 内尝试添加上述组件将看到如下错误提示Restricted component cannot be used as a child component within the Tabs.:::该限制并不是运行时行为而是编辑器的拖拽校验逻辑在 frontend/src/AppBuilder/WidgetManager/configs/restrictedWidgetsConfig.js 中定义了Tabs: [Calendar, Kanban]的映射编辑器在拖拽放置时会根据这张白名单/黑名单表拦截非法的父子组合。属性PropertiesTabsTabs属性用于增删 Tabs 组件中的容器。数组中的每个对象代表一个标签页包含唯一的id、title标签标题以及可选的disabled禁用单个标签。该字段期望接收一个对象数组示例{{[ { title: Home, id: 0 }, { title: Profile, id: 1,disabled:true }, { title: Settings, id: 2 } ]}}在源码 tabs.js 中该属性被定义为一个code类型的字段其校验 schema 要求元素必须是包含id的对象id允许字符串或数字默认值即上面的 Home / Profile / Settings 三项。运行时组件会为未提供id的标签页按数组下标自动补齐 id见 Tabs.jsx因此即使只写{ title: A }也能正常工作。为 Tabs 添加背景色你可以使用backgroundColor属性为每个标签页指定不同的颜色值可以是十六进制颜色码也可以是颜色名称{{[ { title: Home, id: 0, backgroundColor: #81D4FA }, { title: Profile, id: 1, backgroundColor: blue }, { title: Settings, id: 2, backgroundColor: #ecf0f1} ]}}该颜色的生效逻辑在 Tabs.jsx当currentTab变化时组件会从parsedTabs中找到当前 tab 的backgroundColor命中则作为标签内容区的背景色否则回退到样式面板中的commonBackgroundColor默认var(--cc-surface1-surface)。默认标签页Default tabDefault tab属性用于指定组件初始激活的标签页取值必须与上方 Tabs 数组中某个容器的id一致。默认值为0。在运行时代码中默认标签页不仅决定初始渲染还会被持续监听一旦parsedDefaultTab变化组件会同步切换当前激活标签Tabs.jsx。此外还有一层防御逻辑——如果配置的默认 id 不存在于可见标签列表中会自动回退到第一个可见标签Tabs.jsx避免应用启动时出现空白页。隐藏标签Hide tabHide tab用于隐藏上方 Tabs 属性中定义的所有标签标题即标签导航栏本身。它接受布尔值既可以通过开关设置也可以点击fx按钮以编程方式配置。从源码看该值会经过resolveWidgetFieldValue解析Tabs.jsx因此支持{{true}}这类动态表达式为true时导航栏display: none组件退化为只显示当前标签内容的区域容器。仅渲染激活标签页Render only active tab当开启该选项时组件只会渲染当前激活的标签页内容关闭时则渲染全部标签页内容。源码中对应的渲染判定位于shouldRenderTabContentTabs.jsx开启时仅currentTab匹配的标签页进入渲染关闭时所有标签页都会渲染页面切换时仅通过 CSS 控制显隐。需要注意文档描述该选项默认开启而 tabs.js 中renderOnlyActiveTab的defaultValue为false即从当前仓库源码看默认渲染全部标签页实际行为以所部署版本为准。其他可用属性源码补充除文档列出的属性外Tabs 组件在 tabs.js 中还有以下常用属性属性类型默认值说明scrollToTopOnTabSwitchtogglefalse切换标签时是否将内容区滚动到顶部仅在渲染全部标签页renderOnlyActiveTab为 false时可见。实现见 Tabs.jsxdynamicHeighttogglefalse开启后标签内容高度随内容自动伸缩仅查看模式生效useDynamicOptionstogglefalse开启后tabs数组可绑定动态数据源数据变化时标签列表实时更新loadingStatetogglefalse开启后组件显示骨架屏shimmer与加载动画disabledStatetogglefalse锁定整个组件禁止交互inert化处理visibilitytoggletrue组件整体显隐控制collapseWhenHiddentogglefalse隐藏时是否折叠占用空间tooltip/tooltipFormatcode / switch空 /plainText为组件设置提示文案支持纯文本、Markdown 与 HTML此外每个标签页在内部还维护了icon、iconVisibility、loading、disable、visible、fieldBackgroundColor等字段见 tabs.js分别控制标签图标、单个标签的加载/禁用/显隐状态与独立背景色。事件EventsTabs 组件暴露以下事件事件描述On tab switch当标签页发生切换时触发在运行时无论是用户点击标签还是通过 CSA 调用setTab切换组件都会调用fireEvent(onTabSwitch)Tabs.jsx 与 Tabs.jsx从而触发你在事件面板中绑定的处理器。事件处理器中可以执行任意 ToolJet 动作例如切换页面、运行查询、设置全局变量或调用其他组件的动作详细动作清单可参考 Action Reference 相关文档。组件特定动作Component Specific ActionsCSATabs 组件支持通过组件特定动作CSA进行编程式控制。CSA 既可以在事件处理器中触发也可以通过 RunJS 查询调用动作描述访问方式setTab通过组件特定动作设置 Tabs 组件当前的标签页使用 RunJS 查询执行组件特定动作如await components.tabs1.setTab(1)在 tabs.js 的动作清单中setTab接收一个id参数。其实现位于 Tabs.jsx切换前会比较当前标签若目标 id 不同则更新currentTab、同步暴露currentTab/currentTabTitle变量、触发onTabSwitch事件并清空画布选中状态。除了文档中的setTab源码还内置了更多 CSAtabs.js动作参数说明setVisibilityvaluetoggle设置组件整体可见性setDisablevaluetoggle设置组件整体禁用状态setLoadingvaluetoggle设置组件加载状态setTabDisabletabId、value禁用/启用单个标签页setTabLoadingtabId、value设置单个标签页的加载状态setTabVisibilitytabId、value显示/隐藏单个标签页其中tabId参数为动态选项选项来源是component.definition.properties.tabItems.value即当前组件定义的标签列表。暴露变量Exposed Variables变量描述访问方式currentTab保存 Tabs 组件当前选中标签页的 id通过 JS 动态访问{{components.tabs1.currentTab}}源码中currentTab由 React state 驱动并通过setExposedVariables同步给外部Tabs.jsx因此你可以在任意查询、条件表达式或文本渲染中读取它例如根据当前标签页动态切换数据源查询条件。除currentTab外组件还暴露了currentTabTitle当前标签标题、isVisible、isDisabled、isLoading等变量tabs.js方便在 Inspector 面板和表达式中引用。动作Actions在事件处理器中动作列表为 Tabs 组件提供了快捷操作入口动作描述属性setTab设置当前标签页id该动作与 CSA 的setTab底层共用同一实现setCurrentTab 暴露变量更新 onTabSwitch事件触发区别仅在于触发入口动作Actions在事件面板中通过可视化配置CSA 则在 RunJS 或表达式中以代码方式调用。设备可见性Devices属性描述期望值Show on desktop控制组件在桌面端视图是否可见通过开关设置或点击fx输入逻辑表达式动态配置Show on mobile控制组件在移动端视图是否可见通过开关设置或点击fx输入逻辑表达式动态配置这两个开关对应 tabs.js 中的showOnDesktop/showOnMobile配置默认值分别为{{true}}与{{false}}即默认桌面端显示、移动端隐藏。样式Styles样式描述Highlight color通过输入十六进制颜色码或使用取色器更改选中标签的高亮颜色Tab width标签宽度可设置为auto自适应或equally split均分Visibility开关控制组件可见性可通过fx编程配置。为{{false}}时应用部署后组件不可见默认{{true}}Disable默认关闭开启后锁定组件使其不可交互。可通过fx设置为{{true}}时组件被锁定默认{{false}}:::info 任何带有fx按钮的属性都可以进行编程式配置。 :::在源码层面Tabs 的样式定义比文档更丰富tabs.js 将样式分为Tabs与Container两个手风琴分组Tabs 分组headerBackground导航栏背景、divider分隔线颜色、unselectedText未选中文字颜色默认#375FCF、selectedText选中文字颜色、hoverBackground悬停背景、unselectedIcon/selectedIcon图标颜色、accent选中标签下划线强调色默认品牌色、tabWidthauto/split、transition切换动效slide滑动 /none无。Container 分组commonBackgroundColor标签内容区公共背景色、border边框、borderRadius圆角默认 6、boxShadow阴影、paddingdefault/none。其中tabWidth: split时每个标签按可见标签数均分宽度计算公式为100 / visibleCountTabs.jsxtransition: slide时标签内容区采用 300ms 的 transform/opacity 过渡动画Tabs.jsx。实战建议组合使用事件与 CSA一个典型的联动场景是在 Tabs 的On tab switch事件中运行一个查询查询条件引用{{components.tabs1.currentTab}}从而让不同标签页展示不同数据集同时通过 RunJS 调用await components.tabs1.setTab(1)在表单提交成功后自动跳转到结果标签页。这种事件驱动 编程控制的组合方式可以覆盖绝大多数多视图内部工具页面的交互需求。【免费下载链接】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），仅供参考