ToolJet Timer 组件完全指南从属性配置到源码级运行原理【免费下载链接】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/ToolJetTimer计时器是 ToolJet 应用构建器中用于正向/反向计时的组件可完成倒计时、耗时统计、事件计时等场景。本文将基于 ToolJet 官方文档结合仓库源码与测试用例完整讲解 Timer 组件的属性、事件、暴露变量、通用配置与样式体系并深入剖析其setInterval计时内核与状态机实现帮助你既能在画布上熟练使用该组件也能理解其底层运作机制。Timer 组件是什么Timer 组件允许用户通过向上Count Up和向下Count Down两种方式计时适用于设置倒计时、统计耗时或为事件计时等任务。在 ToolJet 应用构建器的组件面板中Timer 位于Presentation呈现分组下与 Text、Tags、CircularProgressBar、Timeline、Statistics 等组件并列分组定义可参见 sectionConfig.js。从组件注册信息看Timer 在 Widget Manager 中的定位为 Countdown or stopwatch倒计时或秒表默认尺寸为宽 11、高 128见 timer.js。注意Timer 组件属于传统legacy组件体系。在 componentTypes.js 的NEW_REVAMPED_COMPONENTS列表中并不包含 Timer因此它走的是legacyUniversalProps通用属性合并路径具体可见 componentTypes.js。Properties属性Timer 组件提供两个核心属性官方文档与组件配置一一对应属性说明Default value默认值指定计时器的初始值格式为HH.MM.SS.MS即时.分.秒.毫秒。Timer type计时器类型指定是向上计数还是向下计数。可从下拉框选择Count Up或Count Down也可以点击fx通过编程方式动态设置为countUp或countDown。源码中的属性定义在 timer.js 中这两个属性的底层定义如下value类型为code显示名 Default value校验 schema 为字符串默认值为00:00:00:000type类型为select下拉选择选项为{ name: Count up, value: countUp }与{ name: Count down, value: countDown }默认值为countUp。值得注意的是配置中针对不同计时类型提供了差异化默认值见 timer.jscountUp类型默认初始值为00:00:00:000从零开始计时countDown类型默认初始值为00:00:10:000从 10 秒开始倒计时。默认值的解析规则从 Timer.jsx 的源码可以看出默认值字符串通过properties.value.split(:)按冒号切分为[HH, MM, SS, MS]四段随后由getTimeObj见 Timer.jsx完成解析与合法性校验hourisNaN(HH)时为 0否则parseInt(HH, 10)minute必须满足MM 59否则为 0second必须满足SS 59否则为 0mSecond必须满足MS 999否则为 0。也就是说分钟、秒、毫秒字段如果超出合理范围会被自动归零这保证了非法输入不会破坏计时逻辑。Events事件Timer 组件支持 5 个事件官方文档定义如下事件说明On start每当用户点击 Start开始按钮时触发。On resume每当用户点击 Resume继续按钮时触发。On pause每当用户点击 Pause暂停按钮时触发。On count down finish每当倒计时归零时触发。On reset每当用户点击 Reset重置按钮时触发。在 timer.js 的配置中这五个事件分别对应onStart、onResume、onPause、onCountDownFinish、onReset。事件触发的源码验证On start / On resumeonStart(isResume)函数在启动计时器后调用fireEvent(isResume ? onResume : onStart)见 Timer.jsxOn pauseonPause清除计时器后调用fireEvent(onPause)见 Timer.jsxOn resetonReset恢复默认值后调用fireEvent(onReset)见 Timer.jsxOn count down finish在useEffect中监测时间状态当倒计时四个字段全部归零时清除计时器、恢复初始状态并触发fireEvent(onCountDownFinish)见 Timer.jsx。事件触发后可以连接到 ToolJet 的Actions动作体系例如执行查询、切换组件状态、显示告警等。关于 Action 的完整用法请参考仓库文档 actions 目录 下的各篇说明官方文档中亦有对应指引见 timer.md 中对 Action Reference 的提示。Component Specific Actions (CSA)Timer 组件当前没有实现任何 CSA组件专属动作即无法像 Button、TextInput 等组件那样通过components.timer1.action()的语法从外部程序化控制组件。官方文档明确说明There are currently no CSA implemented to regulate or control the component。从源码看Timer 的对外状态控制仅通过暴露变量value实现交互控制仍依赖用户点击画布上的 Start / Pause / Resume / Reset 按钮。如果你的业务需要程序化启停计时器可以结合Run JS动作与事件链、或者通过其他组件联动触发相应交互来间接实现。Exposed Variables暴露变量Timer 暴露一个名为value的变量用于在运行时动态读取当前计时值变量说明访问方式value保存计时器的当前值包含hour、minute、second、mSecond四个键。通过 JS 动态访问例如{{components.timer1.value.second}}在源码中暴露变量定义于 timer.js初始为空字符串组件挂载时通过setExposedVariable(value, {})建立暴露通道见 Timer.jsx并在每次状态变更开始、暂停、继续、重置时同步更新开始/继续时setExposedVariable(value, time)见 Timer.jsx暂停时setExposedVariable(value, time)见 Timer.jsx重置时setExposedVariable(value, getTimeObj(getDefaultValue))见 Timer.jsx。实际使用示例value对象的结构固定为{ hour, minute, second, mSecond }你可以在任何支持 JS 表达式的位置使用它例如在 Text 组件中显示当前秒数{{components.timer1.value.second}}在按钮的禁用条件中判断是否到达指定秒数{{components.timer1.value.second 30}}拼接完整时间字符串{{components.timer1.value.hour}}h {{components.timer1.value.minute}}m {{components.timer1.value.second}}s提示毫秒字段的 key 为mSecond注意大小写value对象中不存在单独的毫秒别名键。General通用设置Tooltip提示信息Tooltip 常用于当用户将鼠标悬停在组件上时展示额外的说明信息。在General折叠面板下你可以输入字符串类型的提示文本设置后鼠标悬停在 Timer 组件上即会显示该文本。Tooltip 属于组件的通用属性。从源码看传统组件通过legacyUniversalProps.general注入tooltip字段类型为code字符串校验定义见 componentTypes.js随后通过combineProperties与组件自身的 general 配置合并见 componentTypes.js。Devices设备可见性Timer 组件支持按设备类型控制显示设备说明期望值Show on desktop在桌面视图中显示该组件。可通过开关按钮设置或点击fx输入逻辑表达式动态配置。Show on mobile在移动视图中显示该组件。可通过开关按钮设置或点击fx输入逻辑表达式动态配置。源码中的默认配置为桌面端显示{{true}}、移动端隐藏{{false}}见 timer.js 中的others定义。Styles样式Timer 组件提供以下样式配置项属性说明配置方式Visibility可见性控制组件的可见性。开关按钮切换或点击fx输入逻辑表达式动态配置。Disable禁用启用或禁用组件。开关按钮切换或点击fx输入逻辑表达式动态配置。Box shadow盒阴影设置组件的盒阴影属性。选择阴影颜色并调整相关属性或通过fx编程设置。源码中visibility与disabledState均定义为布尔类型的 toggle默认值分别为true与false见 timer.jsboxShadow则来自传统组件的generalStyles默认值为0px 0px 0px 0px #00000040见 componentTypes.js。官方文档特别提示任何带fx按钮的属性字段都可以进行编程式配置programmatically configured这意味着你可以用表达式、组件引用或查询结果来动态驱动这些样式。源码级原理Timer 的计时内核与状态机理解 Timer 组件的底层实现有助于你预测它在复杂场景下的行为。核心渲染逻辑位于 Timer.jsx关键机制如下1. 基于 setInterval 的 15ms 计时步长Timer 使用setInterval以15 毫秒为步长驱动时间变化见 Timer.jsxCount Up每 15ms 毫秒数15超过 1000ms 进位到秒秒满 60 进位到分分满 60 进位到时Count Down每 15ms 毫秒数-15小于 0 时向秒借位1000依次向下借位当小时也小于 0 时强制归零(MS0, SS0, MM0, HH0)。这种以毫秒为最小单位、逐级进位/借位的实现方式使得显示值始终是规整的HH:MM:SS:MS格式而不是一个浮点秒数。2. 四态状态机组件内部通过state维护一个四态状态机见 Timer.jsxinitial初始显示Start按钮running运行中显示Pause按钮paused已暂停显示Resume按钮Reset按钮在任意状态下都常驻显示。按钮渲染逻辑见 Timer.jsx同时有两个细节值得注意倒计时归零后Start 按钮会被自动禁用isStartDisabled判断见 Timer.jsx防止归零后继续执行无效倒计时当disabledState禁用样式开启时所有按钮都会追加disabledclass。3. 属性变更自动重置组件监听properties.type与默认值的变化见 Timer.jsx一旦你在编辑器中修改了计时类型或默认值计时器会自动清除当前计时器、恢复初始状态并重新加载新默认值。因此在运行时动态切换countUp/countDown会导致计时中断并重置设计交互时需留意。4. 组件卸载清理组件通过useEffect的 cleanup 函数在卸载时清除intervalId见 Timer.jsx避免定时器泄漏导致的资源占用。5. 样式实现Timer 的显示样式定义在主题样式表 theme.scss 中.timer-wrapper提供 10px 内边距.counter-container以font-size: 3em居中展示大号时间数字便于在仪表盘等场景中清晰读数。测试验证Cypress 端到端测试中已覆盖 Timer 组件的基础渲染验证在 componentsBasicHappypath.skip.js 中通过verifyComponentWithOutLabel(Timer, timer1, timer2, data.appName)校验组件拖入画布后的默认命名规则timer1、timer2……与基础可用性可作为你在自动化测试中参考的断言模式。常见使用场景小结结合上述能力Timer 组件在 ToolJet 应用中的典型用法包括考试/答题倒计时Timer type 设为countDown配合On count down finish事件在时间耗尽时自动提交表单或执行查询任务耗时统计Timer type 设为countUp通过暴露变量value在页面其他位置实时展示已用时间流程步骤计时利用On start/On pause/On resume/On reset事件组合记录每个环节的用时并写入数据库。小结本文完整覆盖了 Timer 组件的属性默认值、计时类型、五个交互事件、暴露变量value的四个键、Tooltip 与设备可见性、三类样式配置并深入源码剖析了其 15ms 步长的setInterval计时内核、四态状态机、属性变更重置与卸载清理机制。无论你是要快速在画布上搭建一个倒计时场景还是希望深入理解 ToolJet 传统组件的实现范式本文均可作为直接参考。相关的完整配置与实现文件为 timer.md、timer.js配置 与 Timer.jsx实现。【免费下载链接】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 Timer 组件完全指南：从属性配置到源码级运行原理
ToolJet Timer 组件完全指南从属性配置到源码级运行原理【免费下载链接】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/ToolJetTimer计时器是 ToolJet 应用构建器中用于正向/反向计时的组件可完成倒计时、耗时统计、事件计时等场景。本文将基于 ToolJet 官方文档结合仓库源码与测试用例完整讲解 Timer 组件的属性、事件、暴露变量、通用配置与样式体系并深入剖析其setInterval计时内核与状态机实现帮助你既能在画布上熟练使用该组件也能理解其底层运作机制。Timer 组件是什么Timer 组件允许用户通过向上Count Up和向下Count Down两种方式计时适用于设置倒计时、统计耗时或为事件计时等任务。在 ToolJet 应用构建器的组件面板中Timer 位于Presentation呈现分组下与 Text、Tags、CircularProgressBar、Timeline、Statistics 等组件并列分组定义可参见 sectionConfig.js。从组件注册信息看Timer 在 Widget Manager 中的定位为 Countdown or stopwatch倒计时或秒表默认尺寸为宽 11、高 128见 timer.js。注意Timer 组件属于传统legacy组件体系。在 componentTypes.js 的NEW_REVAMPED_COMPONENTS列表中并不包含 Timer因此它走的是legacyUniversalProps通用属性合并路径具体可见 componentTypes.js。Properties属性Timer 组件提供两个核心属性官方文档与组件配置一一对应属性说明Default value默认值指定计时器的初始值格式为HH.MM.SS.MS即时.分.秒.毫秒。Timer type计时器类型指定是向上计数还是向下计数。可从下拉框选择Count Up或Count Down也可以点击fx通过编程方式动态设置为countUp或countDown。源码中的属性定义在 timer.js 中这两个属性的底层定义如下value类型为code显示名 Default value校验 schema 为字符串默认值为00:00:00:000type类型为select下拉选择选项为{ name: Count up, value: countUp }与{ name: Count down, value: countDown }默认值为countUp。值得注意的是配置中针对不同计时类型提供了差异化默认值见 timer.jscountUp类型默认初始值为00:00:00:000从零开始计时countDown类型默认初始值为00:00:10:000从 10 秒开始倒计时。默认值的解析规则从 Timer.jsx 的源码可以看出默认值字符串通过properties.value.split(:)按冒号切分为[HH, MM, SS, MS]四段随后由getTimeObj见 Timer.jsx完成解析与合法性校验hourisNaN(HH)时为 0否则parseInt(HH, 10)minute必须满足MM 59否则为 0second必须满足SS 59否则为 0mSecond必须满足MS 999否则为 0。也就是说分钟、秒、毫秒字段如果超出合理范围会被自动归零这保证了非法输入不会破坏计时逻辑。Events事件Timer 组件支持 5 个事件官方文档定义如下事件说明On start每当用户点击 Start开始按钮时触发。On resume每当用户点击 Resume继续按钮时触发。On pause每当用户点击 Pause暂停按钮时触发。On count down finish每当倒计时归零时触发。On reset每当用户点击 Reset重置按钮时触发。在 timer.js 的配置中这五个事件分别对应onStart、onResume、onPause、onCountDownFinish、onReset。事件触发的源码验证On start / On resumeonStart(isResume)函数在启动计时器后调用fireEvent(isResume ? onResume : onStart)见 Timer.jsxOn pauseonPause清除计时器后调用fireEvent(onPause)见 Timer.jsxOn resetonReset恢复默认值后调用fireEvent(onReset)见 Timer.jsxOn count down finish在useEffect中监测时间状态当倒计时四个字段全部归零时清除计时器、恢复初始状态并触发fireEvent(onCountDownFinish)见 Timer.jsx。事件触发后可以连接到 ToolJet 的Actions动作体系例如执行查询、切换组件状态、显示告警等。关于 Action 的完整用法请参考仓库文档 actions 目录 下的各篇说明官方文档中亦有对应指引见 timer.md 中对 Action Reference 的提示。Component Specific Actions (CSA)Timer 组件当前没有实现任何 CSA组件专属动作即无法像 Button、TextInput 等组件那样通过components.timer1.action()的语法从外部程序化控制组件。官方文档明确说明There are currently no CSA implemented to regulate or control the component。从源码看Timer 的对外状态控制仅通过暴露变量value实现交互控制仍依赖用户点击画布上的 Start / Pause / Resume / Reset 按钮。如果你的业务需要程序化启停计时器可以结合Run JS动作与事件链、或者通过其他组件联动触发相应交互来间接实现。Exposed Variables暴露变量Timer 暴露一个名为value的变量用于在运行时动态读取当前计时值变量说明访问方式value保存计时器的当前值包含hour、minute、second、mSecond四个键。通过 JS 动态访问例如{{components.timer1.value.second}}在源码中暴露变量定义于 timer.js初始为空字符串组件挂载时通过setExposedVariable(value, {})建立暴露通道见 Timer.jsx并在每次状态变更开始、暂停、继续、重置时同步更新开始/继续时setExposedVariable(value, time)见 Timer.jsx暂停时setExposedVariable(value, time)见 Timer.jsx重置时setExposedVariable(value, getTimeObj(getDefaultValue))见 Timer.jsx。实际使用示例value对象的结构固定为{ hour, minute, second, mSecond }你可以在任何支持 JS 表达式的位置使用它例如在 Text 组件中显示当前秒数{{components.timer1.value.second}}在按钮的禁用条件中判断是否到达指定秒数{{components.timer1.value.second 30}}拼接完整时间字符串{{components.timer1.value.hour}}h {{components.timer1.value.minute}}m {{components.timer1.value.second}}s提示毫秒字段的 key 为mSecond注意大小写value对象中不存在单独的毫秒别名键。General通用设置Tooltip提示信息Tooltip 常用于当用户将鼠标悬停在组件上时展示额外的说明信息。在General折叠面板下你可以输入字符串类型的提示文本设置后鼠标悬停在 Timer 组件上即会显示该文本。Tooltip 属于组件的通用属性。从源码看传统组件通过legacyUniversalProps.general注入tooltip字段类型为code字符串校验定义见 componentTypes.js随后通过combineProperties与组件自身的 general 配置合并见 componentTypes.js。Devices设备可见性Timer 组件支持按设备类型控制显示设备说明期望值Show on desktop在桌面视图中显示该组件。可通过开关按钮设置或点击fx输入逻辑表达式动态配置。Show on mobile在移动视图中显示该组件。可通过开关按钮设置或点击fx输入逻辑表达式动态配置。源码中的默认配置为桌面端显示{{true}}、移动端隐藏{{false}}见 timer.js 中的others定义。Styles样式Timer 组件提供以下样式配置项属性说明配置方式Visibility可见性控制组件的可见性。开关按钮切换或点击fx输入逻辑表达式动态配置。Disable禁用启用或禁用组件。开关按钮切换或点击fx输入逻辑表达式动态配置。Box shadow盒阴影设置组件的盒阴影属性。选择阴影颜色并调整相关属性或通过fx编程设置。源码中visibility与disabledState均定义为布尔类型的 toggle默认值分别为true与false见 timer.jsboxShadow则来自传统组件的generalStyles默认值为0px 0px 0px 0px #00000040见 componentTypes.js。官方文档特别提示任何带fx按钮的属性字段都可以进行编程式配置programmatically configured这意味着你可以用表达式、组件引用或查询结果来动态驱动这些样式。源码级原理Timer 的计时内核与状态机理解 Timer 组件的底层实现有助于你预测它在复杂场景下的行为。核心渲染逻辑位于 Timer.jsx关键机制如下1. 基于 setInterval 的 15ms 计时步长Timer 使用setInterval以15 毫秒为步长驱动时间变化见 Timer.jsxCount Up每 15ms 毫秒数15超过 1000ms 进位到秒秒满 60 进位到分分满 60 进位到时Count Down每 15ms 毫秒数-15小于 0 时向秒借位1000依次向下借位当小时也小于 0 时强制归零(MS0, SS0, MM0, HH0)。这种以毫秒为最小单位、逐级进位/借位的实现方式使得显示值始终是规整的HH:MM:SS:MS格式而不是一个浮点秒数。2. 四态状态机组件内部通过state维护一个四态状态机见 Timer.jsxinitial初始显示Start按钮running运行中显示Pause按钮paused已暂停显示Resume按钮Reset按钮在任意状态下都常驻显示。按钮渲染逻辑见 Timer.jsx同时有两个细节值得注意倒计时归零后Start 按钮会被自动禁用isStartDisabled判断见 Timer.jsx防止归零后继续执行无效倒计时当disabledState禁用样式开启时所有按钮都会追加disabledclass。3. 属性变更自动重置组件监听properties.type与默认值的变化见 Timer.jsx一旦你在编辑器中修改了计时类型或默认值计时器会自动清除当前计时器、恢复初始状态并重新加载新默认值。因此在运行时动态切换countUp/countDown会导致计时中断并重置设计交互时需留意。4. 组件卸载清理组件通过useEffect的 cleanup 函数在卸载时清除intervalId见 Timer.jsx避免定时器泄漏导致的资源占用。5. 样式实现Timer 的显示样式定义在主题样式表 theme.scss 中.timer-wrapper提供 10px 内边距.counter-container以font-size: 3em居中展示大号时间数字便于在仪表盘等场景中清晰读数。测试验证Cypress 端到端测试中已覆盖 Timer 组件的基础渲染验证在 componentsBasicHappypath.skip.js 中通过verifyComponentWithOutLabel(Timer, timer1, timer2, data.appName)校验组件拖入画布后的默认命名规则timer1、timer2……与基础可用性可作为你在自动化测试中参考的断言模式。常见使用场景小结结合上述能力Timer 组件在 ToolJet 应用中的典型用法包括考试/答题倒计时Timer type 设为countDown配合On count down finish事件在时间耗尽时自动提交表单或执行查询任务耗时统计Timer type 设为countUp通过暴露变量value在页面其他位置实时展示已用时间流程步骤计时利用On start/On pause/On resume/On reset事件组合记录每个环节的用时并写入数据库。小结本文完整覆盖了 Timer 组件的属性默认值、计时类型、五个交互事件、暴露变量value的四个键、Tooltip 与设备可见性、三类样式配置并深入源码剖析了其 15ms 步长的setInterval计时内核、四态状态机、属性变更重置与卸载清理机制。无论你是要快速在画布上搭建一个倒计时场景还是希望深入理解 ToolJet 传统组件的实现范式本文均可作为直接参考。相关的完整配置与实现文件为 timer.md、timer.js配置 与 Timer.jsx实现。【免费下载链接】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），仅供参考
