树形表格

树形表格用于以表格格式显示分层数据。

导入#


import { TreeTable } from 'primereact/treetable';
import { Column } from 'primereact/column';

基本用法#

树形表格需要一组 TreeNode 实例作为 value，以及 Column 组件作为子组件进行渲染。带有切换节点元素的列应启用 expander 属性。

名称	大小	类型
没有可用选项


<TreeTable value={nodes} tableStyle={{ minWidth: '50rem' }}>
    <Column field="name" header="Name" expander></Column>
    <Column field="size" header="Size"></Column>
    <Column field="type" header="Type"></Column>
</TreeTable>

动态列#

可以以编程方式创建列。

名称	类型	大小
没有可用选项


<TreeTable value={nodes} tableStyle={{ minWidth: '50rem' }}>
    {columns.map((col, i) => (
        <Column key={col.field} field={col.field} header={col.header} expander={col.expander} />
    ))}
</TreeTable>

受控组件#

展开状态通过 expandedKeys 和 onToggle 属性进行控制。expandedKeys 应该是一个对象，其键引用节点键，值表示展开状态，例如： {'0-0': true}.

名称	大小	类型
没有可用选项


<Button onClick={toggleApplications} label="Toggle Applications" />
<TreeTable value={nodes} expandedKeys={expandedKeys} onToggle={(e) => setExpandedKeys(e.value)} className="mt-4" tableStyle={{ minWidth: '50rem' }}>
    <Column field="name" header="Name" expander></Column>
    <Column field="size" header="Size"></Column>
    <Column field="type" header="Type"></Column>
</TreeTable>

模板#

通过模板支持 header、body 和 footer 部分的自定义内容。可以使用 togglerTemplate 属性自定义切换器。

文件查看器

名称	大小	类型
没有可用选项


<TreeTable value={nodes} header={header} footer={footer} togglerTemplate={togglerTemplate} tableStyle={{ minWidth: '50rem' }}>
    <Column field="name" header="Name" expander></Column>
    <Column field="size" header="Size"></Column>
    <Column field="type" header="Type"></Column>
    <Column body={actionTemplate} headerClassName="w-10rem" />
</TreeTable>

分页器#

基本用法#

通过添加 paginator 属性并定义每页 rows 来启用分页。

名称	大小	类型
没有可用选项


<TreeTable value={nodes} paginator rows={5} rowsPerPageOptions={[5, 10, 25]} tableStyle={{ minWidth: '50rem' }}>
    <Column field="name" header="Name" expander></Column>
    <Column field="size" header="Size"></Column>
    <Column field="type" header="Type"></Column>
</TreeTable>

模板#

可以使用 paginatorTemplate 属性自定义分页器 UI。每个元素还可以使用您自己的 UI 进行进一步自定义以替换默认 UI，有关高级自定义选项的更多信息，请参阅 Paginator 组件。

名称	大小	类型
没有可用选项

0 到 0，共 0 条


<TreeTable value={nodes} paginator rows={5} rowsPerPageOptions={[5, 10, 25, 50]}
        paginatorTemplate="RowsPerPageDropdown FirstPageLink PrevPageLink CurrentPageReport NextPageLink LastPageLink"
        currentPageReportTemplate="{first} to {last} of {totalRecords}"
        paginatorLeft={paginatorLeft} paginatorRight={paginatorRight} tableStyle={{ minWidth: '50rem' }}>
    <Column field="name" header="Name" expander></Column>
    <Column field="size" header="Size"></Column>
    <Column field="type" header="Type"></Column>
</TreeTable>

排序#

单列排序#

通过添加 sortable 属性启用列排序。

名称	大小	类型
没有可用选项


<TreeTable value={nodes} tableStyle={{ minWidth: '50rem' }}>
    <Column field="name" header="Name" expander sortable></Column>
    <Column field="size" header="Size" sortable></Column>
    <Column field="type" header="Type" sortable></Column>
</TreeTable>

多列排序#

可以通过将 sortMode 定义为 multiple 来对多列进行排序。此模式需要在单击标题时按下 metaKey (例如，⌘)。

名称	大小	类型
没有可用选项


<TreeTable value={nodes} sortMode="multiple" tableStyle={{ minWidth: '50rem' }}>
    <Column field="name" header="Name" expander sortable></Column>
    <Column field="size" header="Size" sortable></Column>
    <Column field="type" header="Type" sortable></Column>
</TreeTable>

筛选#

通过向列添加 filter 属性启用筛选。filterMode 指定筛选策略，在 lenient 模式下，当查询匹配一个节点时，不会进一步搜索该节点的子节点，因为该节点的所有后代都包含在内。另一方面，在 strict 模式下，当查询匹配一个节点时，会在所有后代上继续筛选。还提供了一个名为 globalFilter 的通用填充，用于搜索所有支持筛选的列。

宽松模式

严格模式

名称	大小	类型

没有可用选项


<SelectButton value={filterMode} onChange={(e) => setFilterMode(e.value)} options={filterOptions} />

<TreeTable value={nodes} globalFilter={globalFilter} header={header} filterMode={filterMode} tableStyle={{ minWidth: '50rem' }}>
    <Column field="name" header="Name" expander filter filterPlaceholder="Filter by name"></Column>
    <Column field="size" header="Size" filter filterPlaceholder="Filter by size"></Column>
    <Column field="type" header="Type" filter filterPlaceholder="Filter by type"></Column>
</TreeTable>

选择#

单选#

通过将 selectionMode 设置为 single，以及 selectionKeys 和 onSelectionChange 属性来管理选择值绑定，配置单节点选择。

默认情况下，需要按下 metaKey (例如，⌘) 才能取消选择节点，但是可以通过禁用 metaKeySelection 属性来配置此行为。在启用触摸的设备中，此选项无效，并且行为与将其设置为 false 相同。

MetaKey

名称	大小	类型
没有可用选项


<InputSwitch checked={metaKey} onChange={(e) => setMetaKey(e.value)} />

<TreeTable value={nodes} selectionMode="single" selectionKeys={selectedNodeKey}
        onSelectionChange={(e) => setSelectedNodeKey(e.value)} metaKeySelection={metaKey} tableStyle={{ minWidth: '50rem' }}>
    <Column field="name" header="Name" expander></Column>
    <Column field="size" header="Size"></Column>
    <Column field="type" header="Type"></Column>
</TreeTable>

多选#

通过将 selectionMode 设置为 multiple 可以选择多个节点。默认情况下，在多选模式下，需要按下 metaKey (例如，⌘) 才能添加到现有选择中，但是可以通过禁用 metaKeySelection 属性来配置此行为。请注意，在启用触摸的设备中，树形表格始终忽略 metaKey。

在多选模式下，值绑定应该是一个键值对，其中键是节点键，值是一个布尔值，指示是否已选择。


{
    '0-0': true,
    '0-1-0': true
}

MetaKey

名称	大小	类型
没有可用选项


<InputSwitch checked={metaKey} onChange={(e) => setMetaKey(e.value)} />

<TreeTable value={nodes} selectionMode="multiple" selectionKeys={selectedNodeKeys}
        onSelectionChange={(e) => setSelectedNodeKeys(e.value)} metaKeySelection={metaKey} tableStyle={{ minWidth: '50rem' }}>
    <Column field="name" header="Name" expander></Column>
    <Column field="size" header="Size"></Column>
    <Column field="type" header="Type"></Column>
</TreeTable>

复选框#

通过将 selectionMode 配置为 checkbox，可以通过复选框选择多个节点。

在复选框选择模式下，值绑定应该是一个键值对，其中键是节点键，值是一个具有 checked 和 partialChecked 属性的对象，用于表示节点的选中状态。


{
    '0-0': {
        partialChecked: false,
        checked: true
    }
}

名称	大小	类型
没有可用选项


<TreeTable value={nodes} selectionMode="checkbox" selectionKeys={selectedNodeKeys}
        onSelectionChange={(e) => setSelectedNodeKeys(e.value)} tableStyle={{ minWidth: '50rem' }}>
    <Column field="name" header="Name" expander></Column>
    <Column field="size" header="Size"></Column>
    <Column field="type" header="Type"></Column>
</TreeTable>

事件#

树形表格提供 onSelect 和 onUnselect 事件来监听选择事件。

名称	大小	类型
没有可用选项


<TreeTable value={nodes} selectionMode="single" selectionKeys={selectedNodeKey}
        onSelectionChange={(e) => setSelectedNodeKey(e.value)} metaKeySelection={false}
        onSelect={onSelect} onUnselect={onUnselect} tableStyle={{ minWidth: '50rem' }}>
    <Column field="name" header="Name" expander></Column>
    <Column field="size" header="Size"></Column>
    <Column field="type" header="Type"></Column>
</TreeTable>

列组#

可以使用 Row 组件对列进行分组，并且可以使用 headerColumnGroup、footerColumnGroup 属性在标题和页脚处显示组。要跨越的单元格数和行数使用列的 colSpan 和 rowSpan 属性定义。

品牌	销售率
	销售额		利润
	去年	今年	去年	今年
总计			$506,202	$531,020
幸福	51%	40%	$54,406.00	$43,342
命运	83%	96%	$423,132	$312,122
红宝石	38%	5%	$12,321	$8,500
天空	49%	22%	$745,232	$650,323
舒适	17%	79%	$643,242	500,332
优点	52%	65%	$421,132	$150,005
紫罗兰	82%	12%	$131,211	$100,214
甜蜜	44%	45%	$66,442	$53,322
安慰	90%	56%	$765,442	$296,232
本质	75%	54%	$21,212	$12,533


<TreeTable value={nodes} headerColumnGroup={headerGroup} footerColumnGroup={footerGroup} tableStyle={{ minWidth: '50rem' }}>
    <Column field="brand" expander />
    <Column field="lastYearSale" />
    <Column field="thisYearSale" />
    <Column field="lastYearProfit" />
    <Column field="thisYearProfit" />
</TreeTable>

懒加载#

懒加载模式非常适合处理大型数据集。它不会加载整个数据，而是在每次发生分页、排序和过滤时，通过调用相应的回调来加载小块数据。下面的示例模拟了使用内存列表和超时来模拟网络连接，从远程数据源延迟加载数据。

启用 lazy 属性并将逻辑行数分配给 totalRecords（通过执行投影查询）是实现的关键要素，这样分页器会显示 UI，假设存在 totalRecords 大小的记录，尽管实际上页面上不存在这些记录，只存在当前页面上显示的记录。

此外，应该只加载根元素，子元素可以使用 onExpand 回调按需加载。

名称	大小	类型


<TreeTable value={nodes} lazy paginator totalRecords={totalRecords}
        first={first} rows={rows} onPage={onPage} onExpand={onExpand} loading={loading} tableStyle={{ minWidth: '50rem' }}>
    <Column field="name" header="Name" expander></Column>
    <Column field="size" header="Size"></Column>
    <Column field="type" header="Type"></Column>
</TreeTable>

编辑#

通过使用列的 editor 属性定义输入元素来启用单元格内编辑。

名称	大小	类型
没有可用选项


<TreeTable value={nodes} tableStyle={{ minWidth: '50rem' }}>
    <Column field="name" header="Name" expander style={{ height: '3.5rem' }}></Column>
    <Column field="size" header="Size" editor={sizeEditor} cellEditValidator={requiredValidator} style={{ height: '3.5rem' }}></Column>
    <Column field="type" header="Type" editor={typeEditor} style={{ height: '3.5rem' }}></Column>
</TreeTable>

滚动#

垂直滚动#

添加 scrollable 属性以及数据视口的 scrollHeight 可以启用带有固定表头的垂直滚动。

名称	大小	类型

没有可用选项


<TreeTable value={nodes} scrollable scrollHeight="200px">
    <Column field="name" header="Name" expander></Column>
    <Column field="size" header="Size"></Column>
    <Column field="type" header="Type"></Column>
</TreeTable>

水平滚动#

当列的总宽度超过表格宽度时，会启用水平滚动。

名称	大小	类型 2	大小 2	类型 3	大小 3

没有可用选项


<TreeTable value={nodes} scrollable scrollHeight="200px">
    <Column field="name" header="Name" expander style={{ width: '250px' }}></Column>
    <Column field="size" header="Size" style={{ width: '250px' }}></Column>
    <Column field="type" header="Type 2" style={{ width: '250px' }}></Column>
    <Column field="size" header="Size 2" style={{ width: '250px' }}></Column>
    <Column field="type" header="Type 3" style={{ width: '250px' }}></Column>
    <Column field="size" header="Size 3" style={{ width: '250px' }}></Column>
</TreeTable>

冻结列#

可以通过启用列上的 frozen 属性，在水平滚动期间固定列。位置由 alignFrozen 定义，可以是 left 或 right。

名称

没有可用选项

大小	类型	大小	类型	大小	类型

没有可用选项


<TreeTable value={nodes} scrollable frozenWidth="200px" scrollHeight="250px">
    <Column field="name" header="Name" expander frozen style={{ width: '250px', height: '57px' }}></Column>
    <Column field="size" header="Size" style={{ width: '250px', height: '57px' }} columnKey="size_0"></Column>
    <Column field="type" header="Type" style={{ width: '250px', height: '57px' }} columnKey="type_0"></Column>
    <Column field="size" header="Size" style={{ width: '250px', height: '57px' }} columnKey="size_1"></Column>
    <Column field="type" header="Type" style={{ width: '250px', height: '57px' }} columnKey="type_1"></Column>
    <Column field="size" header="Size" style={{ width: '250px', height: '57px' }} columnKey="size_2"></Column>
    <Column field="type" header="Type" style={{ width: '250px', height: '57px' }} columnKey="type_2"></Column>
</TreeTable>

调整列大小#

自适应模式#

当启用 resizableColumns 时，可以使用拖放来调整列的大小。默认的调整大小模式是 fit，它不会改变表格的整体宽度。

名称	大小	类型
没有可用选项


<TreeTable value={nodes} resizableColumns showGridlines tableStyle={{ minWidth: '50rem' }}>
    <Column field="name" header="Name" expander></Column>
    <Column field="size" header="Size"></Column>
    <Column field="type" header="Type"></Column>
</TreeTable>

扩展模式#

将 columnResizeMode 设置为 expand 也会改变表格的宽度。

名称	大小	类型
没有可用选项


<TreeTable value={nodes} resizableColumns showGridlines columnResizeMode="expand" tableStyle={{ minWidth: '50rem' }}>
    <Column field="name" header="Name" expander></Column>
    <Column field="size" header="Size"></Column>
    <Column field="type" header="Type"></Column>
</TreeTable>

重新排序#

当存在 reorderableColumns 时，可以使用拖放来更改列的顺序。

名称	大小	类型
没有可用选项


<TreeTable value={nodes} reorderableColumns tableStyle={{ minWidth: '50rem' }}>
    <Column field="name" header="Name" expander></Column>
    <Column field="size" header="Size"></Column>
    <Column field="type" header="Type"></Column>
</TreeTable>

列切换#

可以基于条件使用动态列实现列的可见性。在此示例中，使用 MultiSelect 来管理可见列。

大小

类型

名称	大小	类型
没有可用选项


<TreeTable value={nodes} header={header} tableStyle={{ minWidth: '50rem' }}>
    <Column key="name" field="name" header="Name" expander />
    {visibleColumns.map((col) => (
        <Column key={col.field} field={col.field} header={col.header} />
    ))}
</TreeTable>

条件样式#

可以基于条件设置特定行和单元格的样式。rowClassName 接收行数据作为参数，以返回行的样式类，而单元格使用 body 模板进行自定义。

名称	大小	类型
没有可用选项


<TreeTable value={nodes} rowClassName={rowClassName} tableStyle={{ minWidth: '50rem' }}>
    <Column field="name" header="Name" expander></Column>
    <Column field="size" header="Size" body={sizeTemplate}></Column>
    <Column field="type" header="Type"></Column>
</TreeTable>

上下文菜单#

TreeTable 使用 onContextMenu 事件与上下文菜单进行独占集成，以便在右键单击时打开菜单，同时使用 contextMenuSelection 和 onContextMenuSelectionChange 属性来控制通过菜单的选择。

名称	大小	类型
没有可用选项


<ContextMenu model={menu} ref={cm} onHide={() => setSelectedNodeKey(null)} />
<TreeTable value={nodes} expandedKeys={expandedKeys} onToggle={(e) => setExpandedKeys(e.value)} contextMenuSelectionKey={selectedNodeKey}
    onContextMenuSelectionChange={(event) => setSelectedNodeKey(event.value)} onContextMenu={(event) => cm.current.show(event.originalEvent)} tableStyle={{ minWidth: '50rem' }}>
    <Column field="name" header="Name" expander></Column>
    <Column field="size" header="Size"></Column>
    <Column field="type" header="Type"></Column>
</TreeTable>

有状态#

有状态表允许将状态（如页面、排序和过滤）保留在本地存储或会话存储中，以便再次访问页面时，表将使用上次的设置渲染数据。

更改表格的状态，例如分页或展开行，离开并返回此表格以测试此功能。使用 stateStorage 属性将设置设置为 session，以便表格在浏览器关闭之前保留状态。另一个选择是 local，它指的是 localStorage 以获得更长的生命周期。

名称	大小	类型

没有可用选项


<TreeTable value={nodes} stateKey={'tree-table-state-demo-session'} stateStorage={'session'}>
    <Column field="name" header="Name" expander filter filterPlaceholder="Filter by name"></Column>
    <Column field="size" header="Size" filter filterPlaceholder="Filter by size"></Column>
    <Column field="type" header="Type" filter filterPlaceholder="Filter by type"></Column>
</TreeTable>

可访问性#

屏幕阅读器

TreeTable 使用 treegrid 元素，可以使用 tableProps 选项扩展其属性。此属性允许传递 aria 角色和属性（如 aria-label 和 aria-describedby）来为阅读器定义表格。表格的默认角色是 table。表头、表体和表尾元素使用 rowgroup，行使用 row 角色，表头单元格具有 columnheader，表体单元格使用 cell 角色。可排序的表头使用 aria-sort 属性，设置为 "ascending" 或 "descending"。

行元素管理 aria-expanded 的状态以及 aria-posinset、aria-setsize 和 aria-level 属性以定义层次结构。

启用选择后，将在行上将 aria-selected 设置为 true。在复选框模式下，内置的复选框组件使用 checkbox 角色和 aria-checked 状态属性。

可编辑单元格使用自定义模板，因此如果需要，您需要手动管理 aria 角色和属性。

分页器是 TreeTable 内部使用的独立组件，有关可访问性功能的更多信息，请参阅分页器。

可排序的表头键盘支持

按键	功能
tab	在表头之间移动。
enter	对列进行排序。
space	对列进行排序。

键盘支持

按键	功能
tab	当焦点进入组件时，将焦点移动到第一个选定的节点，如果没有，则第一个元素接收焦点。如果焦点已在组件内部，则将焦点移动到页面 tab 顺序中的下一个可聚焦元素。
shift + tab	当焦点进入组件时，将焦点移动到最后一个选定的节点，如果没有，则第一个元素接收焦点。如果焦点已在组件内部，则将焦点移动到页面 tab 顺序中的上一个可聚焦元素。
enter	选择聚焦的 treenode。
space	选择聚焦的 treenode。
向下箭头	将焦点移动到下一个 treenode。
向上箭头	将焦点移动到上一个 treenode。
向右箭头	如果节点已关闭，则打开节点，否则将焦点移动到第一个子节点。
向左箭头	如果节点已打开，则关闭节点，否则将焦点移动到父节点。