ToolJet Text 组件完全指南：数据格式、事件与 CSA 动作、样式体系详解

ToolJet Text 组件完全指南：数据格式、事件与 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

Text（文本）组件是 ToolJet 应用画布中最基础也最常用的组件之一，可用于创建标题（header）、副标题（sub-header）、为各类输入框添加标签（label），以及展示任意静态或动态文本内容。本文基于 ToolJet 2.50.0-LTS 版本文档（text.md），结合仓库前端源码（Text.jsx、text.js）与 Cypress 测试用例，系统讲解 Text 组件的数据格式、事件、组件特定动作（CSA）、暴露变量、附加动作、设备可见性与完整样式配置，帮助你从“会用”到“理解其底层实现”。

一、Text 组件的定位与适用场景

Text 组件本质上是一个“内容展示容器”，它不接收用户输入，而是负责把文本内容以多种格式渲染到画布上。典型用法包括：

• 页面大标题、小节标题、副标题；
• 表单中放在输入框旁边的说明文字 / 标签；
• 展示来自数据查询、全局变量、当前用户信息的动态文本（如Hello {{globals.currentUser.firstName}}）；
• 展示富格式内容（Markdown 文档、HTML 片段）。

从组件注册配置看（text.js），Text 组件的官方描述是 “Display text or HTML”，默认尺寸为宽度 6 格、高度 40px，新建实例时默认文本为Hello {{globals.currentUser.firstName}}👋，直接演示了“文本内容支持模板表达式”的能力。

二、数据（Data）：三种文本格式

Text 组件的核心数据属性是Text Format（文本格式）与Text（文本内容）。文本格式支持三种类型：

对应到组件配置源码（text.js），textFormat是一个 switch 类型属性，内部取值为plainText/markdown/html，默认值为plainText；text属性是 code 类型（Codehinter 输入框），默认内容为Hello, there!，同时其校验 schema 声明为字符串类型，并允许通过{{...}}模板表达式注入动态数据。

三种格式在源码中的渲染差异

在组件渲染实现（Text.jsx）中，三种格式走三条完全不同的渲染路径：

• 纯文本：直接渲染文本节点，如果传入值是对象（Object），会被JSON.stringify序列化后展示；
• Markdown：使用react-markdown渲染，并挂载了remark-gfm（GitHub 风格 Markdown，支持表格、删除线、任务列表等）和rehype-raw（允许在 Markdown 中嵌入原始 HTML）两个插件；
• HTML：通过dangerouslySetInnerHTML注入，但在注入前会经过DOMPurify.sanitize()净化处理，这是一个重要的安全细节——即便你粘贴了带脚本的 HTML，也会被清洗掉，避免 XSS 风险。

注意：由于 HTML 模式使用了dangerouslySetInnerHTML，建议仅在渲染可信内容时使用 HTML 格式；若内容来自用户输入，优先使用纯文本或 Markdown，或依赖上述 DOMPurify 净化兜底。

三、事件（Events）

Text 组件提供两个事件：

在源码中（Text.jsx），点击与悬停分别通过handleClick调用fireEvent('onClick')，以及容器根节点的onMouseOver调用fireEvent('onHover')实现。事件定义也注册在组件配置中（text.js）。

你可以为这两个事件挂接任意 ToolJet 动作（Action），例如打开网页、显示告警、运行查询、调用组件特定动作等。关于全部可用动作的详细说明，参见仓库中的 Actions 参考文档 及docs/docs/actions/目录下的其他动作文档。

四、组件特定动作（Component Specific Actions, CSA）

组件特定动作是 Text 组件独有的、可被外部调用的行为。Text 组件支持以下 CSA：

源码中的 CSA 实现

在 Text.jsx 中，组件挂载时通过setExposedVariables一次性暴露上述方法：

• setText(text)：更新内部 state 并同步text暴露变量；
• clear()：把文本置为空字符串；
• setVisibility(value)/setLoading(value)/setDisable(value)：均接收布尔值，更新对应内部 state 与暴露变量（isVisible/isLoading/isDisabled）。

同时，这些动作也注册在组件配置的actions数组中（text.js），因此它们不仅能在 RunJS 里被调用，还能直接在事件处理器中通过 “Control Component（控制组件）” 动作可视化地配置——在组件下拉框中选择目标组件、在动作下拉框中选择Set text/Clear/Set visibility/Set loading/Set disable并填写参数即可。完整的操作示例（以 Text Input 组件为例的按钮事件触发与 RunJS 清空）见 control-component.md。

五、暴露变量（Exposed Variables）

Text 组件向外部暴露以下变量，可在任意支持表达式的输入框中通过{{components.text1.xxx}}动态访问：

这些暴露变量与 CSA 是同一套状态系统的两面：源码中（Text.jsx）通过useEffect监听属性变化并同步isVisible/isLoading/isDisabled暴露变量，而text暴露变量则在文本属性变化（Text.jsx）及setText/clear调用时更新。text的初始默认值在配置中声明为Hello, there!（text.js）。

典型联动场景：把 Text 组件的text暴露变量绑定到其他组件的属性上，例如{{components.text1.text}}作为某按钮 Tooltip 的内容，实现“文本即数据”的跨组件通信。

六、附加动作（Additional Actions）

组件配置中additionalActions分组（text.js）提供了以下通用附加能力：

从源码可以看到，除文档表格列出的能力外，这一分组还包含两个额外属性：

• Dynamic height（动态高度）：开启后组件高度随内容自适应（currentMode === 'view'时生效），配合useDynamicHeight/useHeightObserver钩子（Text.jsx）在运行时观察内容高度并动态调整画布布局；
• Collapse when hidden（隐藏时折叠）：组件隐藏时同时收起占位空间。

此外，Tooltip 还支持tooltipFormat（Plain text / Markdown / HTML 三种格式）与tooltip文本两个配套属性（text.js），默认值为空字符串。加载状态的渲染在源码中通过条件分支实现（Text.jsx）：isLoading === true时，用 ToolJet 的Loader组件显示一个居中的 16px 加载动画，替代正文内容。

七、设备可见性（Devices）

这两个属性注册在组件配置的others分组中（text.js），新建组件时的默认值为桌面显示（{{true}}）、移动端隐藏（{{false}}），可在 Devices 面板中按需调整，实现响应式布局控制。

八、样式（Styles）：Text 分组

Text 组件的样式面板分为Text与Container两个手风琴分组。Text 分组控制文本本身的排版，共 12 项属性：

默认值与源码对应关系

以上样式在组件配置中都有明确注册与默认值（text.js），新拖入的 Text 组件默认样式为：

• textSize（Size）：14px；
• textAlign（Alignment）：left（水平对齐另有verticalAlignment，默认center，可选top/center/bottom）；
• fontWeight（Weight）：normal（实际下拉选项为normal/bold/lighter/bolder）；
• fontStyle（Style）：normal（可选normal/italic/oblique）；
• decoration：none；transformation：none；fontVariant：normal；
• lineHeight：1.5；textIndent：0；letterSpacing：0；wordSpacing：0；
• isScrollRequired（Scroll）：enabled（默认开启滚动，超出尺寸时出现滚动条）。

在渲染层（Text.jsx），这些样式被逐项映射为 CSS：fontSize以${textSize}px形式输出、textIndent/letterSpacing/wordSpacing均拼接px单位、lineHeight直接作为数值、垂直对齐则通过VERTICAL_ALIGNMENT_VS_CSS_VALUE映射表（top → flex-start、center → center、bottom → flex-end）转换为 flex 布局的justifyContent。滚动行为通过overflowX/overflowY控制：isScrollRequired === 'enabled'时overflowY: auto，否则为hidden。深色模式下，默认文本色#000会自动切换为白色，默认背景#edeff5与默认边框#f2f2f5也会自动替换为深色值（Text.jsx）。

九、样式（Styles）：Container 分组

Container 分组控制 Text 组件作为容器元素的盒子样式：

默认值与源码对应关系

Container 分组的默认值同样在配置中注册（text.js）：

• backgroundColor：#fff00000（透明）；borderColor：#ffffff00（透明）；
• borderRadius：6px；
• boxShadow：0px 0px 0px 0px #00000040；
• padding：default（可选default/none）。

渲染时这些值被应用到组件根节点（Text.jsx）：边框始终为1px solid并使用borderColor着色、borderRadius拼接px、boxShadow原样透传、backgroundColor直接生效。由于 Text 默认透明背景与透明边框，视觉上它只是一个“纯文本图层”，很适合叠放在其他组件之上做标注。

十、源码级实现细节速览

除了上述配置项，Text 组件的实现还有几个值得留意的工程细节：

1. 对象文本自动序列化：computeText()（Text.jsx）对0和false做了显式处理（转为字符串），避免文本内容为数字 0 或布尔 false 时被当作空值；渲染时若文本是对象则统一JSON.stringify，保证画布上永远显示字符串。
2. 文本属性响应式更新：properties.text变化时（非首次渲染）会重新计算文本并同步text暴露变量（Text.jsx），因此你可以在运行时通过修改属性（例如事件处理器的 Set variable 动作）动态改文本。
3. 可访问性与测试标识：根节点带有data-cy测试标识（...-text），Cypress 测试正是依赖它做断言。
4. 测试覆盖：仓库的 Cypress 用例 textHappyPath.cy.js 覆盖了 Text 组件的属性（拖入画布、验证组件名、在 Codehinter 中输入文本并断言画布文本）与样式（设置 Weight 为bolder、Font variant 为initial、Size 25、Line Height 3、Text Indent 2、Letter Spacing 2、Word Spacing 2、Border radius 2，以及文本色/背景/边框/阴影取色），可作为手动验证或二次开发的参考。

十一、小结

Text 组件是 ToolJet 中“内容展示”的基石：三种数据格式（纯文本 / Markdown / HTML）覆盖从简单标签到富文本的展示需求；setText、clear、setVisibility、setLoading、setDisable五个 CSA 与text、isLoading、isVisible、isDisabled四个暴露变量，让组件可以完全被查询、事件和其他组件驱动；Text 与 Container 两大样式分组提供了从字号字重到背景阴影的完整视觉控制。结合源码可知，其 Markdown 渲染基于react-markdown+ GFM 插件，HTML 渲染经过 DOMPurify 净化，动态高度与深色模式也做了贴心处理。

要继续深入，可参阅仓库内的 Action Reference 系列文档、Text 组件渲染源码 与 组件配置定义，以及最新版本文档 docs/docs/widgets/text.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