NocoBase 级联选择字段树表数据的多级联动选择实现与配置详解【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase级联选择CascadeSelect是 NocoBase 界面搭建中专门面向树表关系字段的高级组件它以逐级联动的下拉框形态呈现树形数据让用户像选择省 → 市 → 区一样快速完成深层级数据的选取。本文基于官方文档与前端源码讲清它的适用前提目标表必须为树表、单选/多选的取值差异、标题字段与数据范围两大配置项并深入解析其懒加载、模糊搜索与值归一化的底层实现。适用场景与组件定位根据 级联选择文档 的定义级联选择器适用于目标表为树表的关系字段用户可以按照树表的层级结构选取数据并支持对数据的模糊搜索。它在关系字段组件家族中处于什么位置从 关系字段组件文档 可以看到NocoBase 的关系字段默认以下拉选择器呈现另有数据选择器Picker子表单SubForm子表格SubTable子详情Nester文件管理器FileManager标题ReadPretty等多种形态。级联选择是其中唯一按层级逐级展开的编辑态组件。从源码结构看这一仅限树表的限制在组件模式选项中得到了印证。useFieldModeOptions 中明确写道if (collection?.template tree [m2m, o2m, m2o].includes(collectionField.interface)) { return isReadPretty ? [ /* 阅读态标题 / 标签 / 子详情 / 子表格 */ ] : [ { label: t(Select), value: Select }, { label: t(Record picker), value: Picker }, !isTableField [m2m, o2m].includes(collectionField.interface) { label: t(Sub-table), value: SubTable }, !isTableField { label: t(Cascader Select), value: CascadeSelect }, !isTableField { label: t(Sub-form), value: Nester }, { label: t(Sub-form(Popover)), value: PopoverNester }, ]; }也就是说只有当关系字段的目标数据表模板为tree且接口类型为m2o多对一/对一、o2m一对多/对多或m2m多对多时字段设置中才会出现级联选择Cascader Select这一选项。这是使用该组件的第一个硬性前提。使用说明对一为单选对多为多选文档中给出了两种核心使用形态关系为对一m2o级联为单选字段最终值就是链路上选中的那条记录本身关系为对多o2m/m2m级联为多选用户可以添加多条级联选择链每条链独立选择一条层级路径整体构成多选结果。这与源码中的分支逻辑完全一致。InternalCascadeSelect.tsx 在渲染时按关系接口做了分流FormProvider form{selectForm} {collectionField.interface m2o ? ( SchemaComponent components{{ FormItem }} schema{{ ...fieldSchema, x-component: AssociationCascadeSelect, x-component-props: { ...props }, }} / ) : ( SchemaField schema{schema} / )} /FormProviderm2o分支直接渲染单个AssociationCascadeSelect一次只能选一条链其他分支o2m/m2m渲染的是select_array数组 schema——内部基于 Formily 的ArrayItems实现包含ArrayItems.SortHandle拖动排序、级联选择器本身、ArrayItems.Remove移除以及ArrayItems.Addition添加按钮从而形成多条级联链 可排序可增删的多选结构。值的归一化表单里存的不是路径数组一个容易踩坑的点级联控件内部用选中路径数组每一级的{ key, value, children }来驱动 UI但最终写入表单的值并非这个路径。源码中的normalizeToOneCascadeValue与extractLastNonNullValueObjectsInternalCascadeSelect.tsx#L459-L502会沿路径回溯只提取最后一个非空选中项function normalizeToOneCascadeValue(value) { if (!Array.isArray(value)) { return value; } const result extractLastNonNullValueObjects(value); return Array.isArray(result) result.length 0 ? null : result; }这意味着对于省 → 市 → 区三级选择若用户选到市就停下表单值只会是市这条记录而不是把省也一并保存。多选场景下则对每条链分别做同样的提取再过滤掉空对象后组成数组。仓库中的测试用例 InternalCascadeSelect.test.tsx 专门验证了这两个关键行为m2o 值同步外部表单设置了一条带parent嵌套的树记录id: 3 → 2 → 1组件会将其展开为逐级回显的三个下拉且transformNestedData负责把parent嵌套结构摊平为逐级选项值保持为记录而非路径数组选择节点 2 后断言form.values.org_m2o_tree满足{ id: 2, parentId: null }而不是数组父级选完后保留下一层级选中 id 为 1 的父节点后会请求parentId: 1的子级数据并渲染出第二个下拉框继续选择后值变为{ id: 2, parentId: 1 }。字段配置项字段设置面板由 cascadeSelectComponentFieldSettings 定义共包含四个设置项export const cascadeSelectComponentFieldSettings new SchemaSettings({ name: fieldSettings:component:CascadeSelect, items: [fieldComponent, titleField, ellipsisSettingsItem, setTheDataScope], });即字段组件切换为下拉选择器、数据选择器等其他模式、标题字段、省略号设置超长文本省略显示、设置数据范围。其中与级联选择行为强相关的核心配置项有两个。标题字段标题字段是选项显示的标签字段。配置位置在字段设置的标题字段选项中它写回到字段 schema 的x-component-props.fieldNames.label上见 cascadeSelectComponentFieldSettings.tsx#L81-L98 的onChange。标题字段在级联选择中有双重作用显示标签每一级下拉中展示给用户的文本模糊搜索入口文档明确指出支持根据标题字段快速检索。从源码看搜索逻辑位于 onSearchconst onSearch async (search, selectedValue) { const serachParam search ? { [fieldNames.label]: { [operator]: search, }, } : {}; // ... const result await handleGetOptions({ ...serachParam, parentId: selectedValue?.key, }); // ... };它把搜索词拼进过滤条件{ [标题字段]: { $includes: 搜索词 } }并叠加parentId约束在当前已选层级的子集内做服务端搜索。默认操作符为$includes模糊包含但若标题字段本身有filterable能力则优先使用该接口定义的第一个过滤操作符InternalCascadeSelect.tsx#L56-L61。因此选择一个文本类字段如名称、编码作为标题字段模糊搜索体验最佳而不同字段类型的标题字段还会影响标签的呈现方式——例如选项字段会渲染为彩色标签Tag日期字段会格式化为YYYY-MM-DD这些逻辑同样封装在mapOptionsToTags中。关于标题字段的作用范围数据表级全局配置 vs 字段级配置、优先级关系更多内容可参考 标题字段。设置数据范围数据范围用于控制树形列表的数据范围且文档特别强调了一个树表特有的行为当子记录符合条件时该父记录也会出现。这与普通表格按行过滤的语义不同——过滤是向父级冒泡的保证层级链路完整。数据范围支持三类条件详见 设置数据范围静态值如仅未删除的记录可选变量值如仅服务日期晚于当前表单订单日期的记录可选关系字段联动通过引用当前表单中另一个关系字段的取值实现字段之间的级联约束。在级联选择中数据范围与懒加载请求的衔接点在 handleGetOptionsconst handleGetOptions async (filter) { const response await resource.list({ pageSize: 200, params: service?.params, filter: mergeFilter([filter, service?.params?.filter]), tree: !filter.parentId ? true : undefined, }); return response?.data?.data; };这里可以读出几个实现细节数据范围由useServiceOptions解析为service.params含filter等最终通过mergeFilter与层级过滤条件parentId合并两者是且的关系pageSize固定为 200即单层级最多展示 200 个直接子节点超出部分不会全部加载需要配合搜索缩小范围首次打开无parentId过滤时会带上tree: true参数请求目标表后续层级则只按parentId拉取子集。工作原理小结逐级懒加载的交互链路结合源码级联选择的完整交互链路如下打开第一级下拉onDropdownVisibleChange请求目标表根级数据tree: true 数据范围过滤渲染选项选中某一级选项handleSelect截断该级之后的所有后续选择立即按parentId请求下一级子节点若有子节点则追加一个新的下拉框同时通过onChange把归一化后的值写回表单重新展开已选的中间级同样按该级的id重新拉取子级支持用户改选上层节点后自动清理下层输入搜索在当前层级范围内按标题字段做服务端模糊匹配。这种选到哪级、加载到哪级的懒加载设计使得即便树表数据量很大如完整的行政区域、深层组织树组件也始终只请求当前可见层级的数据而不是一次性拉取整棵树。适用前提与注意事项目标表必须为树表collection 模板为tree非树表的关系字段不会出现该组件选项对一m2o为单选表单值是最深选中的那条记录对多o2m/m2m为多选每条级联链贡献一条记录可在组件内拖动排序、增删单层级下拉最多加载200条直接子节点数据更深的检索建议依赖标题字段模糊搜索数据范围在树表上按子记录命中则父记录可见的语义生效配置联动条件时可利用这一特性。如果你还需要在树表上以弹窗精挑数据可改用数据选择器Picker需要就地维护关系表字段时则更适合子表单SubForm。各组件的完整对比见 关系字段组件。【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
NocoBase 级联选择字段树表数据的多级联动选择实现与配置详解【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase级联选择CascadeSelect是 NocoBase 界面搭建中专门面向树表关系字段的高级组件它以逐级联动的下拉框形态呈现树形数据让用户像选择省 → 市 → 区一样快速完成深层级数据的选取。本文基于官方文档与前端源码讲清它的适用前提目标表必须为树表、单选/多选的取值差异、标题字段与数据范围两大配置项并深入解析其懒加载、模糊搜索与值归一化的底层实现。适用场景与组件定位根据 级联选择文档 的定义级联选择器适用于目标表为树表的关系字段用户可以按照树表的层级结构选取数据并支持对数据的模糊搜索。它在关系字段组件家族中处于什么位置从 关系字段组件文档 可以看到NocoBase 的关系字段默认以下拉选择器呈现另有数据选择器Picker子表单SubForm子表格SubTable子详情Nester文件管理器FileManager标题ReadPretty等多种形态。级联选择是其中唯一按层级逐级展开的编辑态组件。从源码结构看这一仅限树表的限制在组件模式选项中得到了印证。useFieldModeOptions 中明确写道if (collection?.template tree [m2m, o2m, m2o].includes(collectionField.interface)) { return isReadPretty ? [ /* 阅读态标题 / 标签 / 子详情 / 子表格 */ ] : [ { label: t(Select), value: Select }, { label: t(Record picker), value: Picker }, !isTableField [m2m, o2m].includes(collectionField.interface) { label: t(Sub-table), value: SubTable }, !isTableField { label: t(Cascader Select), value: CascadeSelect }, !isTableField { label: t(Sub-form), value: Nester }, { label: t(Sub-form(Popover)), value: PopoverNester }, ]; }也就是说只有当关系字段的目标数据表模板为tree且接口类型为m2o多对一/对一、o2m一对多/对多或m2m多对多时字段设置中才会出现级联选择Cascader Select这一选项。这是使用该组件的第一个硬性前提。使用说明对一为单选对多为多选文档中给出了两种核心使用形态关系为对一m2o级联为单选字段最终值就是链路上选中的那条记录本身关系为对多o2m/m2m级联为多选用户可以添加多条级联选择链每条链独立选择一条层级路径整体构成多选结果。这与源码中的分支逻辑完全一致。InternalCascadeSelect.tsx 在渲染时按关系接口做了分流FormProvider form{selectForm} {collectionField.interface m2o ? ( SchemaComponent components{{ FormItem }} schema{{ ...fieldSchema, x-component: AssociationCascadeSelect, x-component-props: { ...props }, }} / ) : ( SchemaField schema{schema} / )} /FormProviderm2o分支直接渲染单个AssociationCascadeSelect一次只能选一条链其他分支o2m/m2m渲染的是select_array数组 schema——内部基于 Formily 的ArrayItems实现包含ArrayItems.SortHandle拖动排序、级联选择器本身、ArrayItems.Remove移除以及ArrayItems.Addition添加按钮从而形成多条级联链 可排序可增删的多选结构。值的归一化表单里存的不是路径数组一个容易踩坑的点级联控件内部用选中路径数组每一级的{ key, value, children }来驱动 UI但最终写入表单的值并非这个路径。源码中的normalizeToOneCascadeValue与extractLastNonNullValueObjectsInternalCascadeSelect.tsx#L459-L502会沿路径回溯只提取最后一个非空选中项function normalizeToOneCascadeValue(value) { if (!Array.isArray(value)) { return value; } const result extractLastNonNullValueObjects(value); return Array.isArray(result) result.length 0 ? null : result; }这意味着对于省 → 市 → 区三级选择若用户选到市就停下表单值只会是市这条记录而不是把省也一并保存。多选场景下则对每条链分别做同样的提取再过滤掉空对象后组成数组。仓库中的测试用例 InternalCascadeSelect.test.tsx 专门验证了这两个关键行为m2o 值同步外部表单设置了一条带parent嵌套的树记录id: 3 → 2 → 1组件会将其展开为逐级回显的三个下拉且transformNestedData负责把parent嵌套结构摊平为逐级选项值保持为记录而非路径数组选择节点 2 后断言form.values.org_m2o_tree满足{ id: 2, parentId: null }而不是数组父级选完后保留下一层级选中 id 为 1 的父节点后会请求parentId: 1的子级数据并渲染出第二个下拉框继续选择后值变为{ id: 2, parentId: 1 }。字段配置项字段设置面板由 cascadeSelectComponentFieldSettings 定义共包含四个设置项export const cascadeSelectComponentFieldSettings new SchemaSettings({ name: fieldSettings:component:CascadeSelect, items: [fieldComponent, titleField, ellipsisSettingsItem, setTheDataScope], });即字段组件切换为下拉选择器、数据选择器等其他模式、标题字段、省略号设置超长文本省略显示、设置数据范围。其中与级联选择行为强相关的核心配置项有两个。标题字段标题字段是选项显示的标签字段。配置位置在字段设置的标题字段选项中它写回到字段 schema 的x-component-props.fieldNames.label上见 cascadeSelectComponentFieldSettings.tsx#L81-L98 的onChange。标题字段在级联选择中有双重作用显示标签每一级下拉中展示给用户的文本模糊搜索入口文档明确指出支持根据标题字段快速检索。从源码看搜索逻辑位于 onSearchconst onSearch async (search, selectedValue) { const serachParam search ? { [fieldNames.label]: { [operator]: search, }, } : {}; // ... const result await handleGetOptions({ ...serachParam, parentId: selectedValue?.key, }); // ... };它把搜索词拼进过滤条件{ [标题字段]: { $includes: 搜索词 } }并叠加parentId约束在当前已选层级的子集内做服务端搜索。默认操作符为$includes模糊包含但若标题字段本身有filterable能力则优先使用该接口定义的第一个过滤操作符InternalCascadeSelect.tsx#L56-L61。因此选择一个文本类字段如名称、编码作为标题字段模糊搜索体验最佳而不同字段类型的标题字段还会影响标签的呈现方式——例如选项字段会渲染为彩色标签Tag日期字段会格式化为YYYY-MM-DD这些逻辑同样封装在mapOptionsToTags中。关于标题字段的作用范围数据表级全局配置 vs 字段级配置、优先级关系更多内容可参考 标题字段。设置数据范围数据范围用于控制树形列表的数据范围且文档特别强调了一个树表特有的行为当子记录符合条件时该父记录也会出现。这与普通表格按行过滤的语义不同——过滤是向父级冒泡的保证层级链路完整。数据范围支持三类条件详见 设置数据范围静态值如仅未删除的记录可选变量值如仅服务日期晚于当前表单订单日期的记录可选关系字段联动通过引用当前表单中另一个关系字段的取值实现字段之间的级联约束。在级联选择中数据范围与懒加载请求的衔接点在 handleGetOptionsconst handleGetOptions async (filter) { const response await resource.list({ pageSize: 200, params: service?.params, filter: mergeFilter([filter, service?.params?.filter]), tree: !filter.parentId ? true : undefined, }); return response?.data?.data; };这里可以读出几个实现细节数据范围由useServiceOptions解析为service.params含filter等最终通过mergeFilter与层级过滤条件parentId合并两者是且的关系pageSize固定为 200即单层级最多展示 200 个直接子节点超出部分不会全部加载需要配合搜索缩小范围首次打开无parentId过滤时会带上tree: true参数请求目标表后续层级则只按parentId拉取子集。工作原理小结逐级懒加载的交互链路结合源码级联选择的完整交互链路如下打开第一级下拉onDropdownVisibleChange请求目标表根级数据tree: true 数据范围过滤渲染选项选中某一级选项handleSelect截断该级之后的所有后续选择立即按parentId请求下一级子节点若有子节点则追加一个新的下拉框同时通过onChange把归一化后的值写回表单重新展开已选的中间级同样按该级的id重新拉取子级支持用户改选上层节点后自动清理下层输入搜索在当前层级范围内按标题字段做服务端模糊匹配。这种选到哪级、加载到哪级的懒加载设计使得即便树表数据量很大如完整的行政区域、深层组织树组件也始终只请求当前可见层级的数据而不是一次性拉取整棵树。适用前提与注意事项目标表必须为树表collection 模板为tree非树表的关系字段不会出现该组件选项对一m2o为单选表单值是最深选中的那条记录对多o2m/m2m为多选每条级联链贡献一条记录可在组件内拖动排序、增删单层级下拉最多加载200条直接子节点数据更深的检索建议依赖标题字段模糊搜索数据范围在树表上按子记录命中则父记录可见的语义生效配置联动条件时可利用这一特性。如果你还需要在树表上以弹窗精挑数据可改用数据选择器Picker需要就地维护关系表字段时则更适合子表单SubForm。各组件的完整对比见 关系字段组件。【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
