企业官网建设流程全解析

ToolJet Tree Select 组件完全指南：树形多选、级联勾选与路径数据提取

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

Tree Select（树形多选）是 ToolJet 应用编辑器中用于呈现可展开/折叠的树状复选框列表的表单类组件，适合组织架构、地区分类、商品类目等层级数据的批量选择场景。本文以 tree-select.md 官方文档为核心，结合前端源码（treeSelect.js、TreeSelect.jsx、useTreeSelect.js）深入讲解其数据模型、事件、暴露变量、校验与样式配置，读完你可以在应用编辑器中熟练配置并使用该组件，并能在 JS 表达式中灵活读取勾选结果与层级路径。

组件概述

Tree Select 本质上是一组以 TreeView（树形视图）呈现的复选框，节点可以展开或折叠，父节点与子节点之间存在级联勾选关系。在源码中，组件被注册为TreeSelect（见 componentTypes.js），内部基于react-checkbox-tree渲染（见 TreeSelect.jsx），并在此基础上封装了独立的勾选逻辑、暴露变量与校验机制。

从 treeSelect.js 的treeSelectConfig可以看到组件默认尺寸为宽 12、高 200（defaultSize），默认标签（Label）为Countries，并自带一份包含 Asia / Europe / Africa 的示例数据，方便你快速上手。

Properties（属性）

Title（标题）

Title用于设置组件的标题文本，接受String类型输入。对应源码中的label属性（默认值'Countries'，类型为 code，可结合表达式动态设置）。

Structure（数据结构）

Tree Select 的数据要求如下：

• 必须是对象数组（array of objects）；
• 每个对象必须包含label与value两个键；
• 若某节点下需要子节点，则必须传入children数组，子节点同样包含label与value键。

示例：

[ { "label": "Asia", "value": "asia", "children": [ { "label": "China", "value": "china", "children": [ { "label": "Beijing", "value": "beijing" }, { "label": "Shanghai", "value": "shanghai" } ] }, { "label": "Japan", "value": "japan" }, { "label": "India", "value": "india", "children": [ { "label": "Delhi", "value": "delhi" }, { "label": "Mumbai", "value": "mumbai" }, { "label": "Bengaluru", "value": "bengaluru" } ] } ] }, { "label": "Europe", "value": "europe", "children": [ { "label": "France", "value": "france" }, { "label": "Spain", "value": "spain" }, { "label": "England", "value": "england" } ] }, { "label": "Africa", "value": "africa" } ]

注意：value在整个结构数组中必须保持唯一。源码在 useTreeSelect.js 中会基于value构建value → 完整路径的映射表（pathObj），并在计算叶子节点集合（leafValues）时依赖唯一性，重复的value会导致路径计算与勾选状态错乱。

这段默认示例数据也直接内置于 treeSelect.js 的definition.properties.data与options中，首次拖入组件即可看到完整的三级树。

Checked values（默认勾选值）

Checked values是一个值数组，用于指定组件默认勾选的节点。示例：

["asia", "spain"]

在级联模式下，勾选父节点会连带勾选其全部子节点。源码中的checkedData属性（displayName 为Selected values）即对应此配置，默认值为{{["asia"]}}。

Expanded values（默认展开值）

与勾选值类似，Expanded values是一个值数组，用于指定默认展开的节点。示例：

["asia"]

对应源码中的expandedData属性，默认值为{{["asia"]}}。

级联勾选与独立选择（Allow independent selection）

源码中的allowIndependentSelection开关控制勾选模式，这是文档之外值得补充的关键行为差异：

• 级联模式（默认，{{false}}）：勾选父节点会递归勾选所有后代；取消勾选会移除自身及所有后代；当父节点的部分（而非全部）后代被勾选时，父节点显示为**半选（indeterminate）**状态。这一逻辑在 TreeSelect.jsx 的getHalfCheckedValues与handleCustomCheck（L177-L239）中实现。
• 独立选择模式（{{true}}）：每个节点独立勾选，父节点勾选不再级联子节点，且父节点只要有自身或后代被选即显示为全选（无半选态），见 TreeSelect.jsx 的displayChecked/displayIndeterminate计算。

源码同时支持Dynamic options（advanced开关）：开启后从data（Schema）读取结构数据，关闭时则从组件内置的options读取，见 TreeSelect.jsx。

Events（事件）

这三个事件在 treeSelect.js 中注册为onChange/onCheck/onUnCheck，并在 TreeSelect.jsx 与onCheck（L305-L309）中通过fireEvent实际派发。每个事件可以绑定一个或多个 Action（如显示提示、运行查询、设置变量等），关于全部 Actions 的详细说明，可参考 Actions 参考文档 目录下的对应章节。

Component Specific Actions（组件专属动作）

原文档注明该组件当时未实现 CSA；但结合当前仓库源码，treeSelect.js 已注册以下 CSA，可在事件中通过Run Action调用：

这些动作在 useTreeSelect.js 中实现并暴露：selectOptions会把传入值归一化（normalizeValues）后写入勾选状态并重算全部暴露变量，deselectOptions则从当前勾选中剔除对应值；三者均会同步触发校验（validate）并更新isValid。

Exposed Variables（暴露变量）

这些变量由 useTreeSelect.js 的computeExposedVars计算：对每个勾选值，从pathObj取根节点到该节点的完整路径数组（如["asia","china","beijing"]），压入checkedPathArray，并用join('-')生成checkedPathStrings（如"asia-china-beijing"）。

除文档列出的四个变量外，源码还额外暴露了以下变量（见 treeSelect.js 与useTreeSelect.js）：

• leafPathArray/leafPathStrings：仅包含叶子节点（无子节点的节点）勾选项的路径数组/路径字符串，由leafValues集合过滤得出（useTreeSelect.js）；
• isLoading、isVisible、isDisabled：分别反映组件的加载、可见与禁用状态；
• isValid、isMandatory：反映校验结果与是否必填。

路径变量实战示例：假设勾选了Beijing，则checked为["beijing"]（级联模式下还可能包含父节点），checkedPathArray为[["asia","china","beijing"]]，checkedPathStrings为["asia-china-beijing"]。你可以在按钮的 On click 事件中通过{{components.treeselect1.checkedPathStrings}}直接把完整的层级路径传给后端查询或setVariable动作。

Layout（布局）

对应源码中的showOnDesktop/showOnMobile开关（treeSelect.js），默认分别为{{true}}与{{false}}（见definition.others，L320-L323）。

Styles（样式）

任何带有fx按钮的属性都可以进行编程式配置（Programmatically configured），即用 JS 表达式动态控制其取值。

源码中 treeSelect.js 定义的样式体系比文档更细，除了上表外还包括：

• Label 相关：labelColor（颜色）、labelFontSize（字号，默认 12）、labelStyle（New / Legacy 两种标签渲染风格）、alignment（Side / Top）、direction（Left / Right）、autoLabelWidth与labelWidth（标签宽度控制）；
• Switch/树节点相关：borderColor（边框）、uncheckedBackground（未勾选背景）、checkmarkColor（对勾颜色）、textColor（选项文本颜色）；
• Container 相关：boxShadow（盒阴影，默认0px 0px 0px 0px #00000040）、padding（Default / None）。

这些样式会直接作用于 TreeSelect.jsx 中读取的样式变量，并传给自定义复选框组件TreeSelectCheckbox与react-checkbox-tree的图标渲染（L348-L379）。

其他可配置项

在 treeSelect.js 中，组件还提供以下补充配置：

• 校验（Validation）：
  • Make this field mandatory（必填开关，默认{{false}}）；
  • Minimum selection（最小勾选数量，数字，默认 0）；
  • Maximum selection（最大勾选数量，数字，默认 0）；
  • Custom validation（自定义校验规则，code 类型，如{{components.text2.text=='yes'&&'valid'}}返回错误文案）。 校验由useTreeSelect在每次勾选变化时触发，结果写入isValid并展示错误提示（见 useTreeSelect.js）。
• 通用行为：Dynamic height（动态高度，视图模式下按内容自适应）、Loading state（加载状态，显示 spinner，见 TreeSelect.jsx）、Collapse when hidden、Tooltip（支持 Plain text / Markdown / HTML 三种格式）。

小结

Tree Select 组件以label+value+children的递归结构驱动，通过级联勾选与半选态简化层级数据选择，同时借助checked、checkedPathArray、checkedPathStrings、leafPathArray等暴露变量，把“勾选了哪些节点”和“这些节点在树中的完整路径”直接暴露给 JS 表达式与事件动作，非常适合用于地区/组织/类目等层级结构的多选与后续数据处理场景。若需深入源码，可重点阅读 TreeSelect.jsx、useTreeSelect.js 与组件配置 treeSelect.js。

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