ToolJet Tags 组件完全指南：用数组数据渲染标签、配置样式与动态数据-迪斯科星球

ToolJet Tags 组件完全指南：用数组数据渲染标签、配置样式与动态数据

【免费下载链接】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

Tags（标签）组件是 ToolJet 应用编辑器中用于将数组数据渲染为标签集合的轻量级展示组件，常见于状态标识、分类标记等场景。本文以 ToolJet v2.50.0-LTS 文档为基础，结合当前仓库的组件定义源码与运行时实现，系统讲解 Tags 组件的数据结构、属性配置、布局与样式控制，并补充源码级别的实现细节，帮助你完整掌握该组件的配置与使用。

组件概述

Tags 组件用于把数组类型的数据以标签（Tag）的形式呈现出来。在 ToolJet 应用编辑器中，从左侧组件库拖入 Tags 组件后，右侧属性面板即可配置标签内容、显示行为与外观样式。组件默认尺寸为宽 9 格、高 30 格（见组件定义文件），展示效果为一系列带圆角、可自定义颜色的胶囊形标签。

Properties（属性）

Tags（标签数据）

Tags 属性用于设置组件要展示的标签数组，其值必须是一个对象数组，每个对象至少包含以下三个字段：

title：标签显示的文字内容；
color：该标签的背景色，使用十六进制颜色码；
textColor：标签内文字的颜色，使用十六进制颜色码。

官方文档给出的标准示例格式如下：

{{ [ { title: 'success', color: '#2fb344', textColor: '#fff' }, { title: 'info', color: '#206bc4', textColor: '#fff' }, { title: 'warning', color: '#f59f00', textColor: '#fff' }, { title: 'danger', color: '#d63939', textColor: '#fff' } ] }}

需要注意，该属性是一个表达式，需要包裹在{{ }}中，这样 ToolJet 才能把它解析为真实的 JS 数组并渲染。上述示例定义了success、info、warning、danger四个标签，分别使用绿色、蓝色、橙色、红色背景与白色文字。

源码中的默认数据结构

从当前仓库的组件定义源码看，Tags 组件默认提供的标签数据结构为（widgets/tags.js）：

{{ [ { title: 'success', color: '#34A94733', textColor: '#34A947' }, { title: 'info', color: '#405DE61A', textColor: '#405DE6' }, { title: 'warning', color: '#F357171A', textColor: '#F35717' }, { title: 'danger', color: '#EB2E3933', textColor: '#EB2E39' } ] }}

这里采用了"浅色背景 + 深色文字"的配色方案（背景色在主题色后追加两位透明度值），并额外支持icon（图标名）、iconVisibility（图标显隐）、visible（单个标签显隐）等字段，具体字段在运行时渲染逻辑中的处理可参考 Tags.jsx。其中visible字段会过滤掉值为false的标签（Tags.jsx），可用于按条件动态隐藏某些标签。

静态配置与动态数据两种模式

虽然 v2.50.0-LTS 文档只给出了"数组表达式"这一种写法，但从当前仓库源码可以推断，该组件已演进出两种数据来源模式（widgets/tags.js）：

静态模式（Dynamic tags 关闭）：在属性面板的 Options 手风琴中逐条添加标签选项，每个选项可配置标题、背景色（Pill color）、文字与图标颜色（Text and icon）、图标（Icon）以及单个标签的显隐（Tag visibility）；标签项支持拖拽排序、删除，点击 "Add new option" 可新增标签，新增标签会按内置 12 色调色板自动取色（实现见 Inspector/Components/Tags.jsx）；
动态模式（Dynamic tags 开启）：显示 Schema 代码编辑框，直接以表达式形式传入标签数组，适合与查询结果、状态变量联动渲染。

运行时组件根据advanced开关选择数据源：动态模式下优先取data字段，其次回退到schema；静态模式下取options配置（Tags.jsx）。因此，如果你使用的是旧版 Tags 属性面板，直接按文档示例传入对象数组即可；若希望标签随数据动态变化，可开启 Dynamic tags 并绑定表达式。

Overflow（溢出行为）

组件还提供 Overflow 开关，决定标签超出容器宽度时的处理方式（widgets/tags.js）：

wrap（默认）：标签自动换行，容器纵向滚动；
scroll：标签保持单行，容器横向滚动。

Component Specific Actions（组件特定动作）

v2.50.0-LTS 文档说明：Tags 组件当前没有实现任何 CSA（Component-Specific Actions），即无法通过事件动作来调控该组件。

补充说明：从当前仓库源码看，组件定义文件中已注册了setVisibility、setDisable、setLoading三个通用动作（widgets/tags.js），运行时也暴露了对应的设置方法（Tags.jsx），这是较新版本的能力扩展。若你的实例停留在 v2.50.0-LTS，请以"无 CSA"为准。

Exposed Variables（暴露变量）

v2.50.0-LTS 文档说明：Tags 组件当前没有暴露任何变量，因此无法在表达式中直接引用该组件的标签数据。

同理，当前仓库源码中组件已额外暴露tags（标签标题数组）、isVisible、isLoading、isDisabled等变量（Tags.jsx），供较新版本使用。在 v2.50.0-LTS 下请不要依赖这些变量编写表达式。

General（通用）

Tooltip（提示信息）

Tooltip 用于在用户将鼠标悬停在组件上时显示额外的说明文字。在属性面板的General手风琴下，以字符串格式填入提示内容即可，悬停时组件会将该字符串展示为气泡提示。

在较新版本中，Tooltip 还支持格式切换：Plain text（纯文本，默认）、Markdown、HTML三种渲染格式（widgets/tags.js），默认提示文本为 "Enter tooltip text"。悬停提示的实现位于组件容器外层（Tags.jsx），由编辑器统一注入。

Layout（布局）

Tags 组件的布局属性如下表所示：

Layout	说明	期望值
Show on desktop	开关控制是否在桌面端显示。	可点击fx以编程方式设置值为`{{true}}`或`{{false}}`。
Show on mobile	开关控制是否在移动端显示。	可点击fx以编程方式设置值为`{{true}}`或`{{false}}`。

源码中showOnDesktop默认值为{{true}}、showOnMobile默认值为{{false}}（widgets/tags.js），即默认桌面端可见、移动端不可见，你可在属性面板的Devices手风琴中调整（Inspector/Components/Tags.jsx）。

Styles（样式）

Tags 组件的样式属性如下：

Visibility	说明	默认值
Visibility	开关控制组件是否可见。可点击fx编程修改其值；若为`{{false}}`，应用部署后组件将不可见。	默认`{{true}}`。

此外，从当前仓库源码可以确认，组件还提供以下外观样式项（widgets/tags.js）：

Size：标签尺寸，small（小）或large（大）。小号标签为 12px 字号、20px 高、内边距 4px 9px；大号标签为 14px 字号、28px 高、内边距 4px 12px（Tags.jsx）；
Border radius：标签圆角，默认8；
Padding：容器内边距，default（默认）或none（无）；
Box shadow：容器阴影，默认0px 0px 0px 0px #00000040；
Alignment：标签对齐方式，left（默认）、center、right。

这些样式项的实际生效逻辑见 Tags.jsx：当溢出模式为wrap时，justifyContent依据对齐方式在flex-start/center/flex-end间切换；禁用状态下组件透明度降为 0.5 且指针事件关闭。

小结

ToolJet 的 Tags 组件是一个结构清晰、配置灵活的数组展示组件。核心要点可归纳为：

数据格式：{{ [{ title, color, textColor }, ...] }}对象数组表达式，是使用该组件的基础；
模式选择：静态模式下逐条配置选项，动态模式下用 Schema 表达式绑定数据；
能力边界：v2.50.0-LTS 下无 CSA、无暴露变量，控制交互需依赖布局开关（Show on desktop/mobile）与样式开关（Visibility）实现；
视觉定制：通过 Size、Border radius、Alignment、Overflow 等样式与行为项，可适配状态标签、分类标记等多种展示需求。

组件配置的完整字段定义可参考 widgets/tags.js，运行时渲染与状态处理可参考 Widgets/Tags/Tags.jsx，属性面板交互实现可参考 RightSideBar/Inspector/Components/Tags.jsx。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析