ToolJet Icon 组件完全指南:属性、事件、组件级动作与样式详解
ToolJet Icon 组件完全指南:属性、事件、组件级动作与样式详解
导读
Icon(图标)是 ToolJet 可视化应用构建器中一个轻量但高频使用的基础组件,用于在应用界面中呈现来自内置图标库的图形符号,并支持悬停(on hover)与点击(on click)两类交互事件。本文基于 ToolJet 2.50.0-LTS 文档与前端源码,完整讲解 Icon 组件的属性配置、事件绑定、组件级动作(CSA)、样式系统与设备可见性控制,帮助你在内部工具、仪表盘等应用中使用图标快速构建交互入口,并通过 RunJS 查询与事件处理器实现动态控制。
组件概述
ToolJet 的 Icon 组件本质上是 Tabler Icons 组件,根据属性 icon 传入的图标名称(如默认值 IconHome2)渲染对应的 SVG 图形。从 widget 定义文件 可以看到,组件名与显示名均为 Icon,默认画布尺寸为宽 5、高 48,默认图标为 IconHome2,默认颜色为 #000,对齐方式为居中。
该组件非常适合用作按钮旁的图形入口、导航指示、状态标记等场景,配合点击事件可触发任意 ToolJet 动作(如显示弹窗、运行查询、切换页面)。
Properties(属性)
| 属性 | 说明 | 期望值 |
|---|---|---|
| Icon | 用于从可用图标列表中选择一个图标 | 可以使用其中的搜索栏查找图标 |
在属性检查器的 Icon 字段中,ToolJet 提供图形化的图标选择器(源码中对应 type: 'iconPicker')。点击后弹出图标库面板,通过内置搜索栏可按名称快速过滤图标。选中的图标名称会以字符串形式存入组件属性,默认值为 IconHome2,例如可直接写入 IconSettings、IconUser、IconBell 等 Tabler 图标标识。
从 widget 定义 可见,icon 属性的校验 schema 为字符串类型,这意味着它同样可以接收 fx 动态值,例如 {{ global.variables.dynamicIcon }} 来在运行时切换图标。
Events(事件)
Icon 组件支持两个交互事件:
| 事件 | 说明 |
|---|---|
| On hover | 光标悬停在图标上时触发 |
| On click | 点击图标时触发 |
在 组件渲染实现 中,onMouseEnter 处理器会阻止事件冒泡并触发 onHover 事件,图标的 onClick 处理器同样先 stopPropagation() 再触发 onClick 事件——这意味着事件不会意外冒泡到外层容器,多组件嵌套时可避免误触发。
与 ToolJet 中的其他组件一致,每个事件都可以绑定多个事件处理器(Handlers)。例如你可以同时让“点击图标”既运行一个查询、又显示一个通知、再切换某个变量的值。事件处理器中可使用的所有 Actions(动作)的完整清单,参见文档 Actions Reference(对应主文档目录中的 actions 分类)。
Component Specific Actions(组件级动作,CSA)
Icon 组件支持通过组件级动作(CSA)在运行时被外部逻辑控制:
| 动作 | 说明 | 调用方式 |
|---|---|---|
| setVisibility() | 设置组件的可见性 | 通过 RunJS 查询,例如 await components.icon1.setVisibility(false);或通过事件处理器触发 |
| click() | 模拟点击图标 | 通过 RunJS 查询,例如 await components.icon1.click();或通过事件处理器触发 |
从 widget 定义 可以看到,Icon 组件实际注册了 4 个动作:click、setVisibility(参数 value,默认 {{true}})、setLoading、setDisable。也就是说,除了文档表格中的两个动作外,你还可以在 RunJS 中调用:
// 设置加载状态
await components.icon1.setLoading(true);
// 禁用图标(不再响应交互)
await components.icon1.setDisable(true);
这些动作与 组件渲染源码 中暴露的内部方法一一对应:click() 会触发 fireEvent('onClick'),setVisibility(value) 会同步更新 isVisible 暴露变量与本地可见状态,setLoading 与 setDisable 同理。动作都返回 Promise,因此在 RunJS 中记得使用 await 确保顺序执行。
Exposed Variables(暴露变量)
文档说明 Icon 组件当前没有对外暴露变量。不过从 渲染实现 看,组件内部其实维护了三个运行时状态:isVisible、isLoading、isDisabled,并通过 setExposedVariables 同步给属性检查器。在编写 RunJS 或表达式时,仍可通过 components.icon1.isVisible 等路径读取当前状态(如用 {{ components.icon1.isVisible }} 作为其他组件属性的动态值),实现跨组件的联动判断。
General(通用设置)
Tooltip(提示文本): 在通用设置中为组件设置提示文本,当用户将鼠标指针移动到组件上时显示该信息,用于补充说明图标的含义。在 widget 定义 中,Tooltip 支持三种格式:plainText(纯文本,默认)、markdown(Markdown 渲染)与 html(HTML 渲染),默认文本为 Tooltip text,可通过 fx 动态绑定。
Devices(设备可见性)
| 属性 | 说明 | 期望值 |
|---|---|---|
| Show on desktop | 在桌面视图中显示该组件 | 可通过开关按钮设置,或点击 fx 输入逻辑表达式动态配置 |
| Show on mobile | 在移动视图中显示该组件 | 可通过开关按钮设置,或点击 fx 输入逻辑表达式动态配置 |
这两个开关控制组件在不同设备视口下的显隐。默认定义中 showOnDesktop 为 {{true}}、showOnMobile 为 {{false}}(见 widget 定义),即默认桌面显示、移动端隐藏。你可以按需调整,例如在移动端布局中让图标同样可见。由于该字段支持 fx,也可以写成 {{ auth.isMobile }} 之类的表达式按运行环境动态决定。
Styles(样式)
| 样式 | 说明 | 期望值 |
|---|---|---|
| Icon color | 修改 Icon 组件的颜色 | 输入十六进制颜色码,或从颜色选择器中选色 |
| Visibility | 控制组件的可见性 | 仅接受布尔值 {{true}} 或 {{false}};若为 {{false}},应用部署后组件将不可见。默认 {{true}} |
| Box shadow | 为组件添加阴影效果 | 可设置偏移量(offset)、模糊(blur)、扩散(spread)与颜色值 |
样式面板按“Icon”分组(见 widget 定义),除文档表格中的三项外,还提供以下可配置项:
- Color(图标颜色):默认
#000(纯黑)。在 渲染实现 中有一个细节:若颜色保持默认的#000,在深色模式(darkMode)下会自动渲染为#fff以保证可见性;一旦你手动指定了其他颜色,则严格按你设置的值渲染。 - Alignment(对齐方式):默认
center,可切换为左对齐或右对齐,控制图标在其容器内的水平位置。 - Padding(内边距):提供
default(默认)与none(无)两种选项。 - Box shadow(盒阴影):默认值为
0px 0px 0px 0px #00000040,可在面板中配置偏移、模糊、扩散与颜色。
关于 Visibility 样式,它与 Properties 中的可见性开关协同工作:源码中 visibility 同时出现在属性区与样式区,运行时以 {{true}}/{{false}} 布尔值驱动 d-none 类来控制 DOM 显隐(见 渲染实现),{{false}} 时组件在部署后的应用中完全隐藏。
:::info
任何带有 fx 按钮的字段都可以被 程序化配置(Programmatically Configured),即用 {{ ... }} 表达式、变量或函数返回值动态驱动,而不再局限于静态取值。
:::
进阶:动态控制 Icon 的完整示例
综合以上能力,一个典型的“动态图标按钮”组合如下:
- 图标切换:在 Icon 属性中将
Icon字段设为 fx 表达式,如{{ global.theme === 'dark' ? 'IconMoon' : 'IconSun' }}; - 点击反馈:在 Events 的 On click 上添加事件处理器,运行一个查询或切换页面;
- 运行时控制:在 RunJS 查询中调用组件级动作:
// 隐藏图标
await components.icon1.setVisibility(false);
// 模拟一次点击(会触发 On click 事件)
await components.icon1.click();
// 进入加载态
await components.icon1.setLoading(true);
- 样式联动:将
Icon color用 fx 绑定到主题变量,如{{ darkMode ? '#ffffff' : '#0f172a' }},实现明暗主题下图标颜色的自适应。
总结
ToolJet 的 Icon 组件虽然轻量,却完整具备属性配置、双交互事件、组件级动作、样式系统与设备可见性控制五层能力,是快速搭建交互式界面不可或缺的基础元件。掌握其 icon 属性(Tabler 图标库)、onClick/onHover 事件、setVisibility()/click() 等 CSA 动作以及 fx 程序化配置,即可在内部工具与仪表盘中灵活构建图标导航、状态指示与操作入口。若要进一步了解事件处理器中可用的全部动作类型,可继续查阅 ToolJet 的 Actions Reference 相关文档。