企业官网建设流程全解析

• UI组件
• 前端

本文介绍 NG-ZORRO（ng-zorro-antd）通用 Pipes 集合中的nzAggregate管道：一个专门用于对数值数组执行求和（sum）、最大值（max）、最小值（min）、平均值（avg）等聚合操作的 Angular 管道。它适用于仪表盘统计卡片、数据报表摘要、图表示例数据等场景，读完后你将掌握该管道的引入方式、完整参数用法、模板写法与底层实现原理，并能结合源码与测试用例理解其边界行为。

nzAggregate 是什么：数组聚合操作的声明式方案

在 Angular 模板中处理数组统计需求时，传统做法是先在组件类中编写reduce、Math.max等逻辑再绑定到模板，代码分散且难以复用。nzAggregate管道把这类高频聚合操作封装为纯函数式管道，让你在模板中直接声明式计算：

{{ [7, 8, 2, 3] | nzAggregate: 'sum' }}

该管道是 ng-zorro-antd 的 Pipes 组件集合（位于 components/pipes）中六个内置管道之一，与其同级的是nzBytes、nzToCssUnit、nzEllipsis、nzSanitizer、nzTrim。其官方功能说明（见 demo/aggregate.md）为：数组的 Sum、Min、Max、Average 等聚合操作（"Sum, Min, Max, Average and other operations on arrays"）。

引入与注册方式

nzAggregate由NzAggregatePipe实现，需要通过NzPipesModule或 Angular 现代组件式导入两种方式使用：

方式一：模块注册（NgModule）

在NzPipesModule（定义见 nz-pipes.module.ts）中，NzAggregatePipe与其他管道一同被声明并导出，因此只需在特性模块中引入该模块即可在模板中使用全部管道：

import { NgModule } from '@angular/core'; import { NzPipesModule } from 'ng-zorro-antd/pipes'; @NgModule({ imports: [NzPipesModule] }) export class MyModule {}

方式二：组件级导入（Standalone）

从源码结构看，仓库的演示组件采用 Standalone 方式按需导入单个管道：

import { Component } from '@angular/core'; import { NzAggregatePipe } from 'ng-zorro-antd/pipes'; @Component({ selector: 'my-aggregate-demo', imports: [NzAggregatePipe], template: `...` }) export class MyAggregateDemoComponent {}

ng-zorro-antd/pipes的公开导出入口见 public-api.ts，其中导出了nz-aggregate.pipe与nz-pipes.module，两种方式均可靠。

API 与参数说明

官方 API 文档（doc/index.zh-CN.md）对nzAggregate的参数定义如下：

结合 nz-aggregate.pipe.ts 的实现，四种聚合方式的语义为：

类型定义同样来自源码：export type AggregateMethod = 'sum' | 'max' | 'min' | 'avg'。传入管道的不再是普通字符串，而是类型安全的联合类型，能获得 IDE 的自动补全与编译期校验。

模板中的典型用法：结合 nz-statistic 的统计卡片

仓库官方演示（demo/aggregate.ts）给出了一套可直接复用的完整模板，使用nz-row/nz-col栅格布局配合nz-statistic统计组件，将四种聚合结果并列展示：

<nz-row [nzGutter]="16"> <nz-col [nzSpan]="6"> <nz-statistic [nzValue]="[7, 8, 2, 3] | nzAggregate: 'max'" nzTitle="Max [7, 8, 2, 3]" /> </nz-col> <nz-col [nzSpan]="6"> <nz-statistic [nzValue]="[7, 8, 2, 3] | nzAggregate: 'min'" nzTitle="Min [7, 8, 2, 3]" /> </nz-col> <nz-col [nzSpan]="6"> <nz-statistic [nzValue]="[7, 8, 2, 3] | nzAggregate: 'sum'" nzTitle="Sum [7, 8, 2, 3]" /> </nz-col> <nz-col [nzSpan]="6"> <nz-statistic [nzValue]="[7, 8, 2, 3] | nzAggregate: 'avg'" nzTitle="Avg [7, 8, 2, 3]" /> </nz-col> </nz-row>

演示组件通过imports: [NzGridModule, NzStatisticModule, NzAggregatePipe]显式引入所需依赖。注意[7, 8, 2, 3] | nzAggregate: 'max'的写法：管道参数（method）放在冒号之后。由于该管道为纯管道，Angular 会在输入数组引用未变化时复用上一次的求值结果，模板表达式保持简洁且无额外性能开销。

底层实现原理与边界行为

核心实现

NzAggregatePipe实现PipeTransform接口，核心逻辑（nz-aggregate.pipe.ts）如下：

transform(value: number[], method: AggregateMethod): undefined | number { if (!Array.isArray(value)) { return value; } if (value.length === 0) { return undefined; } switch (method) { case 'sum': return sum(value); case 'avg': return sum(value) / value.length; case 'max': return Math.max(...value); case 'min': return Math.min(...value); default: throw Error(`Invalid Pipe Arguments: Aggregate pipe doesn't support this type`); } }

关键实现细节：

• 求和复用核心工具函数：'sum'与'avg'分支都调用了ng-zorro-antd/core/util导出的sum工具函数，其定义见 components/core/util/number.ts：

export function sum(input: number[], initial: number = 0): number { return input.reduce((previous: number, current: number) => previous + current, initial); }

它基于数组reduce实现，并允许传入initial初始值（默认0）。avg即sum(value) / value.length。

• 极值与展开运算：'max'/'min'借助 ES6 展开语法将数组展开为Math.max(...value)/Math.min(...value)，等价于Math.max(7, 8, 2, 3)。从源码结构看，对于超大规模数组，展开语法存在栈溢出风险，日常报表场景（数据量通常在数百以内）不受影响。

• 空数组返回undefined：聚合结果无法定义时返回undefined，恰好可与nz-statistic等组件的空值语义衔接。

• 非法 method 抛出异常：switch的default分支抛出Invalid Pipe Arguments: Aggregate pipe doesn't support this type，提示开发者传入的聚合方式不受支持——这是类型联合仍可能被绕过（如as any或来自外部数据）时的运行时兜底校验。

• 非数组输入原样透传：!Array.isArray(value)时直接返回value，避免对null、undefined或非数组值执行聚合时报错。

测试用例验证

仓库配套单元测试（nz-aggregate.pipe.spec.ts）覆盖了全部四种方法，可作为行为规范的权威参考：

• max：[1, 2, 3, 4]→4；[1]→1；[1, 1]→1；[]→undefined
• min：[1, 2, 3, 4]→1；[4, 3, 2, 5]→2；[]→undefined
• sum：[1, 2, 3, 4]→10；[1]→1；[1, 1]→2
• avg：[1, 2, 3, 4]→2.5；[1]→1；[1, 1]→1；[]→undefined

单元素数组在所有方法下均返回该元素本身，空数组统一返回undefined，这些断言与源码逻辑一一对应。

最佳实践小结

• 优先在模板中直接用| nzAggregate: 'sum'完成展示型聚合，无需在组件类里手写reduce与循环；
• 聚合数据来自响应式状态时，注意保持数组引用稳定（如使用不可变更新），以发挥纯管道的缓存收益；
• 需要自定义初始值、小数位控制或更多聚合算法（如方差、中位数）时，可参考sum工具函数（components/core/util/number.ts）自行扩展；该文件还提供了toDecimal、getPrecision、ensureNumberInRange等数值工具可组合使用；
• 遇到非法method报错Invalid Pipe Arguments时，检查传入的聚合方式是否在'sum' | 'max' | 'min' | 'avg'四种取值之内。

nzAggregate以约 20 行实现覆盖了报表与统计场景最常用的四种数组聚合运算，配合NzPipesModule的集中导出，是 ng-zorro-antd 生态中"小而实用"的工具型管道代表。

• UI组件
• 前端