ToolJet Text Input 组件完全指南：属性、事件、验证与组件级动作（CSA）详解

ToolJet Text Input 组件完全指南属性、事件、验证与组件级动作CSA详解【免费下载链接】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 2.50.0-LTS 版本文档系统讲解Text Input文本输入组件的全部配置能力包括基础属性、事件绑定、组件特定动作CSA、暴露变量、输入验证、设备可见性与样式定制。文章内容同时结合当前仓库中该组件的前端实现源码组件配置定义、组件渲染实现、输入逻辑 Hook、基础输入组件与端到端测试用例帮助开发者既能在可视化编辑器中快速上手又能理解每个配置项背后的真实实现机制。Text Input组件允许用户输入单行文本既可以作为独立组件使用也可以嵌入到 Form 表单字段中。在 ToolJet 的组件类型定义中见 componentTypes.js 对应的组件注册与 textinput.js 的配置它默认尺寸为宽 10、高 40defaultSize组件标识名为TextInput拖入画布后默认命名为textinput1测试常量中同样以textinput1作为默认组件名见 textInput.js。Properties基础属性Text Input 组件提供三个核心内容属性在右侧属性面板中均可直接配置也可以通过fx按钮切换为动态表达式组件配置中这三个属性均定义为type: code即支持动态绑定见 textinput.js属性说明期望值Label显示为字段的标签文本字符串例如Enter Your Name配置默认值为Label数据校验 schema 为字符串类型Placeholder提示用户输入内容的占位提示字符串例如John Doe配置默认值为Enter your inputDefault Value应用加载时组件持有的默认值字符串例如Default Text对应配置中的value属性默认值为空字符串从源码看value属性不仅是初始值也是整个组件的值状态来源useInputHook 中useState(properties.value ?? )用它初始化输入框内容同时通过useEffect监听properties.value的变化并同步更新输入框useInput.js、useInput.js。这意味着 Default Value 支持用{{...}}表达式绑定其他组件的值或全局变量实现组件间的数据联动。Events事件Text Input 组件支持四个事件全部在事件处理器Event Handlers中配置事件定义可在 textinput.js 中找到事件触发时机On change用户在文本输入框中输入任何内容时触发On enter pressed用户输入文本后在键盘上按下回车键时触发On focus用户点击输入框内部获得焦点时触发On blur用户点击输入框外部失去焦点时触发这四个事件在useInputHook 中分别对应handleChange、handleKeyUp、handleFocus、handleBlur四个处理器并通过fireEvent向上抛出useInput.jshandleChange更新组件内部值并立即触发onChange事件实现输入即触发handleKeyUp仅在按下Enter键时同步值并触发onEnterPressedhandleFocus通过setTimeout(..., 0)延迟一帧触发onFocus确保焦点状态先完成渲染handleBlur先设置校验错误展示状态为 true失焦即校验、再触发onBlur。提示关于所有Actions如 Show alert、Run query 等的详细用法可查阅仓库中的 Action Reference 文档原文档指向/docs/category/actions-reference在当前 2.50.0-LTS 版本文档中对应 actions 目录。Component Specific Actions组件特定动作CSAText Input 组件暴露了一组可用RunJS 查询或事件处理器调用的组件特定动作。CSA 动作定义位于 textinput.js其底层实现在 useInput.js 中通过setExposedVariables注入动作说明调用方式setText()设置输入框的值RunJS 查询例如await components.textinput1.setText(this is input text)或通过事件触发clear()清空输入框中的已输入文本RunJS 查询例如await components.textinput1.clear()或通过事件触发setFocus()将光标焦点设置到输入框RunJS 查询例如await components.textinput1.setFocus()或通过事件触发setBlur()将光标焦点从输入框移除RunJS 查询例如await components.textinput1.setBlur()或通过事件触发setVisibility()设置组件的可见性RunJS 查询例如await components.textinput1.setVisibility(false)或通过事件触发setLoading()设置组件的加载状态RunJS 查询例如await components.textinput1.setLoading(true)或通过事件触发setDisable()禁用组件RunJS 查询例如await components.textinput1.setDisable(true)或通过事件触发源码级行为细节useInput.jssetText除更新值外还会调用setShowValidationError(true)立即展示校验结果并触发一次onChange事件clear清空值并触发onChangesetFocus/setBlur直接操作底层 DOM 输入框的focus()/blur()setVisibility、setDisable、setLoading在更新本地状态的同时还会同步更新暴露变量isVisible、isDisabled、isLoading该组件还保留了两个**已弃用deprecated**的兼容动作disable和visibility配置中标注Disable(deprecated)、Visibility(deprecated)仅当inputType TextInput时注入新应用建议统一使用setDisable/setVisibility。在 Cypress 端到端测试中textInput.cy.jssetVisibility、setDisable、setLoading与setText、clear、setFocus、setBlur一起被作为组件 Inspector 中的 Function 类型节点进行验证印证了这些 CSA 动作的真实可用性。Exposed Variables暴露变量Text Input 组件将以下状态暴露为可在 JS 中动态访问的变量定义见 textinput.js运行时同步逻辑见 useInput.js变量说明访问方式value保存用户在组件中输入的值动态 JS 访问例如{{components.textinput1.value}}label保存组件标签的值动态 JS 访问例如{{components.textinput1.label}}isValid指示输入是否满足校验条件动态 JS 访问例如{{components.textinput1.isValid}}isMandatory指示字段是否为必填动态 JS 访问例如{{components.textinput1.isMandatory}}isLoading指示组件是否处于加载中动态 JS 访问例如{{components.textinput1.isLoading}}isVisible指示组件是否可见动态 JS 访问例如{{components.textinput1.isVisible}}isDisabled指示组件是否被禁用动态 JS 访问例如{{components.textinput1.isDisabled}}实现机制value、label、isValid、isMandatory、isLoading、isVisible、isDisabled这些变量通过setExposedVariable/setExposedVariables实时同步到全局状态每当用户在输入框中键入内容setInputValue会同时更新value和isValid重新执行校验useInput.js。Cypress 测试验证了这些暴露变量的默认初始值value 、isMandatory false、isVisible true、isDisabled false、isLoading false、label Label、isValid truetextInput.cy.js。Validation输入验证Text Input 组件内置了完整的输入校验体系配置项定义见 textinput.js校验选项说明期望值Make this field mandatory若未输入任何值显示 Field cannot be empty 提示启用/禁用开关或点击fx输入逻辑表达式动态配置Regex用于校验输入的正则表达式正则表达式模式例如^\d{3}-\d{2}-\d{4}$配置中的占位示例为^[a-zA-Z0-9_ -]{3,16}$Min length设置允许的最少字符数整数例如6表示最少 6 个字符Max length设置允许的最多字符数整数例如12表示最多 12 个字符Custom validation针对特定条件指定自定义校验错误消息逻辑表达式例如{{components.textinput1.value5Value needs to be more than 5}}在 Custom Validation 中使用正则表达式要在Custom Validation内使用正则请使用如下格式格式{{(regexPattern.test(value)) ? : Error message;}}示例{{(/^\d{1,10}$/.test(components.textinput1.value)) ? : Error message;}}校验的底层实现从源码看Text Input 的校验最终统一走全局 store 中的validateWidget方法。仓库中的 useValidation.js 展示了校验对象的标准结构——regex、minLength、maxLength、customRule四个键分别对应上述校验项并返回{ isValid, validationError }组件每次渲染时先以当前值执行一次初始校验useState(validate(value))用户键入内容时setInputValue通过validateRef.current(value)重新校验并同步isValid暴露变量校验错误消息默认不立即展示而是在失焦handleBlur中setShowValidationError(true)、表单提交或调用setText之后才显示避免用户输入过程中被打断。Additional Actions附加动作在组件的额外行为区additionalActions分组见 textinput.js除文档列出的四项外该组件还提供了Enable clear button显示一键清空按钮与Collapse when hidden隐藏时是否折叠占位两个实用开关动作说明配置方式Loading state启用加载 spinner常配合isLoading使用以指示进行中的处理启用/禁用开关或点击fx输入逻辑表达式动态配置Visibility控制组件可见性启用/禁用开关或点击fx输入逻辑表达式动态配置Disable启用或禁用组件启用/禁用开关或点击fx输入逻辑表达式动态配置Tooltip悬停时提供附加信息字符串例如Enter your name here且可通过tooltipFormat在 Plain text / Markdown / HTML 三种格式间切换默认plainText实现细节loadingState为 true 时输入框会进入加载态——BaseInput中disabled{disable || loading}将禁用输入、aria-busy{loading}标记可访问性状态并在输入框右侧渲染 16px 的Loaderspinner同时useInput中useState(disabledState || loadingState)保证加载时组件自动表现为禁用BaseInput.jsx、useInput.js。清空按钮启用Enable clear buttonshowClearBtn后当输入框有值且未被禁用/加载时会渲染一个 ✕ 图标按钮。点击后调用handleClear——清空值并触发onChange事件TextInput.jsx同时输入框右侧预留 25px 内边距避免文字与按钮重叠。Devices设备可见性Text Input 组件支持按设备类型控制显示对应配置中的others.showOnDesktop/showOnMobile见 textinput.js属性说明期望值Show on desktop在桌面视图中显示组件通过开关设置或点击fx输入逻辑表达式动态配置默认值为trueShow on mobile在移动视图中显示组件通过开关设置或点击fx输入逻辑表达式动态配置默认值为falseStyles样式定制Text Input 的样式分为 Label、Field、Container 三个分组每个颜色类样式均支持取色器选择或点击fx输入返回 Hex 颜色代码的程序化表达式两种配置方式。样式完整定义见 textinput.js以下同时标注了各样式在配置中的默认值。Label标签样式标签属性说明配置方式Textcolor设置组件标签的颜色选择颜色或点击fx输入返回 Hex 颜色代码的代码默认var(--cc-primary-text)SizelabelFontSize设置标签字号数值输入默认12Alignment设置标签与输入框的位置关系切换选项或点击fx输入返回side或top的代码默认side方向direction标签在side布局下的左右排列方向左/右图标切换默认leftWidthauto / width / widthType设置输入框宽度保留Auto width使用标准宽度或取消勾选后通过滑块修改宽度或点击fx输入返回数值的代码widthType可进一步选择宽度相对于Of the Component默认还是Of the Field从源码看Label 的宽度与字号计算由 useInput.js 中的工具函数完成getLabelWidthOfInput依据widthType计算标签实际宽度ofField模式下标签宽度为设定值的 70%getLabelFontSize/getLabelHeight负责字号与行高换算非法数值回退到默认 12px。widthType: ofField在代码中被标记为已弃用checkIfInputWidgetTypeIsDeprecated新应用建议使用默认的ofComponent。Field输入框样式字段属性说明配置方式Background设置组件背景颜色选择颜色或点击fx输入返回 Hex 颜色代码的代码默认var(--cc-surface1-surface)Border设置组件边框颜色选择颜色或点击fx输入返回 Hex 颜色代码的代码默认var(--cc-default-border)Text设置输入文本的颜色选择颜色或点击fx输入返回 Hex 颜色代码的代码默认var(--cc-primary-text)Placeholder Text设置占位提示文字的颜色选择颜色或点击fx默认var(--cc-placeholder-text)Error text设置校验错误消息的颜色选择颜色或点击fx默认var(--cc-error-systemStatus)Icon为组件选择图标启用图标可见性、选择图标与图标颜色也可通过fx程序化设置默认图标IconHome2图标与图标颜色默认在界面中隐藏需手动开启iconVisibilityBorder radius修改组件圆角输入数值或点击fx输入返回数值的代码默认6Box shadow设置组件盒阴影属性选择阴影颜色并调整相关属性或通过fx程序化设置默认0px 0px 0px 0px #00000040实现细节边框颜色存在一套状态优先级逻辑BaseInput.jsx——校验失败且已展示错误时显示错误色var(--cc-error-systemStatus)聚焦时优先显示强调色accentColor默认var(--cc-primary-brand)否则使用borderColor禁用/加载态退化为禁用边框色。getModifiedColor(borderColor, 8)还会为边框生成更深的阴影色--tblr-input-border-color-darker。错误消息渲染为 11px 字号、16px 行高的文本位置跟随标签方向BaseInput.jsx。Container容器样式Padding内边距启用Default选项以保持标准内边距或选择None去除内边距。默认值为defaulttextinput.js。在top对齐布局下输入区域高度会依据标签高度与内边距自动计算height: calc(100% - labelHeight - padding * 2)其中标准内边距常量为BOX_PADDING * 2BaseInput.jsx。实战组合示例示例一RunJS 动态赋值与联动在画布放置 Text Input默认textinput1后新建一个RunJS查询并执行await components.textinput1.setText(this is input text); // 赋值并触发 onChange await components.textinput1.setDisable(true); // 禁用输入 await components.textinput1.setLoading(true); // 显示加载态示例二基于暴露变量的动态样式利用isValid与value暴露变量实现动态反馈例如在按钮的 Disable 条件中填写{{!components.textinput1.isValid || components.textinput1.value.length 6}}当输入不满足校验如少于 6 个字符时按钮自动禁用。示例三回车即提交为 Text Input 添加On enter pressed事件绑定一个查询或 Show alert action实现输入完成后回车直接执行的典型搜索/表单交互模式同时配合On change事件做实时过滤或计数。关键文件索引组件配置属性/校验/样式/CSA 定义与默认值textinput.js组件渲染入口 TextInput.jsx输入逻辑 Hook事件、CSA、暴露变量、值同步useInput.js基础输入组件渲染、样式状态机、清空按钮、错误提示BaseInput.jsx校验对象结构regex/minLength/maxLength/customRuleuseValidation.js端到端测试暴露变量与 CSA 验证textInput.cy.js官方文档原文text-input.md【免费下载链接】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），仅供参考