ToolJet Spinner 组件完全指南：配置、样式与源码实现解析

ToolJet Spinner 组件完全指南配置、样式与源码实现解析【免费下载链接】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/ToolJetSpinner加载指示器是 ToolJet 应用构建器中用于反馈操作正在进行中的基础视觉组件适合在查询执行、数据加载或异步任务等待期间向用户提供明确的状态提示。本文以 docs/docs/widgets/spinner.md 为骨架结合 frontend/src/AppBuilder/WidgetManager/widgets/spinner.js 与 frontend/src/AppBuilder/Widgets/Spinner.jsx 的源码实现系统讲解 Spinner 的添加方式、通用属性、布局控制、样式定制以及它在 ToolJet 组件体系中的注册与渲染原理帮助你准确掌握该组件的全部配置能力。Spinner 组件概述Spinner 组件的核心作用是通过等待状态变化来提供动作正在进行的视觉指示。在内部工具、数据看板或业务应用中它通常被放置在与异步操作相关的区域——例如查询面板执行查询、列表加载数据或文件上传期间——以替代静态内容避免用户误以为界面无响应。在 ToolJet 组件体系中Spinner 是一个纯展示型、无交互逻辑的轻量组件这一点从源码配置中可以得到印证spinner.js 中properties: {}与events: {}均为空对象说明它没有专属业务属性和事件处理exposedVariables: {}为空说明它不对外暴露任何可供表达式引用的变量组件描述为Indicate loading state指示加载状态默认画布尺寸为宽 4、高 30源码第 6-9 行。因此Spinner 的配置焦点集中在布局与样式两个维度这也是本文接下来展开的核心内容。在画布中添加 Spinner在 App Builder 中Spinner 与其他组件一样位于右侧边栏的Components Library组件库中。你可以通过以下步骤将其添加到画布打开 app-builder/overview.md 所述的编辑器界面在右侧组件库中搜索 Spinner将 Spinner 拖拽至画布的目标位置点击组件顶部的⚙️ 组件名手柄在右侧打开 Properties Panel属性面板进行配置。属性面板将所选组件的可用设置按General、Layout、Styles等区块组织详见 app-builder/right-sidebar.md。组件专属动作CSA与 ToolJet 中 Button、Table 等具备丰富交互能力的组件不同Spinner目前没有实现任何 Component-Specific Actions组件专属动作CSA。这意味着你无法通过事件处理器Event Handlers调用诸如setVisibility、setColor之类的组件级动作来编程控制 Spinner。如果你需要在运行时动态改变 Spinner 的显示或外观唯一途径是使用下文提到的fx动态值功能将属性值绑定为 JavaScript 表达式如{{true}}、{{false}}。暴露变量Exposed VariablesSpinner 同样不暴露任何变量。在 ToolJet 中暴露变量通常用于在表达式中引用组件状态例如输入框的value而 Spinner 是纯展示组件没有可供外部读取的运行态数据因此exposedVariables为空源码第 46 行。在编写表达式时无需也无法引用components.spinner1.*之类的变量。GeneralTooltip 悬浮提示在属性面板的General通用折叠区块下你可以为 Spinner 配置Tooltip输入框接受字符串格式的值配置完成后当用户将鼠标指针悬停到该组件上时会显示这段字符串作为提示文本。Tooltip 用于为组件补充额外说明信息例如正在同步数据请稍候。从源码层面看Tooltip 是组件配置中通用的字符串属性——在 textinput.js 等组件配置中可以看到tooltip属性的占位符文案为Enter tooltip textSpinner 的 Tooltip 遵循同一套属性面板渲染机制输入后以字符串形式存储并在悬停时展示。Layout响应式布局控制Layout 区块提供两个开关控制 Spinner 在不同设备视口下的显示行为布局属性说明期望值Show on desktop开关是否在桌面视图中显示该组件可通过点击fx以编程方式设置值{{true}}或{{false}}Show on mobile开关是否在移动视图中显示该组件可通过点击fx以编程方式设置值{{true}}或{{false}}在源码配置中这两个开关的默认值分别为{{true}}和{{false}}spinner.js 第 48-52 行即默认在桌面端显示、移动端不显示。这意味着如果你的应用需要面向移动端用户展示加载状态需要手动打开 Show on mobile。Styles样式定制Styles 区块是 Spinner 外观定制的核心共包含三个属性样式属性说明Visibility控制组件可见性。通过开关切换或点击fx以编程方式设置值。若为{{false}}应用部署后组件将不可见。默认值为{{true}}Color修改 Spinner 的颜色。可输入Hex 颜色代码或使用颜色选择器color-picker挑选颜色Size修改 Spinner 的尺寸。通过下拉框选择提供small和large两种规格各样式的源码级默认值对照 spinner.js 的styles配置可以确认每个样式的类型与默认值样式键控件类型默认值visibilitytoggle开关true校验类型为 booleancolourcolorSwatches取色器var(--cc-primary-brand)即跟随主题的主品牌色 CSS 变量sizeselect下拉框sm可选值为smsmall与lglarge其中有两个值得注意的细节默认颜色跟随主题Spinner 的默认颜色并非写死的某个 Hex 值而是引用了--cc-primary-brand这个 CSS 变量因此它会自动适配当前应用的品牌主题色除非你通过 Color 属性显式覆盖尺寸映射属性面板中的 small / large 在内部被映射为 Bootstrap 的sm/lg尺寸类。源码实现Spinner 的渲染原理理解了配置项之后我们深入源码看一下 Spinner 在运行时是如何渲染的。渲染组件定义在 frontend/src/AppBuilder/Widgets/Spinner.jsxexport const Spinner ({ styles, height, dataCy }) { const { colour, size, visibility, boxShadow } styles; const baseStyle { height, display: visibility ? : none, boxShadow, }; return ( div classNamespinner-container style{baseStyle} contenteditable="false">【免费下载链接】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），仅供参考