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/ToolJetTree 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、高 200defaultSize默认标签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与handleCustomCheckL177-L239中实现。独立选择模式{{true}}每个节点独立勾选父节点勾选不再级联子节点且父节点只要有自身或后代被选即显示为全选无半选态见 TreeSelect.jsx 的displayChecked/displayIndeterminate计算。源码同时支持Dynamic optionsadvanced开关开启后从dataSchema读取结构数据关闭时则从组件内置的options读取见 TreeSelect.jsx。Events事件事件描述On change每当复选框值发生变化勾选或取消勾选时触发On check每当复选框被勾选时触发On uncheck每当复选框被取消勾选时触发这三个事件在 treeSelect.js 中注册为onChange/onCheck/onUnCheck并在 TreeSelect.jsx 与onCheckL305-L309中通过fireEvent实际派发。每个事件可以绑定一个或多个 Action如显示提示、运行查询、设置变量等关于全部 Actions 的详细说明可参考 Actions 参考文档 目录下的对应章节。Component Specific Actions组件专属动作原文档注明该组件当时未实现 CSA但结合当前仓库源码treeSelect.js 已注册以下 CSA可在事件中通过Run Action调用Action说明参数Set disable设置组件的禁用状态disable布尔值默认{{false}}Set loading设置组件的加载状态显示 spinnerloading布尔值默认{{false}}Set visibility设置组件的可见性visibility布尔值默认{{true}}Select option(s)以编程方式勾选指定节点values值数组默认{{[]}}Deselect option(s)以编程方式取消勾选指定节点values值数组默认{{[]}}这些动作在 useTreeSelect.js 中实现并暴露selectOptions会把传入值归一化normalizeValues后写入勾选状态并重算全部暴露变量deselectOptions则从当前勾选中剔除对应值三者均会同步触发校验validate并更新isValid。Exposed Variables暴露变量变量描述访问方式checked所有已勾选项的 value 值数组{{components.treeselect1.checked[1]}}expanded当前已展开节点的 value 值数组{{components.treeselect1.expanded[0]}}checkedPathArray已勾选项的路径以不同数组嵌套表示{{components.treeselect1.checkedPathArray[1][1]}}checkedPathStrings已勾选项的路径以短横线-连接的字符串表示{{components.treeselect1.checkedPathStrings[2]}}这些变量由 useTreeSelect.js 的computeExposedVars计算对每个勾选值从pathObj取根节点到该节点的完整路径数组如[asia,china,beijing]压入checkedPathArray并用join(-)生成checkedPathStrings如asia-china-beijing。除文档列出的四个变量外源码还额外暴露了以下变量见 treeSelect.js 与useTreeSelect.jsleafPathArray/leafPathStrings仅包含叶子节点无子节点的节点勾选项的路径数组/路径字符串由leafValues集合过滤得出useTreeSelect.jsisLoading、isVisible、isDisabled分别反映组件的加载、可见与禁用状态isValid、isMandatory反映校验结果与是否必填。路径变量实战示例假设勾选了Beijing则checked为[beijing]级联模式下还可能包含父节点checkedPathArray为[[asia,china,beijing]]checkedPathStrings为[asia-china-beijing]。你可以在按钮的 On click 事件中通过{{components.treeselect1.checkedPathStrings}}直接把完整的层级路径传给后端查询或setVariable动作。Layout布局布局项描述期望值Show on desktop是否在桌面端显示可通过点击fx以编程方式设置{{true}}或{{false}}Show on mobile是否在移动端显示可通过点击fx以编程方式设置{{true}}或{{false}}对应源码中的showOnDesktop/showOnMobile开关treeSelect.js默认分别为{{true}}与{{false}}见definition.othersL320-L323。Styles样式样式描述默认值Text color组件文本颜色可输入 Hex 色值或使用取色器var(--cc-primary-text)Checkbox color复选框勾选态背景颜色可输入 Hex 色值或使用取色器var(--cc-primary-brand)Visibility控制组件可见性仅接受布尔值为{{false}}时应用部署后组件不可见{{true}}Disable仅接受布尔值为{{true}}时组件被锁定、不可交互{{false}}任何带有fx按钮的属性都可以进行编程式配置Programmatically configured即用 JS 表达式动态控制其取值。源码中 treeSelect.js 定义的样式体系比文档更细除了上表外还包括Label 相关labelColor颜色、labelFontSize字号默认 12、labelStyleNew / Legacy 两种标签渲染风格、alignmentSide / Top、directionLeft / Right、autoLabelWidth与labelWidth标签宽度控制Switch/树节点相关borderColor边框、uncheckedBackground未勾选背景、checkmarkColor对勾颜色、textColor选项文本颜色Container 相关boxShadow盒阴影默认0px 0px 0px 0px #00000040、paddingDefault / None。这些样式会直接作用于 TreeSelect.jsx 中读取的样式变量并传给自定义复选框组件TreeSelectCheckbox与react-checkbox-tree的图标渲染L348-L379。其他可配置项在 treeSelect.js 中组件还提供以下补充配置校验ValidationMake this field mandatory必填开关默认{{false}}Minimum selection最小勾选数量数字默认 0Maximum selection最大勾选数量数字默认 0Custom validation自定义校验规则code 类型如{{components.text2.textyesvalid}}返回错误文案。 校验由useTreeSelect在每次勾选变化时触发结果写入isValid并展示错误提示见 useTreeSelect.js。通用行为Dynamic height动态高度视图模式下按内容自适应、Loading state加载状态显示 spinner见 TreeSelect.jsx、Collapse when hidden、Tooltip支持 Plain text / Markdown / HTML 三种格式。小结Tree Select 组件以labelvaluechildren的递归结构驱动通过级联勾选与半选态简化层级数据选择同时借助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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
ToolJet Tree Select 组件完全指南：树形多选、级联勾选与路径数据提取
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/ToolJetTree 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、高 200defaultSize默认标签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与handleCustomCheckL177-L239中实现。独立选择模式{{true}}每个节点独立勾选父节点勾选不再级联子节点且父节点只要有自身或后代被选即显示为全选无半选态见 TreeSelect.jsx 的displayChecked/displayIndeterminate计算。源码同时支持Dynamic optionsadvanced开关开启后从dataSchema读取结构数据关闭时则从组件内置的options读取见 TreeSelect.jsx。Events事件事件描述On change每当复选框值发生变化勾选或取消勾选时触发On check每当复选框被勾选时触发On uncheck每当复选框被取消勾选时触发这三个事件在 treeSelect.js 中注册为onChange/onCheck/onUnCheck并在 TreeSelect.jsx 与onCheckL305-L309中通过fireEvent实际派发。每个事件可以绑定一个或多个 Action如显示提示、运行查询、设置变量等关于全部 Actions 的详细说明可参考 Actions 参考文档 目录下的对应章节。Component Specific Actions组件专属动作原文档注明该组件当时未实现 CSA但结合当前仓库源码treeSelect.js 已注册以下 CSA可在事件中通过Run Action调用Action说明参数Set disable设置组件的禁用状态disable布尔值默认{{false}}Set loading设置组件的加载状态显示 spinnerloading布尔值默认{{false}}Set visibility设置组件的可见性visibility布尔值默认{{true}}Select option(s)以编程方式勾选指定节点values值数组默认{{[]}}Deselect option(s)以编程方式取消勾选指定节点values值数组默认{{[]}}这些动作在 useTreeSelect.js 中实现并暴露selectOptions会把传入值归一化normalizeValues后写入勾选状态并重算全部暴露变量deselectOptions则从当前勾选中剔除对应值三者均会同步触发校验validate并更新isValid。Exposed Variables暴露变量变量描述访问方式checked所有已勾选项的 value 值数组{{components.treeselect1.checked[1]}}expanded当前已展开节点的 value 值数组{{components.treeselect1.expanded[0]}}checkedPathArray已勾选项的路径以不同数组嵌套表示{{components.treeselect1.checkedPathArray[1][1]}}checkedPathStrings已勾选项的路径以短横线-连接的字符串表示{{components.treeselect1.checkedPathStrings[2]}}这些变量由 useTreeSelect.js 的computeExposedVars计算对每个勾选值从pathObj取根节点到该节点的完整路径数组如[asia,china,beijing]压入checkedPathArray并用join(-)生成checkedPathStrings如asia-china-beijing。除文档列出的四个变量外源码还额外暴露了以下变量见 treeSelect.js 与useTreeSelect.jsleafPathArray/leafPathStrings仅包含叶子节点无子节点的节点勾选项的路径数组/路径字符串由leafValues集合过滤得出useTreeSelect.jsisLoading、isVisible、isDisabled分别反映组件的加载、可见与禁用状态isValid、isMandatory反映校验结果与是否必填。路径变量实战示例假设勾选了Beijing则checked为[beijing]级联模式下还可能包含父节点checkedPathArray为[[asia,china,beijing]]checkedPathStrings为[asia-china-beijing]。你可以在按钮的 On click 事件中通过{{components.treeselect1.checkedPathStrings}}直接把完整的层级路径传给后端查询或setVariable动作。Layout布局布局项描述期望值Show on desktop是否在桌面端显示可通过点击fx以编程方式设置{{true}}或{{false}}Show on mobile是否在移动端显示可通过点击fx以编程方式设置{{true}}或{{false}}对应源码中的showOnDesktop/showOnMobile开关treeSelect.js默认分别为{{true}}与{{false}}见definition.othersL320-L323。Styles样式样式描述默认值Text color组件文本颜色可输入 Hex 色值或使用取色器var(--cc-primary-text)Checkbox color复选框勾选态背景颜色可输入 Hex 色值或使用取色器var(--cc-primary-brand)Visibility控制组件可见性仅接受布尔值为{{false}}时应用部署后组件不可见{{true}}Disable仅接受布尔值为{{true}}时组件被锁定、不可交互{{false}}任何带有fx按钮的属性都可以进行编程式配置Programmatically configured即用 JS 表达式动态控制其取值。源码中 treeSelect.js 定义的样式体系比文档更细除了上表外还包括Label 相关labelColor颜色、labelFontSize字号默认 12、labelStyleNew / Legacy 两种标签渲染风格、alignmentSide / Top、directionLeft / Right、autoLabelWidth与labelWidth标签宽度控制Switch/树节点相关borderColor边框、uncheckedBackground未勾选背景、checkmarkColor对勾颜色、textColor选项文本颜色Container 相关boxShadow盒阴影默认0px 0px 0px 0px #00000040、paddingDefault / None。这些样式会直接作用于 TreeSelect.jsx 中读取的样式变量并传给自定义复选框组件TreeSelectCheckbox与react-checkbox-tree的图标渲染L348-L379。其他可配置项在 treeSelect.js 中组件还提供以下补充配置校验ValidationMake this field mandatory必填开关默认{{false}}Minimum selection最小勾选数量数字默认 0Maximum selection最大勾选数量数字默认 0Custom validation自定义校验规则code 类型如{{components.text2.textyesvalid}}返回错误文案。 校验由useTreeSelect在每次勾选变化时触发结果写入isValid并展示错误提示见 useTreeSelect.js。通用行为Dynamic height动态高度视图模式下按内容自适应、Loading state加载状态显示 spinner见 TreeSelect.jsx、Collapse when hidden、Tooltip支持 Plain text / Markdown / HTML 三种格式。小结Tree Select 组件以labelvaluechildren的递归结构驱动通过级联勾选与半选态简化层级数据选择同时借助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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
