Element Plus 虚拟树形组件子节点点击导致勾选框自动勾选问题排查与解决

公众号：小博的前端笔记

🔍 问题描述

近期在使用 Element Plus 的虚拟树形组件（<el-tree-v2>）时，发现点击最后一层叶子节点会触发勾选框自动勾选。这一行为与预期不符（期望仅通过勾选框操作触发选中），且导致父节点联动勾选逻辑异常。

🛠️ 排查过程

1. 版本对比

   • 本地 package.json 声明的 Element Plus 版本为 2.9.3，但实际 package-lock.json 中版本被锁定为 2.9.7（可能因分支合并或依赖升级导致）。

- 经官方文档和源码对比，发现 Element Plus 2.9.6 版本 为虚拟树组件新增了属性 check-on-click-leaf，且该属性默认值为 true。这导致点击叶子节点时自动触发勾选框状态变更。

1. 属性作用分析

   • check-on-click-leaf 是专为虚拟树设计的属性，用于控制是否在点击叶子节点时切换勾选状态（非叶子节点不受影响）。默认开启的设计可能与部分场景冲突。

✅ 解决方案

方案一：关闭自动勾选属性

在 <el-tree-v2> 组件中显式关闭该属性：

<el-tree-v2  
  check-on-click-leaf="false"  
  ...其他配置  
/>  

此修改后，叶子节点点击仅触发 node-click 事件，不再自动勾选。

方案二：固定版本与依赖

1. 还原版本至预期状态：

   bash复制代码

   npm install [email protected] --save-exact  

2. 清理 package-lock.json

   并重装依赖：

   rm -rf package-lock.json node_modules  
   npm install  

💎 总结建议

• 开发环境一致性 ：定期校验 package-lock.json 避免依赖漂移。
• 灵活使用组件属性 ：若需保留高版本特性，通过 check-on-click-leaf="false" 禁用默认行为即可。
• 权威参考 ：Element Plus 官方文档的 TreeV2 属性说明 是核心调试依据。

此问题源于版本升级的属性默认值变化，通过显式配置可快速解决，同时建议团队规范依赖管理流程。