树形控件

# 变更记录 | 产品版本 | 更新内容 | 更新日期 | | --- | --- | --- | | V5.0.021 | 支持了树控件配置父节点是否可勾选的功能，满足根据父节点是否有业务含义来开启勾选的需求 | 2023-05-17 | | V5.0.022 | 新增了树控件更新内容时，支持局部更新保留当前展开收起状态的功能，提升了用户体验 | 2023-06-06 | | V6.0.1 | 支持了树控件点击文字的时候不修改勾选状态的功能，提升了用户使用体验 | 2023-10-27 | | V6.0.2 | 1、树控件节点支持配置图片格式图标，满足用户实现多色图标的场景
2、支持树的展开收起动作通知到后端，方便进行扩展，比如两个树控件支持同步展开收起状态 | 2023-11-28 | | V7.0.1 | 优化了树控件功能，支持节点后配置图标及操作、节点复制、批量勾选、按节点设置背景色，满足用户使用场景，提升用户体验 | 2024-10-24 | # 1 功能介绍 可以完整展现数据层级关系，并具有展开、收起、选择等交互功能。树形控件需要在插件中构造数据。 # 2 控件对象 `kd.bos.form.control.TreeView` # 3 视觉展示  # 4 属性说明 ## 4.1 通用属性 >通用属性包含字段和控件的一些公有的属性，如宽高，帮助文本等等。请参考[通用属性](https://vip.kingdee.com/article/215559076720798976) ## 4.2 样式属性 >样式属性是每个控件在设计器右侧样式栏可以设置的属性，请参考[样式属性](https://vip.kingdee.com/article/252017936767406336) ## 4.3 业务属性 | 属性名 | 属性 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | --- | | 根节点可见 | rv | 复选框 | true | 设置根节点是否可见 | | 多选 | im | 复选框 | false | 设置节点是否允许多选 | | 启用拖拽 | de | 复选框 | false | 设置节点可拖拽 | | 级联全选 | ccn | 复选框 | true | 设置勾选上级节点时，下级节点全选 | | 大数据优化 | bdrender | 复选框 | true | 数据量过大进行优化处理，详见4.3.1 | | 手风琴模式 | accordion | 复选框 | false | 勾选后，目录树同一级只能展开一个控制，详见4.3.2 | | 取消批量勾选 | disableBatchCheck | 复选框 | false | 开启了允许多选的时候，取消批量勾选，仅可选叶子节点，不能选子节点 | | 是否限制勾选生效区域 | restrictCheckEffectiveArea | 复选框 | false | 开启了这个参数，点击文字不自动勾选复选框，限制勾选生效区域 | | 树的展开、收起是否通知后端 | notifyFoldingStatus | 复选框 | false | 默认情况下，树的展开收起是不会通知后端 | ### 4.3.1 大数据优化 数据量过大的时候进行的优化处理，打开此属性，提升树节点大数据渲染性能 ### 4.3.2 手风琴模式 勾选手风琴模式，目录树同一级只能展开一个控制，效果类似手风琴；而普通模式是可以同时展开多个的 普通模式：  手风琴模式：  ### 4.3.3 多选 在开启多选模式时，可以通过长按 Shift 进行批量多选和反选  # 5 树形控件接口示例 ## 5.1 控件编程模型 ### 5.1.1 控件编程模型定义 树形控件的编程模型为TreeVew，派生自控件编程模型基类Control： ```java package kd.bos.form.control; public class CodeEdit extends Control { ``` 插件可以通过如下代码，获取到树形控件的编程模型实例： ```java TreeView treeView = this.getView().getControl(KEY_TREEVIEW1); ``` ### 5.1.2 控件方法清单 树形控件，派生自控件基类，增加了如下方法： | 方法 | 说明 | | --- | --- | | expand | 展开指定节点 | | showNode | 展开当前节点，及其上级节点 | | collapse | 折叠指定节点 | | deleteNode | 移除指定节点 | | deleteNodes | 移除一批节点 | | deleteAllNodes | 移除全部节点 | | updateNode | 刷新节点 | | updateNodes | 刷新一批节点 | | addNode | 添加节点到对应parentId所在节点下面
parentId为空时直接添加到树上作为根节点 | | addNodes | 添加多个节点到对应parentId所在节点下面
parentId为空时直接添加到树上作为根节点 | | checkNode | 勾选节点 | | checkNodes | 勾选一批节点 | | uncheckNode | 取消节点勾选 | | uncheckNodes | 取消一批节点勾选 | | focusNode | 设置焦点 | | setRootVisible | 设置根节点是否可见 | | setMulti | 设置是否支持多选 | | getTreeState | 获取树形控件当前状态，包括焦点节点、已勾选的节点等信息 | | updateNodeProps | 局部更新树节点的属性。id是必传属性、如果id传的是数组支持同时修改多个节点。所有支持局部更新的属性有：节点名称、锁定状态、展开折叠状态、标签信息、图标信息。 | ### 5.1.3 控件方法的使用案例 案例说明： * 动态加载树形控件的节点 * 按层次，分批加载树形控件的节点 * 响应树形节点点击事件，提示用户当前所选择的节点 * 支持多选时，即时获取到勾选的节点 * 可以通过拖拽，改变节点位置 实现方案： * 捕获表单数据绑定事件beforeBindData，加载第一层节点 * 捕获树形控件的节点懒加载事件 queryTreeNodeChildren，加载下层子节点 * 捕获树形节点点击treeNodeClick事件，显示提示消息 * 捕获树形节点勾选事件 treeNodeCheck，显示提示消息 * 捕获树形控件的拖拽事件 treeNodeDragged，修改节点位置 示例代码： ```java package kd.bos.plugin.sample.dynamicform.pcform.control.bizcase; import java.util.ArrayList; import java.util.EventObject; import java.util.List; import kd.bos.dataentity.utils.StringUtils; import kd.bos.entity.tree.TreeNode; import kd.bos.form.control.TreeView; import kd.bos.form.control.TreeView.TreeState; import kd.bos.form.control.events.TreeNodeCheckEvent; import kd.bos.form.control.events.TreeNodeCheckListener; import kd.bos.form.control.events.TreeNodeClickListener; import kd.bos.form.control.events.TreeNodeDragEvent; import kd.bos.form.control.events.TreeNodeDragListener; import kd.bos.form.control.events.TreeNodeEvent; import kd.bos.form.control.events.TreeNodeQueryListener; import kd.bos.form.plugin.AbstractFormPlugin; public class TreeViewSample extends AbstractFormPlugin implements TreeNodeClickListener, TreeNodeCheckListener, TreeNodeQueryListener, TreeNodeDragListener{ private final static String KEY_TREEVIEW1 = "treeviewap1"; /** * 注册控件事件 */ @Override public void registerListener(EventObject e) { super.registerListener(e); TreeView treeView = this.getView().getControl(KEY_TREEVIEW1); // 侦听树节点懒加载事件 treeView.addTreeNodeQueryListener(this); // 侦听树节点点击事件，Click treeView.addTreeNodeClickListener(this); // 侦听树节点勾选事件，Check：特别注意字母拼接差异Check、Click treeView.addTreeNodeCheckListener(this); // 侦听树节点拖拽移动事件 treeView.addTreeNodeDragListener(this); } /** * 界面加载，开始绑定数据事件 */ @Override public void beforeBindData(EventObject e) { super.beforeBindData(e); // 初始化树形控件的属性与第一层节点 TreeView treeView = this.getView().getControl(KEY_TREEVIEW1); treeView.setMulti(true); // 支持多选，不触发节点单击事件treeNodeClick，会触发节点双击事件treeNodeDoubleClick //treeView.setMulti(false); // 不支持多选，不触发复选节点事件 treeNodeCheck TreeNode root = new TreeNode("", "node1", "root node"); root.setChildren(new ArrayList<>()); // 需要懒加载的节点，需setChildren(new ArrayList<>()) treeView.addNode(root); treeView.setRootVisible(true); // 显示根节点 treeView.expand("node1"); // 展开节点 treeView.setDraggable(true); // 允许节点被拖拽 treeView.setDroppable(true); // 允许接收拖拽进的内容 } /** * 节点懒加载事件 * @remark * 节点需要setChildren(new ArrayList<>())，当节点的children存在且isEmpty时，点击展开节点时触发事件 */ @Override public void queryTreeNodeChildren(TreeNodeEvent arg0) { String nodeId = (String)arg0.getNodeId(); List<TreeNode> childNodes = this.loadChildNode(nodeId); TreeView treeView = this.getView().getCo