树 - CUBA 框架开发者手册

3.5.2.1.50. 树

Tree 组件用于将具有自引用关系的实体显示为树状层次结构。

组件的 XML 名称: tree

下面是一个在界面 XML 描述中定义 tree 组件的示例:

<data readOnly="true">
    <collection id="departmentsDc" class="com.company.sales.entity.Department" view="department-view">
        <loader id="departmentsDl">
            <query>
                <![CDATA[select e from sales_Department e]]>
            </query>
        </loader>
    </collection>
</data>
<layout>
    <tree id="departmentsTree" dataContainer="departmentsDc" hierarchyProperty="parentDept"/>
</layout>

这里，dataContainer 属性包含指向集合数据容器的引用，hierarchyProperty 属性定义了一个实体属性的名称，这个属性也指向同一个的实体（从而能形成树）。

使用 treechildren 元素的 captionProperty 属性指定要显示为树节点名称的实体属性的名称，如果这个属性没有定义，将默认显示实体的实例名称。

contentMode 属性定义树节点名称的展示方式。有三种预定义的模式：

TEXT - 文本值直接显示
PREFORMATTED - 文本值以特定格式显示。此时，界面渲染时会保留回车。
HTML - 文本值以 HTML 方式显示。注意，用该模式时需要避免 XSS 问题。

使用 setItemCaptionProvider() 方法可以设置一个函数，用来将实体的属性名称作为标题放到数的每项中。

在 Tree 中进行选择：

multiselect 设置是否允许树节点多选。如果 multiselect 设置为 true，用户可在按住 Ctrl 或 Shift 键的情况下使用键盘或鼠标选择多个节点。多选模式默认关闭。

selectionMode - 设置行选择模式。有三种预定义的选择模式：
- SINGLE - 单一记录选择模式。
- MULTI - 多选模式，跟在表格中多选类似。
- NONE - 禁止选择。
行选择事件可以通过 SelectionListener 监听器进行跟踪。选择事件的发起者可以通过isUserOriginated()方法跟踪。

selectionMode 属性比废弃的 multiselect 属性有更高的优先级。

setItemClickAction() 用于定义一个操作，双击树节点时执行。

每个树节点左边可以定义一个图标。在界面控制器中的 setIconProvider() 方法中创建一个 Function 接口的实现来设置图标：

@Inject
private Tree<Department> tree;

@Subscribe
protected void onInit(InitEvent event) {
    tree.setIconProvider(department -> {
        if (department.getParentDept() == null) {
            return "icons/root.png";
        }
        return "icons/leaf.png";
    });
}

可以用下面的方式在树节点展开或收起时做交互：

@Subscribe("tree")
public void onTreeExpand(Tree.ExpandEvent<Task> event) {
    notifications.create()
            .withCaption("Expanded: " + event.getExpandedItem().getName())
            .show();
}

@Subscribe("tree")
public void onTreeCollapse(Tree.CollapseEvent<Task> event) {
    notifications.create()
            .withCaption("Collapsed: " + event.getCollapsedItem().getName())
            .show();
}

Tree 组件有 DescriptionProvider，因此，在 contentMode 设置为 ContentMode.HTML 时，可以渲染 HTML。如果 htmlSanitizerEnabled 属性设置为 true，该 provider 的执行结果会是清理后安全的 HTML。

htmlSanitizerEnabled 属性会覆盖全局的 cuba.web.htmlSanitizerEnabled 配置。

对于之前的老界面，Tree 组件可以绑定到一个数据源而不是数据容器。这种情况下，需要定义嵌套的 treechildren 元素，这个元素需要包含指向在 datasource 属性定义的 hierarchicalDatasource 的引用。hierarchicalDatasource 的声明需要包含 hierarchyProperty 属性，此属性定义了实体属性的名称，这个属性也指向相同的实体。

tree 的属性: caption - captionAsHtml - captionProperty - contentMode - contextHelpText - contextHelpTextHtmlEnabled - css - dataContainer - description - descriptionAsHtml - enable - box.expandRatio - height - htmlSanitizerEnabled - id - multiselect - showOrphans - stylename - tabIndex - visible - width
tree 的元素: actions - treechildren
treechildren 的属性: captionProperty - datasource
API: addCollapseListener - addExpandListener - setDescriptionProvider - setDetailsGenerator - setItemCaptionProvider