前端UI组件【免费下载链接】rsuite A suite of React components .项目地址https://gitcode.com/gh_mirrors/rs/rsuite点击查看免费下载本文围绕 RSuite 中多级联动多选组件 MultiCascader 的“不可选状态”能力展开如何通过uncheckableItemValues让树中的特定节点只展示、不可勾选如何与cascade级联勾选、renderValue自定义展示等机制协同工作。读完本文你将掌握该属性的完整语义、数据结构约定、底层实现原理以及可复制的完整示例代码与验证测试用例。一、什么是“不可选状态”在 RSuite 的多级多选组件中一个树节点可以处于三种“交互受限”的状态之一可正常勾选默认状态节点复选框可自由选中/取消禁用disabled通过disabledItemValues指定节点呈灰色不可交互也不可被任何级联操作影响不可选uncheckable通过uncheckableItemValues指定节点的复选框被移除只作为纯展示项存在用户无法直接勾选它。uncheckableItemValues在官方 Props 表中的定义是“设置无法勾选的选项值”类型为字符串数组string[]用于声明一组“不允许被勾选”的节点 value。与disabledItemValues最核心的区别在于不可选节点依然参与父子级联关系的计算只是它本身不能作为勾选对象被用户点选详见后文源码分析。该属性同时存在于 MultiCascader 及其底层无浮层版本 MultiCascadeTree 中二者共享同一套级联值计算逻辑。二、完整示例让指定节点只读展示官方文档docs/pages/components/multi-cascader/fragments/uncheckable.md给出了一个最小可运行的示例本文完整继承并补充注释import { MultiCascader, Button } from rsuite; import { mockTreeData } from ./mock; // 生成一个 3 层树第一层 3 个节点、第二层每节点 3 个、第三层每节点 4 个 const data mockTreeData({ limits: [3, 3, 4], labels: (layer, value, faker) { const methodName [jobArea, jobType, firstName]; return faker.person[methodName[layer]](); } }); const App () ( MultiCascader data{data} block renderValue{(value, selectedItems) selectedItems.map(item item.label).join( , )} uncheckableItemValues{[1, 2, 2-1]} / / ); ReactDOM.render(App /, document.getElementById(root));在这个示例中data由mockTreeData生成节点value按“父 value - 序号”规则自动编号uncheckableItemValues{[1, 2, 2-1]}声明了 3 个不可勾选节点第一层的1、2以及第二层中属于2的子节点2-1block让选择器占满整行renderValue将已选节点的label用逗号拼接显示方便直观看到选中结果。mockTreeData 生成的数据结构mockTreeData是文档示例与测试共用的数据生成器实现位于 docs/utils/mock.ts。其核心逻辑是按limits数组定义每层节点数量递归生成树节点 value 的命名规则为第一层节点1、2、3……从 1 开始的自增字符串第二层节点父 value - 序号如2-1、2-2第三层节点2-1-1、2-1-2……依次类推。因此示例中的1、2指第一层两个父节点2-1指2的第二个层级子节点。在测试文件中数据则由 test/mocks/data-mock.ts 提供的mockTreeData([1, 2, [3, 3-1, 3-2]])形式构造语义完全一致。三、底层原理一节点渲染层的处理在 src/MultiCascadeTree/TreeView.tsx 中每一列树节点渲染前都会先判断节点是否处于不可选状态const uncheckable uncheckableItemValues.some(uncheckableValue shallowEqual(uncheckableValue, item[valueKey]) );判断依据是值相等比较shallowEqual而不是引用相等因此即使传入的对象结构与数据源中的不同只要 value 相等即可命中。随后在渲染节点时checkable{!uncheckable}当uncheckable为true时节点的复选框不再渲染checkable{false}节点退化为纯文本展示项用户无法点击勾选。此外TreeView 还会统计每列中不可选节点的数量let uncheckableCount 0; // ...渲染循环中if (uncheckable) { uncheckableCount; } const columnClasses prefix(column, { column-uncheckable: uncheckableCount children.length });当某一列的节点全部不可选时该列会被附加column-uncheckable样式类用于整列弱化展示具体视觉样式由 src/MultiCascadeTree/styles/index.scss 定义。这一细节说明不可选状态不仅是交互限制还内置了对整列不可选场景的样式反馈。在 MultiCascader 的入口组件 src/MultiCascader/MultiCascader.tsx 中uncheckableItemValues默认值为空数组并通过两条链路分别传入一是TreeView级联列展示二是useSearch与useCascadeValue搜索与级联值计算确保下拉弹出层与搜索视图都遵守不可选规则。四、底层原理二级联值计算中的过滤逻辑不可选状态对“父子级联勾选”的影响是本文最值得深入的部分。核心实现位于 src/MultiCascadeTree/hooks/useCascadeValue.ts配合工具函数 src/MultiCascadeTree/utils.ts。1. 遍历子节点时跳过不可选节点当勾选一个父节点时需要把其全部后代子节点一并写入 value。getChildrenValue在递归遍历时会显式跳过不可选节点item[childrenKey].forEach(n { if (uncheckableItemValues !uncheckableItemValues.some(v v n[valueKey])) { values.push(n[valueKey]); } values values.concat(getChildrenValue(n)); });这意味着不可选节点的 value 永远不会因为父节点被勾选而自动进入选中集合它始终停留在“展示但未勾选”的状态。2. 父节点的全选判定过滤不可选子节点splitValue在勾选任意节点后会向上回溯祖先节点判断其所有子节点是否已全部选中若是则祖先节点被自动勾选级联。该判定同样排除了不可选子节点const isCheckAll parents[i][childrenKey] // Filter out options that are marked as not selectable .filter(n !uncheckableItemValues?.some(v v n[valueKey])) // Check if all nodes are selected .every(n nextValue.some(v v n[valueKey]));同时祖先节点自身如果是不可选节点isCheckableParent为false则不会被自动写入 value。这种“忽略不可选节点”的级联策略保证了一个父节点只要其所有可选子节点都被勾选就能呈现为全选状态而不会因为存在不可选子节点而永远无法全选。3. 取消勾选时联动删除反向操作同样受控当取消勾选某个节点时getOtherItemValuesByUnselectChild位于 src/MultiCascadeTree/utils.ts会收集与其相关的父节点与兄弟节点 value一并从选中集合中移除避免残留“孤儿选中值”。4. 关闭级联时的表现当cascade{false}时useCascadeValue走简单的增删分支nextValue.push(nodeValue)/filter不做父子联动此时uncheckableItemValues依然在渲染层生效复选框被移除但不会参与任何自动计算。五、行为验证测试用例中的关键场景组件仓库提供了完整的测试覆盖src/MultiCascader/test/MultiCascader.spec.tsx其中两个用例精确印证了上文所述语义场景一子节点不可选父节点仍可全选render(MultiCascader data{items} value{[3-1]} uncheckableItemValues{[3-2]} /); // 期望 combobox 文本为 3 (All)1items中3的子节点为3-1、3-2其中3-2不可选。当选中3-1后由于唯一的可选子节点已勾选父节点3仍然被判定为全选(All)——不可选子节点不阻碍父节点的级联全选。场景二父节点不可选子节点独立展示render(MultiCascader data{items} value{[3-1, 3-2]} uncheckableItemValues{[3]} /); // 期望 combobox 文本为 3-1,3-22父节点3不可选后选中集合中不再有父节点值已选的子节点3-1、3-2直接以自身 label 展示3-1,3-2计数徽标显示2。这两组测试从渲染结果角度确认了uncheckableItemValues只影响“该节点自身是否可被勾选”不会破坏其余节点间的正常级联关系。六、使用注意事项与相关 Props结合 组件官方 Props 文档 与源码默认值使用时有几点值得注意关注点说明uncheckableItemValues默认值空数组[]即默认所有节点均可勾选见 MultiCascader.tsx 中uncheckableItemValues emptyArray值匹配方式通过shallowEqual与节点valueKey默认value对应字段做值比较传入的 value 必须与数据中的 value 完全一致与disabledItemValues的区别不可选节点仍可被级联逻辑“感知”如父节点全选判定时被过滤禁用节点则彻底退出交互与计算与cascade的配合默认cascadetrue时按上文逻辑联动cascadefalse时仅影响复选框渲染与searchable的配合搜索视图中同样会过滤不可选节点useSearch接收同一份uncheckableItemValues搜索结果不会把不可选节点列为可勾选项自定义节点渲染若使用renderTreeNode自定义节点复选框的移除逻辑依然生效但自定义内容中的交互元素需要自行处理七、总结uncheckableItemValues为 RSuite MultiCascader 提供了一种“看得见、选不了”的节点形态适合用于展示结构信息、说明性分类或由系统预定的固定层级。其实现贯穿三层代码渲染层TreeView.tsx 移除复选框并支持整列弱化样式、状态层useCascadeValue.ts 在级联计算中过滤不可选节点、以及配套的测试用例MultiCascader.spec.tsx验证行为边界。掌握这一属性你就能在多级多选场景下精确控制“哪些层级仅供展示、哪些层级参与选择”。赞分享前端UI组件【免费下载链接】rsuite A suite of React components .项目地址https://gitcode.com/gh_mirrors/rs/rsuite点击查看免费下载相关推荐rsuite CheckTree 不可选择节点uncheckableItemValues实战指南隐藏复选框而不破坏级联选择rsuite CheckTree 不可选择节点uncheckableItemValues实战指南隐藏复选框而不破坏级联选择 本文以 rsuite 的 C前端UI组件Flowable 运维工具箱实战JMX 远程管理与 Maven Archetype 单元测试脚手架Flowable 运维工具箱实战JMX 远程管理与 Maven Archetype 单元测试脚手架 本指南聚焦 Flowable 引擎的两大运维与开发利器前端UI组件rsuite MultiCascader 基础用法实战级联多项选择器从入门到源码级解析rsuite MultiCascader 基础用法实战级联多项选择器从入门到源码级解析 导读 MultiCascader 是 rsuite 中用于 对有层级关前端UI组件上一篇5个超实用的Python翻译库解锁多语言沟通新姿势下一篇X6 画布数据序列化指南graph.toJSON 导出与 graph.fromJSON 导入实战创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考