treeDataGrid 树形数据网格

基本用法

treeDataGrid 功能基本上与 dataGrid 组件一致。

在视图 XML 中声明式定义 treeDataGrid 的示例：

<data readOnly="true">
    <collection id="departmentsDc"
                class="com.company.onboarding.entity.Department"> (1)
        <fetchPlan extends="_base">
            <property name="hrManager" fetchPlan="_base"/>
            <property name="parentDepartment" fetchPlan="_base"/>
        </fetchPlan>
        <loader id="departmentsDl">
            <query>
                <![CDATA[select e from Department e]]>
            </query>
        </loader>
    </collection>
</data>
<layout>
            <treeDataGrid
                          hierarchyProperty="parentDepartment"
                          width="100%"
                          minHeight="20em"
                          dataContainer="departmentsDc"> (2)
                <columns> (3)
                    <column property="name"/>
                    <column property="hrManager"/>
                </columns>
            </treeDataGrid>
</layout>
1 Department 实体的 集合容器。
2 treeDataGrid 通过 dataContainer 属性与 departmentsDc 容器绑定。
3 columns 元素定义在树形网格中展示哪些实体属性。
tree data grid basics

操作

treeDataGrid 组件实现了 HasActions 接口，可以包含标准 列表操作 和自定义操作。操作通过相应的按钮或 右键菜单 调用。

tree data grid actions

如需在 Jmix Studio 中添加 action，可以在视图 XML 或 Jmix UI 结构中选择组件，然后在组件属性面板中点击 Add→Action 按钮。
显示代码 
<hbox id="buttonsPanel" classNames="buttons-panel"> (1)
    <button id="createBtn" action="departmentsTable.create"/>
    <button id="editBtn" action="departmentsTable.edit"/>
    <button id="removeBtn" action="departmentsTable.remove"/>
    <button id="infoBtn" action="departmentsTable.getInfo" icon="INFO_CIRCLE"/>
</hbox>
<treeDataGrid id="departmentsTable"
              hierarchyProperty="parentDepartment"
              width="100%"
              minHeight="20em"
              dataContainer="departmentsDc"> (2)
    <columns>
        <column property="name"/>
        <column property="hrManager"/>
    </columns>
    <actions>
        <action id="create" type="list_create"/>
        <action id="edit" type="list_edit"/>
        <action id="remove" type="list_remove"/>
        <action id="getInfo" text="Get Info"/> (3)
    </actions>
</treeDataGrid>
1 定义一个 hbox 包含操作按钮。
2 定义 list_create 标准操作。
3 定义 getInfo 自定义操作。其 text 属性的值用于在右键菜单中显示该操作，并作为按钮的标题。

右键菜单

右键菜单提供了另一种访问 操作 的方式。每个操作显示为一个菜单项。

使用 contextMenu 元素可以优化菜单项列表，使用分隔符或层次结构进行组织。

tree data grid context menu
显示代码 
<treeDataGrid id="treeDataGrid"
              hierarchyProperty="parentDepartment"
              width="100%"
              minHeight="20em"
              dataContainer="departmentsDc">
    <columns>
        <column property="name"/>
        <column property="hrManager"/>
    </columns>
    <actions showInContextMenuEnabled="false"> (1)
        <action id="create" type="list_create"/>
        <action id="edit" type="list_edit"/>
        <action id="remove" type="list_remove"/>
        <action id="getInfo" text="Get Info"/>
        <action id="viewCalendar" text="Calendar"/>
    </actions>
    <contextMenu>
        <item action="treeDataGrid.create"/> (2)
        <item action="treeDataGrid.edit"/>
        <item action="treeDataGrid.remove"/>
        <separator/>
        <item text="More"> (3)
            <item action="treeDataGrid.getInfo" icon="INFO_CIRCLE"/>
            <item action="treeDataGrid.viewCalendar" icon="CALENDAR"/>
        </item>
    </contextMenu>
</treeDataGrid>
1 隐藏菜单中所有的操作。或者使用 visible 属性隐藏特定操作。
2 为需要的操作显式添加菜单项。
3 菜单项互相包含以创建层级结构。

XML 属性

在 Jmix 中，所有组件都有一些作用一致的 通用属性。 下面是 treeDataGrid 的特殊属性：

名称

描述

默认值

allRowsVisible

如果设置为 true，表格会一次显示所有的行，不带滚动条。也就是说，此时不会仅显示那些可见行，等用户滚动到底部才加载更多数据，而是会直接在 DOM 中同时渲染所有的数据。

如果有大量数据，会有性能问题，此时不推荐使用该功能。

false

columnReorderingAllowed

如果设置为 true，则用户可以修改表格列的顺序。

false

detailsVisibleOnClick

如果设置为 true，当用户点击特定行时，显示 条目详情。

true

dropMode

设置行的拖放模式。支持 BETWEEN、ON_TOP、ON_TOP_OR_BETWEEN、ON_GRID。该功能可用于行的顺序调整或在不同表格之间拖放数据。

-

editorBuffered

如果设置为 true，则启用缓存模式的 行内编辑，只有当用户点击保存按钮时才会提交改动。该模式下用户也可以取消修改。在非缓存模式时，改动会自动提交。

false

hierarchyProperty

定义引用自身实体属性的名称，即树形结构的键值属性。

-

multiSort

如果设置为 true，则启用多列排序。

false

multiSortOnShiftClickOnly

如果设置为 true，仅当按住 Shift 键并单击列标题时，才会激活多列排序。

false

multiSortPriority

设置点击的列添加到排序列中的位置。支持 PREPEND、APPEND。

PREPEND

nestedNullBehavior

设置解析可能包含 null 值的内部属性时的行为。支持 THROW、ALLOW_NULLS。

THROW

pageSize

设置每页展示的行数，这个数值也是每次从数据提供器中获取的数量。

50

rowDraggable

如果设置为 true，启用表格的行拖放功能。

false

selectionMode

设置选择模式。支持 SINGLE 和 MULTI。

SINGLE

showOrphans

如果设置为 false，则组件不会显示孤立记录。如果为 true，孤立记录会作为树的顶层根节点展示。

孤立记录是指不存在的父记录的子记录。通常这是由于过滤或分页，导致从数据库中仅加载了部分数据造成的。在使用过滤器时，隐藏孤立记录更符合人们的习惯。但是，这样会导致分页有问题，某些页可能是空的或者只有一半数据，所以在使用 treeDataGrid 时，最好不要使用 simplePagination 组件。

false

事件和处理器

在 Jmix 中，所有组件都有一些 通用事件和处理器，可以按相同的方法设置。 下面是 treeDataGrid 的特殊事件和处理器：

在 Jmix Studio 生成处理器桩代码时，可以使用 Jmix UI 组件面板的 Handlers 标签页或者视图类顶部面板的 Generate Handler 添加，也可以通过 Code → Generate 菜单（Alt+Insert / Cmd+N）生成。

名称

描述

CellFocusEvent

com.vaadin.flow.component.grid.CellFocusEvent 当数据网格的某个单元格获得焦点时发送。对应 grid-cell-focus DOM 事件。

CollapseEvent

com.vaadin.flow.component.treegrid.CollapseEvent 当节点收起时发送。

ColumnReorderEvent

com.vaadin.flow.component.grid.ColumnReorderEvent 当数据网格的列重排时发送。对应 column-reorder-all-columns DOM 事件。

ColumnResizeEvent

com.vaadin.flow.component.grid.ColumnResizeEvent 当用户改变数据网格列大小时发送。对应 column-drag-resize DOM 事件。

ExpandEvent

com.vaadin.flow.component.treegrid.ExpandEvent 当节点展开时发送。

GridDragEndEvent

com.vaadin.flow.component.grid.dnd.GridDragEndEvent 当数据网格的行拖放结束时发送。对应 grid-dragend DOM 事件。

GridDragStartEvent

com.vaadin.flow.component.grid.dnd.GridDragStartEvent 当数据网格的行拖放开始时发送。对应 grid-dragstart DOM 事件。

GridDropEvent

com.vaadin.flow.component.grid.dnd.GridDropEvent 当拖放至数据网格或数据行时发送。对应 grid-drop DOM 事件。

ItemClickEvent

com.vaadin.flow.component.grid.ItemClickEvent 当点击数据网格条目时发送。对应 item-click DOM 事件。

ItemDoubleClickEvent

com.vaadin.flow.component.grid.ItemDoubleClickEvent 当双击数据网格条目时发送。对应 item-double-click DOM 事件。

SortEvent

com.vaadin.flow.data.event.SortEvent 描述 DataProvider 中排序变化的事件。由 SortNotifiers 触发。

dataGenerator

为数据网格添加数据生成器。如果已经添加，则不做操作。参考 com.vaadin.flow.data.provider.HasDataGenerators 接口。

dragFilter

用于控制特定行是否可拖放，而不是通过 rowDraggable 设置所有行的拖放。

dropFilter

用于设置哪些行可以作为拖放的目的地。

enterPressHandler

用户按下回车键的处理器。

partNameGenerator

按照条件为单元格生成 CSS 类的 part。可以根据数据自定义单元格的外观。

tooltipGenerator

按照给定条件为列单元格生成提示窗。参考 在线示例。

XML 内部元素

dataGrid 的 XML 内部元素提供很多选项来控制列的外观、行为和功能，既可以集中控制列，也可以单独控制列的功能。

如需为选择的组件添加内部元素，可以使用 Jmix UI 组件属性面板中的 Add 按钮添加。

columns

columns 元素可以设置一组需要展示的属性，并设置所有列的行为。

XML 元素

columns

属性

exclude - includeAll - resizable - sortable

XML 内部元素

column
Table 1. 属性

名称

描述

默认值

exclude

排除特定的属性卡不予展示。多个属性需要使用逗号分隔。示例：exclude = "id, version, sortValue"。

-

includeAll

如果为 true，则包含数据容器 fetch plan 中的所有属性。

-

resizable

如果设置为 true，所有列都支持用户改变宽度。

false

sortable

如果设置为 true，所有列都支持排序。

true

column

column 元素定义一个单独的列。为单独列设置的属性会覆盖为所有列设置的属性。

XML 元素

column

属性

autowidth - editable - filterable - flexGrow - footer - frozen - header - key - property - resizable - sortable - textAlign - visible - width

事件和处理器

AttachEvent - DataGridColumnVisibilityChangedEvent - DetachEvent - partNameGenerator - renderer - tooltipGenerator

XML 内部元素

Aggregation - LocalDateRenderer - LocalDateTimeRenderer - NumberRenderer
Table 2. 属性

名称

描述

默认值

autoWidth

如果设置为 true，列宽根据内容自动调整。

false

editable

如果设置为 true，列可编辑。参阅 行内编辑。

false

filterable

如果设置为 true，启用该列的过滤。参阅 表头过滤。

false

flexGrow

设置列的 flex grow 比例。当设置为 0 时，列宽固定。

0

footer

为列设置一个 footer 文本。该属性可以是文本本身或者 消息包 中的一个键值。如果是消息包键值，则必须以 msg:// 开头。

-

frozen

如果设置为 true，则锁住该列。用户在水平滚动表格时会一直显示锁住的列。建议从左至右依次锁定列。

false

header

为列设置一个 header 文本。该属性可以是文本本身或者 消息包 中的一个键值。如果是消息包键值，则必须以 msg:// 开头。

-

key

设置用户定义的列映射 id。这个键值可以用来通过 getColumnByKey(String) 方法获取该列。

键值必须在同一个数据网格中唯一，设定后不能更改。

-

property

指定列中需要显示的实体属性。可以是根实体的属性 property = "user"，也可以是子实体的属性 property = "user.department.name"（并通过 “.” 变量对象图）。

-

resizable

如果设置为 true，用户可以手动调整列宽。

false

sortable

如果设置为 true，列可排序。

false

textAlign

设置文本的对其方式，支持 START、CENTER、END。参考文本对齐。

START

visible

如果设置为 true，则列可见。

true

width

用 CSS 字符串设置列宽。

-
Table 3. 事件和处理器

名称

描述

DataGridColumnVisibilityChangedEvent

通过 gridColumnVisibility 列可见性 组件修改列可见性时发送。

partNameGenerator

按照给定条件为列生成 CSS 类的 part。此功能可以根据展示的数据修改单元格的外观。参考 在线示例。

renderer

使用文本或组件选人列内容。参阅 文本渲染器 和 组件渲染器。

tooltipGenerator

按照给定条件为列生成提示窗。参考 在线示例。

contextMenu

contextMenu 元素可以使用与其默认排列方式不同的方式组织右键菜单的条目。请参阅 示例。

XML 元素

contextMenu

属性

id - classNames - css - enabled - visible

事件和处理器

AttachEvent - DetachEvent - GridContextMenuOpenedEvent - openedChangeEvent - dynamicContentHandler

XML 内部元素

item - separator
Table 4. 事件和处理器

名称

描述

GridContextMenuOpenedEvent

当右键菜单的打开状态变化时触发。可以返回目标菜单项本身或 id，能根据点击事件调整菜单项的展示。

openedChangeEvent

当右键菜单的打开状态变化时触发。

dynamicContentHandler

在菜单打开时处理菜单的动态更新，例如添加菜单项或其内容。请参阅 示例。

参考

Vaadin 文档