ToolJet 自定义样式Custom Styles实战指南用工作区级 CSS 统一所有应用的组件外观【免费下载链接】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 的自定义样式Custom Styles功能允许你在工作区Workspace级别注入自己的 CSS覆盖组件的默认样式从而让团队创建的所有应用共享一套统一、可品牌的视觉主题。本文将先带你从 Workspace Settings 中的 Custom Styles 页面完成全局与单组件两级样式定制再结合 ToolJet 前端渲染器与后端存储的源码实现解释_tooljet-component类名的生成机制、样式的作用域与持久化方式帮助你从会配进阶到懂原理。功能定位一个付费特性解决跨应用主题一致性问题在 ToolJet 中每次新建应用时手动逐个调整组件颜色与字体既重复又容易产生视觉偏差。Custom Styles 的设计目标正是解决这一痛点一次编写处处生效在 Workspace Settings 中写入的 CSS 会作用于该工作区下所有应用的组件默认样式保持主题一致性通过标准化样式避免不同应用之间出现观感割裂提升视觉连贯性与用户体验减少重复劳动开发者无需为每个新应用重复配置组件样式从而提高开发效率。从官方文档标注的 Paid feature付费特性徽标可以看出该功能属于 ToolJet 的商业化能力仅对付费用户开放。工作原理类名注入 样式持久化在动手写 CSS 之前先理解两个关键机制这会让你后面的每个选择器都写得更自信。1. 画布组件自动携带两个类名在 ToolJet 前端渲染器中每个组件渲染时都会被自动挂载两个类名。源码位于 frontend/src/AppBuilder/AppCanvas/RenderWidget.jsxconst innerWidgetClassName [ canvas-component, inCanvas _tooljet-${component?.component} _tooljet-${component?.name}, isDisabledOrLoading disabled, userCssClass, ] .filter(Boolean) .join( );从中可以读出两个重要事实_tooljet-${component?.component}component字段是组件类型因此会生成类似_tooljet-Button、_tooljet-Table、_tooljet-TextInput的类名——这就是文档中全局组件类名的来源_tooljet-${component?.name}name是你在画布上给具体组件起的名称生成类似_tooljet-addIncomeButton的类名——这就是文档中单个组件类名的来源。也就是说同一个组件实例会同时拥有类型类名与实例类名你可以据此选择是改一批还是改一个。2. 样式以工作区为单位持久化在服务端自定义样式并非存储在浏览器本地而是通过 REST API 保存到服务端数据库。服务端实体定义在 server/src/entities/custom_styles.entity.ts对应custom_styles表关键字段包括字段说明idUUID 主键styles用户写入的 CSS 文本organization_id工作区 ID带唯一约束一个工作区一份样式scope作用域枚举instance实例级或workspace工作区级默认workspacecreated_at/updated_at创建与更新时间前端请求层封装在 frontend/src/_services/custom_styles.service.js对外暴露四个方法save(body)POST /custom-styles保存工作区样式get()GET /custom-styles获取工作区样式getForAppViewerEditor()GET /custom-styles/app供应用编辑器/查看器读取样式getForPublicApp(slug)GET /custom-styles/:slug供公开分享的应用读取样式。对应的路由定义在 server/src/modules/custom-styles/controller.ts。应用在加载时见 frontend/src/AppBuilder/_hooks/useAppData.js会调用这些接口拉取样式并注入页面因此编辑器、查看器与公开分享页面都能保持一致外观。另外值得一提的是Renderer 中还有一处hasCustomStyling的许可证门控frontend/src/AppBuilder/AppCanvas/RenderWidget.jsx它与cssClass属性相关——即组件级自定义 CSS 类同样受付费能力控制从侧面印证了 Custom Styles 整体是许可证License控制的功能。第一步进入 Custom Styles 页面操作路径非常直接登录 ToolJet 并进入仪表盘点击侧边栏或右上角的Workspace Settings在设置页中找到并进入Custom Styles页面。在该页面中你会看到一个 CSS 编辑区域后续所有全局与单组件样式都写在这里并保存生效。全局定制让一类组件统一换肤规则一使用组件类型类名_tooljet-component要修改某类组件的默认颜色直接使用它的类型类名即可格式为_tooljet-component。例如 Button 组件的类型类名就是_tooljet-Button。规则二用浏览器检查器定位子类与 HTML 标签类型类名通常挂在组件最外层容器上而具体要修改的属性如按钮文字颜色、输入框标签字号往往藏在组件的子类或内部 HTML 标签里。此时需要借助浏览器开发者工具Inspector右键目标元素 → 检查在 DOM 树中逐层展开找到目标属性的对应子类或 HTML 标签。实战示例一修改 Button 背景色找到 Button 组件内部的button标签后在 Custom Styles 区域写入._tooljet-Button button { background-color: #152A65 !important; }保存后画布上所有 Button 组件的背景色都会变为深蓝色#152A65。实战示例二修改 Table 组件 Filter 按钮背景色Table 组件的 Filter 按钮位于表头区域对应子类为.table-card-header其内部同样是button标签._tooljet-Table .table-card-header button { background-color: #152A65 !important; }这条规则只作用于 Table 表头中的 Filter 按钮不会影响页面上的其他普通按钮。实战示例三修改 Text Input 与 Number Input 的标签样式输入类组件的标签渲染为p标签因此通过._tooljet-TextInput p与._tooljet-NumberInput p即可同时调整标签的颜色、字号与字重._tooljet-TextInput p { color: #152A65 !important; font-size: 16px !important; font-weight: bold !important; } ._tooljet-NumberInput p { color: #152A65 !important; font-size: 16px !important; font-weight: bold !important; }这样所有文本输入框与数字输入框的标签都会呈现统一的加粗深蓝样式。单组件定制只改某一个组件当你不希望影响整类组件、只想单独美化画布上的某一个组件时使用该组件的实例类名格式为_tooljet-component_name其中component_name是在应用中为组件设置的名称。例如在画布上把一个 Button 命名为addIncomeButton它的实例类名就是_tooljet-addIncomeButton。对应的样式如下背景色会变为蓝色._tooljet-addIncomeButton button { background-color: blue !important; }可以看到与全局示例的结构完全一致只是把类型类名换成了实例类名。进阶建议与注意事项!important的使用组件默认样式通常来自组件自身的 SCSS优先级不低官方示例中统一使用!important确保覆盖生效。建议在自定义样式中保持同样的写法并在全局维护一份统一的品牌色/字体变量避免散落硬编码。选择器粒度选择全局样式写在_tooljet-component下会作用于工作区所有应用中的所有同类组件适合品牌主题单组件样式写在_tooljet-component_name下适合报表、看板等特殊页面的局部强调。二者可同时使用实例类名写法更具体可以覆盖更粗粒度的全局规则。作用域与团队协作样式保存在custom_styles表中并与工作区一一对应organization_id唯一意味着同一个团队的所有成员打开应用时都会看到相同的自定义外观scope字段还支持instance级作用域可在需要时覆盖整个实例的默认外观。排查技巧如果某条规则没有生效先用浏览器检查器确认目标组件的最外层类名是否确实以_tooljet-开头、子元素选择器是否命中并检查 Custom Styles 页面是否已保存成功保存对应POST /custom-styles请求。总结Custom Styles 让 ToolJet 用户摆脱逐组件手改样式的重复劳动全局定制解决品牌一致性单组件定制解决局部差异化。其底层机制清晰可见——前端渲染器在 RenderWidget.jsx 中为每个组件自动注入_tooljet-类型与_tooljet-名称两类选择器后端通过 custom_styles.entity.ts 与 custom_styles.service.js 完成样式的工作区级持久化与按需分发。掌握这套类名体系你就能用标准 CSS 高效地打造出观感统一、品牌鲜明、可规模复用的 ToolJet 应用集群。【免费下载链接】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），仅供参考