ToolJet Textarea 组件完全指南多行文本输入配置、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/ToolJetToolJet 的Textarea组件用于接收多行文本输入适用于备注、描述、反馈等需要多句段落的场景。本文以官方文档为骨架结合 组件配置定义、渲染实现 与底层 useInput Hook 源码系统讲解该组件的属性、事件、校验、组件级操作CSA、暴露变量与样式配置让你在低代码画布中高效构建并深度定制多行输入能力。组件定位与 Text Input 的区别Textarea 与 Text Input 组件在功能上非常相似二者都让用户在一个输入框中填写文本。核心差异在于Text Input接收单行文本适合姓名、邮箱、短关键词等输入Textarea接收多行文本适合需要多个句子或换行段落的长文本输入例如意见反馈、商品描述、JSON 配置粘贴等。在源码中Textarea 的定义非常清晰——description: Multi-line text input多行文本输入且它复用了与 Text Input 相同的BaseInput渲染体系仅在渲染时通过inputTypetextarea切换为原生textarea标签见 BaseInput.jsx 中的RenderInputinputType ! textarea ? input .../ : textarea rows{1} .../。这意味着 Textarea 天然继承了输入类组件统一的标签Label、校验Validation、事件Events与组件级操作CSA机制。Properties属性Textarea 的核心属性如下属性说明期望值Default value默认值组件加载时预先填入的初始值若用户未修改可通过组件变量取回该值。任意文本例如John Doe。Placeholder占位符输入框内的提示文字用户开始输入后自动消失。说明性文字例如Type name here。在上述文档属性之外从 textarea.js 配置定义 可以看到该组件还具备以下常用属性Label输入框标签用于描述字段含义默认值为LabelDynamic height动态高度默认关闭false。开启后textarea 的高度会随内容自动伸缩输入多行内容时组件自动变高无需手动拖拽调整Loading state加载状态开启后输入框进入加载态并禁用输入常用于异步数据就绪前占位Visibility可见性控制组件是否显示默认trueCollapse when hidden隐藏时折叠默认关闭。开启后当组件因可见性条件被隐藏时其在画布中占用的空间一并折叠避免留下空白区域Disable禁用开启后组件不可交互默认false。说明默认值value与占位符placeholder属性类型均为code意味着它们不仅支持静态字符串还支持通过{{...}}双花括号语法绑定动态表达式例如绑定其他组件的值或查询结果。Events事件虽然原文档未单列事件表但从配置定义textarea.js 中events字段与 useInput.js 的实现可以确认Textarea 支持四个标准事件可用于在右侧属性面板中挂载动作如显示提示、执行查询、触发下载等事件触发时机On change用户在输入框内键入内容时触发handleChange中调用fireEvent(onChange)。On enter pressed用户在输入框内按下回车键时触发handleKeyUp检测到Enter键后调用fireEvent(onEnterPressed)。On focus用户点击输入框获得焦点时触发handleFocus中通过setTimeout延迟调用fireEvent(onFocus)。On blur用户点击输入框外部失去焦点时触发handleBlur中调用fireEvent(onBlur)同时触发校验错误展示。Validation校验Textarea 同样具备输入类组件统一的校验能力见 textarea.js 中validation字段Make this field mandatory必填开启后值为空即视为校验失败Regex通过正则表达式校验输入格式例如^[a-zA-Z0-9_ -]{3,16}$表示仅允许字母、数字、下划线、空格与连字符且长度为 3~16Min length / Max length限制输入的最小/最大字符数Custom validation自定义校验使用{{...}}表达式自定义校验逻辑例如{{components.text2.textyesvalid}}——表达式返回字符串时视为校验失败并展示该字符串作为错误提示。从 useInput.js 源码看每次值变化都会执行validateRef.current(value)并更新isValid暴露变量当校验失败且用户已交互showValidationError为真时BaseInput.jsx 会在输入框下方渲染错误提示文字并给输入框添加is-invalid样式、边框切换为错误色var(--cc-error-systemStatus)。Component Specific Actions组件级操作CSATextarea 支持通过**组件级操作CSA**在任意事件处理器中动态控制组件。文档明确给出两种核心操作操作说明调用方式setText设置 Textarea 的文本内容。在 RunJS 查询中执行await components.textarea1.setText(this is a textarea)。clear清空 Textarea 的值。在 RunJS 查询中执行await components.textarea1.clear()。在 useInput.js 中可以看到这两个操作的底层实现exposedVariables.setText async function (text) { setInputValue(text); setShowValidationError(true); fireEvent(onChange); }; exposedVariables.clear async function () { clearValue(); };值得注意的细节setText不仅更新值还会立即触发表单校验并派发onChange事件因此通过 CSA 写入的文本同样会走完整的校验链路clear则清空值并触发onChange。此外从 textarea.js 的actions定义看该组件还支持以下扩展 CSAsetFocus/setBlur聚焦/失焦输入框对应inputRef.current.focus()/.blur()setVisibility以布尔值动态控制可见性如await components.textarea1.setVisibility(true)setDisable以布尔值动态禁用组件如await components.textarea1.setDisable(true)setLoading以布尔值动态切换加载状态disable / visibility已标记为 deprecated弃用的旧式操作建议改用setDisable/setVisibility。Exposed Variables暴露变量Textarea 暴露的变量可在应用的任意表达式中动态读取变量说明访问方式value当前输入框内持有的文本值。{{components.textarea1.value}}结合 useInput.js 的exposedVariables定义Textarea 实际还暴露了下列辅助变量便于你在条件逻辑、校验提示与 UI 联动中使用isValid当前值是否通过校验布尔值isMandatory是否被标记为必填布尔值isLoading是否处于加载状态布尔值isVisible组件当前是否可见布尔值isDisabled组件当前是否被禁用布尔值label当前标签文本。例如你可以用{{components.textarea1.value.length}}在文本输入的同时实时统计字符数或用{{components.textarea1.isValid}}控制提交按钮的可用状态。Styles样式Textarea 支持以下核心样式配置样式说明期望值Visibility控制组件可见性。设为{{false}}后应用部署时组件将不可见。开关按钮或通过fx传入布尔值/返回布尔值的逻辑表达式如{{true}}/{{false}}。Disable设为 true 时组件不可用。开关按钮或通过fx传入布尔表达式。Border radius调整组件四角的圆角程度。数值。默认值为6见 textarea.js。Box Shadow盒阴影Box Shadow属性用于为组件框架添加阴影效果。你可以通过X / Y 滑杆分别指定水平与垂直偏移量并配置模糊半径Blur、扩散半径Spread与阴影颜色。默认阴影值为0px 0px 0px 0px #00000040即无位移、40% 透明度黑色的微弱阴影。除了文档列出的项从 textarea.js 的styles定义看该组件还提供更细粒度的外观控制标签样式文本颜色color、标签字号labelFontSize默认12、标签对齐方式alignmentSide 侧边 / Top 顶部、方向左/右、标签区宽度width默认33与是否自动auto默认true字段样式背景色backgroundColor、边框色borderColor、强调色accentColor聚焦时边框高亮色、文本颜色textColor、错误文本颜色errTextColor、图标与图标颜色icon/iconColor默认可选配左侧图标、内边距paddingDefault / None。这些样式大多支持fx动态绑定可依据应用状态实时切换外观。General通用Tooltip提示气泡Tooltip用于在鼠标悬停于组件上时显示额外的说明信息。在属性面板的Tooltip输入框中填写文本后用户将鼠标悬停到 Textarea 组件上即可看到该提示。从源码看Tooltip 还支持格式切换tooltipFormat可选Plain text纯文本、Markdown与HTML三种渲染格式默认使用纯文本适合需要富文本提示如链接、加粗、列表的场景。Devices设备可见性Textarea 可针对不同终端分别控制显隐设备说明期望值Show on desktop在桌面端视图中显示组件。开关按钮或通过fx配置逻辑表达式。Show on mobile在移动端视图中显示组件。开关按钮或通过fx配置逻辑表达式。两者默认值分别为true/false见 textarea.js 中others.showOnDesktop/others.showOnMobile即组件默认在桌面端展示、在移动端隐藏可按需调整。源码级实现解析1. 组件注册与配置驱动Textarea 的完整配置定义在 frontend/src/AppBuilder/WidgetManager/widgets/textarea.js。它是一个**配置驱动config-driven**的组件名称Textarea、展示名Text Area、描述Multi-line text input、画布默认尺寸宽10、高100以及上述所有属性、校验、事件、样式、暴露变量与 CSA 动作均在此声明。右侧属性面板的 UI 会根据这份配置自动渲染无需为每个配置项手写面板代码。2. 渲染与动态高度frontend/src/AppBuilder/Widgets/TextArea.jsx 是组件的渲染入口它通过useInput(props)获得统一输入逻辑再委托给BaseInput完成实际 DOM 渲染。值得展开的是其**动态高度Dynamic height**实现开启动态高度后properties.dynamicHeight currentMode view组件通过useHeightObserver观察输入内容高度变化resizeTextArea回调会把 textarea 高度先设为auto再依据内容scrollHeight与容器可用高度扣除内边距与边框比较取较大值作为最终高度useDynamicHeightHook 会把计算出的高度回写到布局系统使相邻组件随之重新排布。因此动态高度模式下的 Textarea 在输入多行内容时会越写越长非常适合评论、备注等不确定输入量的场景。3. 统一输入逻辑与无障碍frontend/src/AppBuilder/Widgets/BaseComponents/hooks/useInput.js 承载了所有输入类组件共享的状态与行为值管理value、校验状态validationStatus/isValid/validationError、加载/禁用/可见性状态同步、CSA 动作注册以及onChange/onEnterPressed/onFocus/onBlur事件派发。而 BaseInput.jsx 则负责最终渲染它为 textarea 类型设置了rows{1}并注入了完整的无障碍属性aria-disabled、aria-busy、aria-required、aria-invalid、aria-label等确保多行输入在键盘与屏幕阅读器场景下同样可用。小结Textarea 是 ToolJet 中处理长文本输入的标准组件它继承了输入类组件的完整属性、事件、校验与 CSA 体系并额外提供动态高度等适合多行内容的特性。无论你是在表单中收集反馈、在管理后台编辑描述还是通过 RunJS 以components.textarea1.setText(...)编程式驱动输入内容都可以基于本文的配置项与源码路径快速定位、按需定制。相关文件索引官方文档docs/docs/widgets/textarea.md组件配置定义frontend/src/AppBuilder/WidgetManager/widgets/textarea.js组件渲染实现frontend/src/AppBuilder/Widgets/TextArea.jsx统一输入逻辑frontend/src/AppBuilder/Widgets/BaseComponents/hooks/useInput.js基础渲染组件frontend/src/AppBuilder/Widgets/BaseComponents/BaseInput.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），仅供参考