ToolJet 条件显示组件实战使用 fx 表达式与用户组Groups控制组件可见性【免费下载链接】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 低代码平台中多组用户Groups可能同时访问同一个应用而不同角色的用户应当看到不同的界面内容。本篇技术指南基于官方 How-to 文档围绕{{globals.currentUser.groups.includes(Manager)}}这一核心表达式讲解如何利用属性面板中的fx功能与用户组机制按当前登录用户所属的用户组条件化控制组件如按钮的显示与隐藏。读完本文你将掌握 Visibility 属性的 fx 用法、globals.currentUser的数据结构、组件可见性的底层渲染原理以及将整组组件包进 Container 实现区块级条件显示的高级方案。一、场景背景为什么需要按用户组条件显示组件在真实业务应用中同一个应用往往需要同时服务于不同角色的用户。例如一个员工请假审批应用Employee Leave Management普通员工可以查看请假申请列表但只有Manager经理用户组的成员才有权限看到并操作Approve Selected批准选中按钮。如果让所有用户都看到该按钮非经理用户点击后就会因权限不足而报错体验与安全性都不理想。ToolJet 的解决方案是不写后端判断逻辑而是在组件属性层直接声明可见性条件。通过在组件的Visibility属性中写入一个返回布尔值的 JavaScript 表达式ToolJet 会在每次渲染时对当前用户求值从而决定该组件是否出现在画布上。二、核心表达式globals.currentUser.groups从哪来在动手配置之前先理解globals.currentUser.groups是什么。从源码看ToolJet 前端在初始化当前状态时会把当前会话中的用户组信息注入globals.currentUser见 frontend/src/_stores/currentStateStore.jsconst userVars { email: currentUser?.email, firstName: currentUser?.first_name, lastName: currentUser?.last_name, groups: currentSession?.group_permissions ? [all_users, ...currentSession.group_permissions.map((group) group.name)] : [all_users], role: currentSession?.role?.name, ssoUserInfo: currentUser?.sso_user_info, ...(currentUser?.metadata !_.isEmpty(currentUser.metadata) ? { metadata: currentUser.metadata } : {}), };可以提炼出以下事实globals.currentUser是一个对象包含email、firstName、lastName、groups、role、ssoUserInfo、metadata等字段groups是一个字符串数组来源于当前会话currentSession的group_permissions即用户在当前工作区中所属的全部用户组名称数组始终包含默认组all_users再追加用户实际所属的组名——这意味着你可以放心使用includes(all_users)之类与默认组相关的判断用户的组信息最终来自服务端授权流程返回的group_permissions前端通过data.group_permissions.map((group) group.group)写入用户状态见 frontend/src/_helpers/authorizeWorkspace.js。因此表达式{{globals.currentUser.groups.includes(Manager)}}的含义是当前登录用户的用户组列表中是否包含名为Manager的组其求值结果是一个布尔值true或false恰好是 Visibility 属性所需的类型。三、分步实现给按钮配置基于用户组的可见性下面以示例应用中的Approve Selected按钮为例实现仅 Manager 组用户可见。假设应用界面中已经放置了需要的组件初始界面如下图所示第 1 步选中目标组件并定位 Visibility 属性在编辑器中选中Approve Selected按钮组件在右侧属性面板中找到Visibility可见性属性。从组件定义源码可以确认visibility是每个组件的标准属性之一。以按钮为例在 frontend/src/AppBuilder/WidgetManager/widgets/button.js 中定义如下visibility: { type: toggle, displayName: Visibility, validation: { schema: { type: boolean } }, section: additionalActions, },这里的关键点是validation: { schema: { type: boolean } }Visibility 属性的合法取值必须是布尔类型因此你写入的 fx 表达式必须能求出true或false。第 2 步点击 fx 按钮切换到表达式模式Visibility属性默认是一个开关toggle。点击输入框旁的fx按钮将其切换为表达式输入模式然后输入下面的代码{{globals.currentUser.groups.includes(Manager)}}第 3 步保存并验证效果保存应用后当非 Manager 组的用户访问应用时表达式求值为falseApprove Selected按钮不会渲染当Manager 组的用户访问应用时表达式求值为true按钮正常显示。四、两种用户视角的实际效果对比以下两张截图分别展示了同一应用在两类用户视角下的差异。非 Manager 用户视角界面中不出现Approve Selected按钮用户只能查看请假申请列表Manager 用户视角界面右下角出现Approve Selected按钮Manager 可以对选中的申请执行批准操作五、底层原理可见性是如何生效的条件显示并非只在配置阶段生效ToolJet 在画布渲染与运行时求值两个环节都会读取该属性。1. 运行时求值组件属性中的表达式会在运行时被解析为真实值。以渲染环节为例frontend/src/AppBuilder/AppCanvas/RenderWidget.jsx 中这样读取可见性return resolved?.properties?.visibility ?? resolved?.styles?.visibility ?? true;也就是说渲染器会优先使用解析resolved后的properties.visibility其次回退到styles.visibility两者都不存在时默认可见true。你在属性面板中配置的 fx 表达式最终会进入properties.visibility参与求值。2. 画布编辑器中的即时反馈编辑器画布同样会对每个组件调用可见性判断。在 frontend/src/AppBuilder/AppCanvas/Grid/Grid.jsx 中const isComponentVisible (id) { const component getResolvedComponent(id, null, moduleId); const componentExposedVisibility getExposedValueOfComponent(id, moduleId)?.isVisible; if (componentExposedVisibility false) return false; let visibility; if (isArray(component)) { visibility component?.[0]?.properties?.visibility ?? component?.[0]?.styles?.visibility ?? null; } else { visibility component?.properties?.visibility ?? component?.styles?.visibility ?? null; } return visibility; };从源码结构可以推断isComponentVisible会在网格重排与布局计算时被调用条件为false的组件会被判定为不可见并从当前布局中移除从而释放其所占的网格空间这正是隐藏组件不占位效果的来源。同时表达式求值基于globals.currentUser因此不同用户登录同一应用时同一组件可以呈现完全不同的显示状态这属于典型的运行时动态渲染。六、进阶用法用 Container 实现整组组件条件显示当需要按条件显示一个区块多个组件的组合时无需给每个组件单独配置表达式。推荐的做法是从组件面板中拖入一个Container容器组件将需要条件显示的所有组件按钮、输入框、表格等都放入该 Container 内部选中 Container在其Visibility属性中写入相同的 fx 表达式{{globals.currentUser.groups.includes(Manager)}}这样整个容器及其内部的所有组件会作为一个整体被显示或隐藏既避免了重复配置也让界面结构更清晰、更易维护。ToolJet 的 Container 组件同样具备visibility属性定义其渲染逻辑与普通组件一致可放心使用这一模式。七、扩展基于globals.currentUser的其他条件场景理解了数据结构后同一机制可以推广到更多角色感知的界面定制场景按角色显示使用{{globals.currentUser.role admin}}或{{globals.currentUser.role builder}}判断用户在工作区中的角色按默认组判断利用始终存在的all_users组例如{{globals.currentUser.groups.includes(all_users)}}恒为真可用作对照测试多组联合判断用||组合多个组如{{globals.currentUser.groups.includes(Manager) || globals.currentUser.groups.includes(Admin)}}实现属于任一指定组即可见取反逻辑用!取反例如让某个提示信息只对非 Manager 用户显示{{!globals.currentUser.groups.includes(Manager)}}。需要说明的适用前提是globals.currentUser中的groups来自当前工作区的用户组配置组名必须与工作区设置Workspace Settings → Groups中的组名完全一致区分大小写否则includes匹配会失败。八、小结通过本文的实践你已经掌握了 ToolJet 条件显示组件的完整链路配置入口组件属性面板 → Visibility → 点击 fx 进入表达式模式核心表达式{{globals.currentUser.groups.includes(组名)}}返回布尔值数据来源globals.currentUser.groups由会话中的group_permissions映射而来并始终包含all_users默认组见 frontend/src/_stores/currentStateStore.js生效机制属性值需为布尔类型见 frontend/src/AppBuilder/WidgetManager/widgets/button.js渲染器与画布在运行时分别通过properties.visibility判定可见性见 frontend/src/AppBuilder/AppCanvas/RenderWidget.jsx 与 frontend/src/AppBuilder/AppCanvas/Grid/Grid.jsx区块级控制将相关组件放入 Container 并对容器应用同一表达式即可一次性控制整组组件的显示状态。这套fx Groups的组合能力让权限感知的界面定制完全可以在应用构建器内声明式完成无需编写额外后端代码。【免费下载链接】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），仅供参考