TanStack Table React 聚合Aggregation完整指南从总计到分组汇总的自定义实现【免费下载链接】table Headless UI for building powerful tables datagrids for TS/JS - React-Table, Vue-Table, Solid-Table, Svelte-Table项目地址: https://gitcode.com/gh_mirrors/ta/table本篇技术指南围绕tanstack/react-table的聚合功能展开系统讲解如何通过rowAggregationFeature注册聚合函数、在列上配置单个或多个聚合、计算总计与自定义行子集汇总、实现分组聚合columnGroupingFeaturegroupedRowModel、编写自定义聚合定义constructAggregationFn以及对接服务端/外部预计算值。读完本文你将掌握在普通表格中直接计算总计、在分组表格中渲染aggregatedCell、以及通过maxDepth精确控制参与聚合的行集合等完整实战能力。前置示例与文档定位本文对应的官方示例位于React Aggregation 示例React Grouped Aggregation 示例两个示例均在examples/react/目录下可直接参考src/main.tsx查看完整可运行代码。聚合Aggregation与列分组Grouping是两个相互独立的能力只要列需要计算总计或聚合值就必须注册rowAggregationFeature只有当表格同时需要把行分组显示时才额外注册columnGroupingFeature。这一独立性是理解后续所有配置的前提。聚合功能的基础设置按需注册 Feature 与聚合函数聚合功能的核心是注册rowAggregationFeature同时把列配置中按名称引用的内置聚合函数注册进aggregationFns注册表。注意只有在列上通过字符串名称引用聚合函数时才需要注册表条目若直接把定义definition传给列则不需要注册。import { rowAggregationFeature, aggregationFn_count, aggregationFn_extent, aggregationFn_mean, aggregationFn_sum, tableFeatures, useTable, } from tanstack/react-table const features tableFeatures({ rowAggregationFeature, aggregationFns: { count: aggregationFn_count, extent: aggregationFn_extent, mean: aggregationFn_mean, sum: aggregationFn_sum, }, }) const table useTable({ features, columns, data, })从源码看rowAggregationFeature在 rowAggregationFeature.ts 中通过getDefaultColumnDef设置了三个默认列选项aggregatedCell默认按值格式化聚合结果、aggregationFn: auto、maxAggregationDepth: 0并通过getDefaultTableOptions将manualAggregation默认置为false。这意味着即便不显式配置聚合相关的基础行为也已就绪。聚合不需要分组行模型聚合功能并不依赖分组行模型grouped row model。这意味着你可以在完全普通的表格上直接得到总计grand totals和自定义行子集的总计例如仅使用createFilteredRowModel、createPaginatedRowModel的表格。官方 Aggregation 示例 就是典型的无分组聚合它同时注册了过滤、分页、行选择等特性却没有注册任何分组相关特性照样在tfoot中渲染各列聚合值。完整注册表与stockFeatures完整的aggregationFns注册表包含全部内置聚合函数仍然可用以保证兼容性但它的缺陷是会把所有内置函数一并打包进 bundle。因此源码注释将其标记为deprecated并建议逐个导入aggregationFn_*定义以获得更好的 tree-shaking 效果见 aggregationFns.ts。另外使用stockFeatures标准特性集的表格已经包含了rowAggregationFeature无需重复注册但列上按名称引用的聚合函数定义仍需要你主动注册到aggregationFns因为stockFeatures并不会替你决定用哪些函数。列上的聚合配置单个聚合与多个聚合一个列可以接受单个聚合函数也可以接受一个聚合函数数组columnHelper.accessor(amount, { aggregationFn: sum, }) columnHelper.accessor(score, { aggregationFn: [count, mean, { id: range, aggregationFn: extent }], })单个聚合返回一个标量值。多个聚合返回一个对象以聚合名称或描述符descriptor的id作为键。字符串值如sum保持向后兼容直接按名称解析注册表中的定义。当结果需要一个稳定的自定义键或需要给聚合传选项时应使用描述符对象形式{ id: range, aggregationFn: extent }。标量与数组的取值规则aggregationFn为标量时可以是已注册的名称、auto或内联定义inline definition。聚合数组中的每一项都需要一个唯一的稳定 id。出现重复 id、缺失描述符 id、引用了未注册的名称时开发环境下会输出警告源码中的warn函数仅在生产环境之外生效见 rowAggregationFeature.utils.ts并将受影响的键以undefined值保留下来避免破坏整体结果结构。读取多聚合结果多个聚合可以结合类型参数读取获得类型安全的键控结果const scoreColumn columnHelper.accessor(score, { aggregationFn: [count, mean, { id: range, aggregationFn: extent }], footer: ({ column }) { const result column.getAggregationValue{ count: number mean: number | undefined range: [number | undefined, number | undefined] }() return ${result.count} values; mean ${result.mean}; range ${result.range} }, })官方示例的score列正是这种用法footer 中通过column.getAggregationValue()拿到{ count, mean, range }结构化结果并格式化展示参见 aggregation/src/main.tsx。总计与行子集Grand Totals Row Subsets默认总计过滤后的预分组行模型不传参数直接调用column.getAggregationValue()会聚合默认的预分组行模型pre-grouped row model。其行为要点是过滤filtering是生效的分组grouping、排序sorting、展开expansion、分页pagination不会改变这个默认总计。footer: ({ column }) column.getAggregationValuenumber().toLocaleString()官方 Grouped Aggregation 示例 中visits列的 footer 即采用该形式输出总计与分组后的aggregatedCell数值相互印证。自定义行子集传入rows通过传入一个选项对象指定任意行模型或自定义行数组作为聚合根集合即可得到不同的总计column.getAggregationValue({ rows: table.getCoreRowModel().rows }) column.getAggregationValue({ rows: table.getRowModel().rows }) column.getAggregationValue({ rows: table.getFilteredSelectedRowModel().rows }) column.getAggregationValue({ rows: table.getCoreRowModel().rows.slice(0, 3) }) column.getAggregationValue({ rows: table.getCoreRowModel().rows, maxDepth: 1 })这些调用方式分别对应全部核心行、当前可见过滤分页后行、已选行、自定义切片如前 3 行、以及带深度限制的核心行。官方示例通过一个下拉菜单在这几种行源之间切换演示了同一列、不同行集合、不同总计的效果见 aggregation/src/main.tsx 与 aggregation/src/main.tsx。深度maxDepth语义深度是相对于传入的行数组而言的0选中传入的根行本身1选中这些根行直接的子行sub-rows依此类推Infinity选中终端行terminal rows即所有叶节点。选择结果是一个唯一的边界unique frontier如果某个分支在到达最大深度之前就结束了则该分支贡献其最深可达的行。这一行为在源码的normalizeAggregationRows/collectNormalizedAggregationRow中实现——遍历时若row.subRows.length depth maxDepth则继续下钻否则把当前行加入结果并用Set按row.id去重见 rowAggregationFeature.utils.ts。maxAggregationDepth配置与缓存列上的maxAggregationDepth用于缓存化的默认调用即不传rows的调用默认值为0。也可以在选项对象中传maxDepth作为显式覆盖。列上配置的每个聚合函数都会收到相同的选中行集合。显式传rows的调用每次都会重新计算而默认调用会以行模型、深度、注册表、列聚合选项为键进行缓存源码AggregationCacheEntry记录aggregationFnOption、dependency、maxDepth、registry、value见 rowAggregationFeature.utils.ts。结合最大子行深度table.getMaxSubRowDepth()返回核心行模型中最深的结构性深度。若要在最深子行边界之前停一层例如想在总计中保留一层分组摘要行、不摊平到所有叶子可以这样计算const maxDepth Math.max(0, table.getMaxSubRowDepth() - 1) column.getAggregationValue({ rows: table.getCoreRowModel().rows, maxDepth, })分组聚合Grouped Aggregation组合两个独立特性分组聚合 聚合特性 分组特性二者独立注册、组合使用。需要同时注册rowAggregationFeature与columnGroupingFeature挂载分组行模型groupedRowModel并在需要产生分组值的列上配置聚合函数const features tableFeatures({ rowAggregationFeature, columnGroupingFeature, groupedRowModel: createGroupedRowModel(), aggregationFns: { sum: aggregationFn_sum }, }) columnHelper.accessor(visits, { aggregationFn: sum, aggregatedCell: ({ getValue }) getValuenumber().toLocaleString(), footer: ({ column }) column.getAggregationValuenumber().toLocaleString(), })官方示例还同时叠加了过滤、排序、展开、分页等特性并用createTableHook封装成useAppTable/createAppColumnHelper使用这不是必需模式但便于复用完整代码见 grouped-aggregation/src/main.tsx。aggregatedCell与cell.getIsAggregated()aggregatedCell列选项负责在合成的分组行上渲染聚合值。使用cell.getIsAggregated()可以判断某个单元格是否为分组的聚合单元格。footer 渲染仍使用适配器adapter自带的普通 footer 渲染器与aggregatedCell互不干扰。注意仅分组不聚合的表格不会暴露cell.getIsAggregated()——该 API 属于rowAggregationFeature。这一点在源码中也很清楚getIsAggregated由 rowAggregationFeature.ts 通过assignCellPrototype注入与分组特性无关。自定义聚合定义Custom Aggregation Definitions基于上下文的constructAggregationFn自定义聚合是基于上下文context的定义。核心上下文包含rows在maxDepth下选中的唯一边界行集合getValue(row)读取当前列在该行上的值。const joined constructAggregationFnany, any, string, string({ aggregate: ({ rows, getValue }) rows .map((row) getValue(row)) .filter(Boolean) .join(, ), })泛型参数依次对应 feature 类型、行数据类型、输入值类型与输出结果类型。上下文还包含column、columnId、maxDepth与table。在分组聚合期间上下文额外包含groupingRow与subRows根级root聚合与调用者提供行caller-supplied rows的聚合则不包含这两个属性源码类型定义见 rowAggregationFeature.types.ts。使用groupingRow与subRows分组深度为groupingRow.depth。subRows包含该分组层级的直接子行因此聚合可以显式选择直接子行而不是用深度选择出的rowsconst subRowCount constructAggregationFnany, any, unknown, number({ aggregate: ({ subRows, rows }) (subRows ?? rows).length, })在最末端分组层级subRows包含直接的数据行在嵌套层级它包含直接的下级合成分组行。所有内置聚合定义都消费同一个深度选出的rowssubRows仅供需要分组行的直接结构子级的自定义定义按需使用。可选merge更高效的组合计算当结果可以由已经算好的子行结果更高效地合并得到时可以提供一个merge函数const sum constructAggregationFnany, any, unknown, number({ aggregate: ({ rows, getValue }) rows.reduce((total, row) { const value getValue(row) return total (typeof value number ? value : 0) }, 0), merge: ({ subRowResults }) subRowResults.reduce((total, value) total value, 0), })merge中的subRowResults[i]是先前为subRows[i]计算出的聚合结果。没有merge时嵌套分组会以该组的深度选择rows 其直接subRows两者调用aggregate。这种基于上下文的新形式取代了旧的可调用聚合签名及其fromRows、resolveDataValue属性同时保留了对两种行集合的访问。内置函数是这套自定义机制的最佳参照例如aggregationFn_sum在aggregate中累加数值非数值贡献 0在merge中仅合并数字类型的子结果见 aggregationFns.ts。提供服务端或外部预计算值列级getAggregationValue提供器一个列可以在本地计算之前先接管聚合值请求。做法是在列上提供getAggregationValueconst amountColumn columnHelper.accessor(amount, { aggregationFn: sum, getAggregationValue: ({ rows }) { if (rows ! undefined) return undefined // use local fallback for overrides return { value: serverTotals.amount } }, })返回{ value }表示该请求已被接管即使value是undefined也算接管即{ value: undefined }同样有效。返回undefined则回退到本地计算。将同样的提供器放到defaultColumn上可以让所有列共享。在上面的例子中当调用者显式传入rows即rows ! undefined属于行子集覆盖请求时返回undefined走本地回退而当rows为undefined默认总计请求时直接返回服务端预计算的总计。manualAggregation关闭本地回退设置manualAggregation: true可以禁用column.getAggregationValue()的本地回退即所有聚合值都必须由外部提供。它和manualGrouping是两回事后者控制分组行模型是否运行。选择数据管线数据管线应该在客户端还是服务端运行可参考 客户端 vs 服务端指南。内置聚合函数速查以下是tanstack/react-table内置的聚合定义逐个导入aggregationFn_*可获得更好的 tree-shaking完整实现见 aggregationFns.ts名称行为说明sum对数值求和非数值贡献 0。count统计行数与列值无关。min/max求数值或Date的边界值非法类型被忽略。extent返回[min, max]空输入返回[undefined, undefined]。mean对数值及类数字非空值求平均空值与非数值被忽略。median要求每个行值都是数字非数值被忽略返回中位数或undefined。unique/uniqueCount使用 JavaScriptSet语义去重 / 去重计数。first/last返回位置值包含 nullish 值。auto自动推断aggregationFn: auto会检查第一条核心行core row的值数字number→ 解析为已注册的sumDate→ 解析为已注册的extent其他类型 →不解析任何聚合。这也是rowAggregationFeature的默认aggregationFn取值见 rowAggregationFeature.ts。注意auto的解析依赖注册表中存在对应的sum/extent因此使用auto时记得注册这两个函数。Web Workers 与聚合在 Worker Row Models 指南 所述的工作线程worker场景中基于 worker 的分组行模型会在 worker 内主动预计算那些显式配置了聚合的分组聚合值。column.getAggregationValue()的最终总计仍在主线程上、基于选中的行模型执行。跨 worker 边界传递的聚合结果必须是结构化可克隆structured-cloneable的例如纯对象、数组、数字等函数、Map等特殊对象可能无法正确传递。因此若数据管线迁移到 worker请确保聚合输出值满足 structured-clone 约束并充分理解分组聚合值在 worker 侧预计算、最终总计在主线程计算的这种分工。总结TanStack Table 的聚合功能由rowAggregationFeature独立提供与列分组解耦既可以用于普通表格的 footer 总计也可以与columnGroupingFeature组合实现分组摘要行。核心要点可归纳为注册按名称引用内置函数时需在aggregationFns中注册对应aggregationFn_*定义列配置aggregationFn支持单个标量名称 /auto/ 内联定义或带唯一 id 的数组多聚合返回键控对象取值column.getAggregationValue()无参时聚合过滤后、预分组的默认行模型传rows时可对任意行模型或自定义子集计算maxDepth/maxAggregationDepth控制参与聚合的行层级分组展示用aggregatedCell渲染合成分组行的聚合值用cell.getIsAggregated()识别聚合单元格自定义constructAggregationFn提供基于上下文的aggregate可选merge定义上下文包含rows、getValue、column、columnId、maxDepth、table分组期间还有groupingRow与subRows外部值列级 /defaultColumn级getAggregationValue提供器可接管请求manualAggregation: true关闭本地回退Worker分组聚合在 worker 内预计算最终总计在主线程执行跨线程结果需结构化可克隆。通过 Aggregation 示例 与 Grouped Aggregation 示例 的可运行代码以及packages/table-core/src/features/row-aggregation/下的源码实现你可以在此基础上构建出从简单总计到复杂分组汇总的任意聚合需求。【免费下载链接】table Headless UI for building powerful tables datagrids for TS/JS - React-Table, Vue-Table, Solid-Table, Svelte-Table项目地址: https://gitcode.com/gh_mirrors/ta/table创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考