syncfusion-angular-pivot-table

实现 Angular Pivot Grid

Syncfusion Angular Pivot Grid 是一款功能强大的数据可视化与分析组件，可用于创建交互式透视表、汇总多维数据并执行高级分析操作。

重要提示： 务必查阅此技能中的参考文件（references/*.md），验证 API 类名、属性和方法签名。这些文件包含经过验证且可正常运行的示例。请勿假设其他来源中的 API 详情准确无误。

⚠️ 安全警告：数据源验证

重要安全提示： 实现透视表时，务必使用可信数据源。切勿在未进行适当验证和清理的情况下，从不可信或用户提供的 URL 获取或绑定数据。

安全最佳实践：

1. 使用本地数据：优先使用本地内存数据源，以确保最高安全性
2. 验证远程数据源：仅连接到由你控制且经过身份验证和授权的 API 端点
3. 清理用户输入：切勿允许用户指定任意 URL 或数据源
4. 实施身份验证：始终使用身份验证标头和安全的 API 端点
5. 验证内容：绑定外部来源的数据前，验证并清理收到的所有数据
6. 使用 HTTPS：远程数据连接始终使用 HTTPS
7. 速率限制：对 API 端点实施速率限制，以防止滥用

安全风险：

• 间接提示词注入：不可信的第三方数据可能包含恶意内容，操纵 AI Agent 的行为
• 数据泄露：恶意数据源可能试图提取敏感信息
• 代码注入：不可信数据可能包含脚本或有害内容

建议做法：

✅ 应该： 使用受控且经过身份验证的后端 API ✅ 应该： 实施服务器端数据验证 ✅ 应该： 使用环境变量配置 API 端点 ✅ 应该： 将允许的数据源加入白名单

❌ 不要： 接受用户提供的 URL ❌ 不要： 绑定到公开且不可信的端点 ❌ 不要： 跳过数据验证和清理 ❌ 不要： 对敏感数据使用 HTTP

何时使用此技能

在用户需要以下操作时使用此技能：

• 根据多维数据创建和配置透视表
• 绑定 OLAP 或关系型数据源
• 使用多种汇总函数（Sum、Avg、Count 等）汇总数据
• 按数字范围、日期或自定义类别对数据分组
• 使用公式创建和管理计算字段
• 启用下钻和穿透操作
• 使用集成的透视图表可视化数据
• 应用自定义格式和条件样式
• 优化大型数据集的性能
• 将透视表数据导出到 Excel 或 PDF
• 保存和恢复透视表状态
• 使用字段列表、分组栏和工具栏自定义 UI

文档指南

入门

📄 阅读： references/getting-started.md

• 安装和软件包设置（Angular 21 独立架构）
• Angular Pivot Grid 基本实现
• 主题包 — 使用整合后的 @syncfusion/ej2-{theme}-theme 包（例如 ej2-material3-theme），并仅导入一次 styles/pivotview/index.css
• CSS 导入和主题配置
• 组件初始化（PivotViewModule、bootstrapApplication）

汇总

📄 阅读： references/aggregation.md

• 汇总函数：Sum、Avg、Count、Min、Max、Product、Median、DistinctCount
• 高级汇总：DifferenceFrom、PercentageOfDifferenceFrom、PercentageOfParentTotal
• 父级总计汇总：PercentageOfParentColumnTotal、PercentageOfParentRowTotal（按轴计算父级百分比）
• 累计汇总：RunningTotals 和 PercentageOfRunningTotals（累计占总计的百分比；仅限客户端）
• 使用 baseField 和 baseItem 属性配置基准字段
• 对同一字段应用多个汇总
• 自定义汇总下拉菜单和 UI
• 在运行时更改汇总类型
• 事件：aggregateCellInfo、actionBegin、actionComplete、actionFailure

分组

📄 阅读： references/grouping.md

• 使用 allowGrouping: true 启用分组，并注入 GroupingService
• 数字分组：使用 rangeInterval、startingAt、endingAt 配置范围
• 日期分组：按年、季度、月、日、小时、分钟、秒整理
• 自定义分组：按业务定义的类别对数据分组
• 通过上下文菜单进行 UI 分组
• 取消分组和以编程方式取消分组
• 常见分组模式和故障排除

计算字段

📄 阅读： references/calculated-field.md

• 以交互方式和编程方式创建计算字段
• 使用 allowCalculatedField: true 启用，并注入 CalculatedFieldService
• 使用 calculatedFieldSettings（名称、公式）定义字段
• 将字段以 type: 'CalculatedField' 添加到 values 数组
• 通过 UI（字段列表、分组栏）编辑或重命名字段
• 公式语法：运算符（+, -, , /, ^, <, >, ==, !=, &, |, ?），函数（abs、min、max、isNaN、Math.）
• 公式中的汇总函数：Sum、Count、Avg、Min、Max
• 使用单独的 formatSettings 数组设置格式：货币（C）、数字（N）、百分比（P）
• 事件：calculatedFieldCreate（验证）、actionBegin/actionComplete（控制操作）

数据透视图集成

📄 阅读： references/pivot-chart-integration.md

• 注入 PivotChartService 提供程序以启用图表功能
• 图表类型：21 种以上，包括 Line、Column、Area、Bar、StepArea、Pie、Doughnut、Funnel、Pyramid、Radar、Polar、Pareto、Bubble、Scatter、Spline
• 显示选项：使用 displayOption 属性，并通过 view 和 primary 设置显示表格、图表或两者
• 系列自定义：通过 chartSettings 中的 chartSeries 自定义图表（type、marker、dataLabel）
• 字段列表集成：使用 showFieldList: true 启用动态字段操作
• 分组栏支持：使用 showGroupingBar: true 启用坐标轴字段切换
• 坐标轴配置：通过 chartSettings 中的 primaryXAxis 和 primaryYAxis 自定义 X/Y 轴
• 多坐标轴：配置 enableMultipleAxis，并使用 multipleAxisMode 实现多值可视化
• 累积图表钻取：通过上下文菜单支持 Pie、Doughnut、Funnel、Pyramid 的下钻和上钻

筛选与排序

📄 阅读： references/filtering-and-sorting.md

• 成员筛选：包含或排除特定字段成员（包含/排除，OLAP 使用 levelCount）
• 将当前选择追加到筛选条件：在成员编辑器中累积选择，而不是替换现有选择
• 成员编辑器体验：全选/取消全选、搜索成员、在编辑器中对成员排序
• 限制显示的成员数量：调整 maxNodeLimitInMemberEditor，以适应大型层次结构
• OLAP 成员加载：通过 loadOnDemandInMemberEditor 和 levelCount 按需加载
• 标签筛选：按字符串（Equals、Contains、BeginWith、Between，……）、数字或日期筛选标题文本
• 值筛选：使用运算符（Equals、GreaterThan、Between，……）和前 N/后 N成员，按聚合值筛选
• 筛选事件：memberFiltering、memberEditorOpen、actionBegin/actionComplete/actionFailure
• 成员排序：按升序/降序排列字段成员
• 自定义成员排序：使用 membersOrder 按用户定义的顺序对字段成员排序
• 值排序：使用 enableValueSorting 对数据透视表值和聚合数据排序
• 编程式值排序：使用 valueSortSettings 进行配置

数据格式化与条件格式化

📄 阅读： references/data-formatting.md

• 数字格式化：应用货币（C）、百分比（P）、数字（N）、科学计数法（E）格式
• 自定义格式字符串：使用占位符为计算字段定义格式字符串
• 条件格式化：使用 conditionalFormatSettings 根据单元格值应用颜色/样式
• 格式设置配置：在 dataSourceSettings 的独立 formatSettings 数组中进行配置

导出与打印

📄 阅读： references/export-and-print.md

• Excel 导出：使用 excelExport() 导出，并设置自定义属性和主题
• PDF 导出：使用 pdfExport() 导出，并设置页眉、页脚和页面方向
• CSV 导出：使用 csvExport() 导出大型数据集（100 万行以上）
• 打印功能：使用 print() 方法打印表格和图表
• 多表导出：在单个文件中合并多个数据透视表
• 导出自定义：设置单元格样式、配色主题和品牌元素

UI 自定义

📄 阅读： references/ui-customization.md

• 工具栏配置：显示/隐藏内置工具栏项
• 报表管理：新建、保存、加载、删除报表
• 视图切换：在网格和图表模式之间切换
• 导出选项：快速导出按钮
• 总计/小计：显示/隐藏总计和小计，并自定义其位置
• 自定义模板：构建自定义工具栏或字段列表

分组栏 UI 操作

📄 阅读： references/grouping-bar-ui-operations.md

• 启用分组栏：在组件上设置 showGroupingBar: true
• 拖放重组：在行、列、值、筛选轴之间移动字段
• 筛选操作：通过分组栏字段按钮访问筛选器
• 排序操作：通过分组栏界面配置排序选项
• 移除操作：直接从分组栏移除字段
• 值字段管理：在累积图表中切换值字段
• 隐藏特定图标：按字段控制筛选、排序、移除图标的可见性
• 分组栏自定义：通过 groupingBarSettings 进行配置

工具提示自定义

📄 阅读： references/tooltips-customization.md

• 启用/禁用工具提示：配置单元格和图表上的工具提示可见性
• 自定义工具提示模板：使用占位符定义动态工具提示内容
• 可用占位符：行标题、列标题、值及其他单元格元数据
• 数据透视图工具提示自定义：自定义图表数据点的工具提示外观
• CSS 样式：使用自定义 CSS 设置工具提示样式
• 动态工具提示内容：根据单元格值和上下文进行配置

编辑与钻取操作

📄 阅读： references/editing-drill-operations.md

• 启用编辑：在组件上设置 allowEditing: true（仅适用于关系型数据）
• 编辑模式：普通（内联）、对话框（弹出窗口）、批量（多条记录）、命令列（专用列）
• 编辑设置：通过 editSettings 配置 allowAdding、allowDeleting、allowCommandColumns
• 编辑事件：监听 editCompleted、actionBegin、actionComplete、actionFailure
• CRUD 操作：通过编辑界面创建、读取、更新和删除记录
• 上钻操作：通过上下文菜单查看聚合值对应的底层原始数据
• 下钻操作：单击单元格，深入浏览分层数据
• 单元格选择：通过 selectionSettings 配置
• 保存数据：更新后的记录通过事件处理程序和数据绑定持久化

OLAP 数据源

📄 阅读： references/olap-data-sources.md

• 连接配置：在 dataSourceSettings 中设置 url、catalog、cube、providerType: 'SSAS'
• OLAP 多维数据集元素：度量值（数值聚合）、维度（分层分组）、层级、命名集
• MDX 支持：使用 MDX（多维表达式）语法配置查询
• 层级：通过 [Dimension].[Hierarchy] 表示法访问（例如，[Date].[Date Hierarchy]）
• 计算字段：在 OLAP 多维数据集中创建计算度量值和维度
• 身份验证：通过连接字符串或后端身份验证标头进行配置
• 命名集：用于分析的预定义成员组
• 高级功能：在 OLAP 中进行下钻、虚拟滚动和值筛选

分页配置

📄 阅读： references/paging-configuration.md

• 设置 enablePaging: true 并注入 PagerService 以启用分页
• 页面设置：rowPageSize、columnPageSize、currentRowPage、currentColumnPage
• 配置分页器 UI 及其位置（顶部／底部）
• 行分页与列分页
• 紧凑视图和反向分页器布局
• 在下拉菜单中自定义页面大小选项
• 结合虚拟滚动进行分页以提升性能
• 对超大数据集进行服务端分页
• 针对移动设备优化分页

虚拟滚动

📄 阅读： references/virtual-scrolling.md

• 对大型数据集设置 enableVirtualization: true 以启用虚拟滚动
• 单页模式：使用 allowSinglePage: true 仅渲染当前视图页
• 限制：列宽使用基于像素的 columnWidth，避免在运行时更改尺寸
• 使用 enginePopulated 事件和 update／updateView 方法同步静态 FieldList
• 针对客户端 10 万行以上数据进行性能优化

下钻与上钻操作

📄 阅读： references/drill-down.md

• 下钻：单击单元格以浏览分层数据
• 上卷：返回更高层级
• 上钻：查看聚合值对应的底层原始数据
• 事件：用于钻取交互的 cellClick、fieldDrop、fieldsUpdated
• 上下文菜单：内置钻取操作

数据库连接

📄 阅读： references/database-connections.md

• SQL Server：通过 SQL 身份验证使用连接字符串进行连接
• MySQL：使用主机、端口、用户、密码和数据库进行配置
• PostgreSQL：配置 PostgreSQL 数据库连接
• Oracle：使用命名参数连接 Oracle 数据库
• MongoDB：连接 MongoDB 集合并查询文档
• Elasticsearch：通过 Elasticsearch 索引进行大数据分析
• Snowflake：集成云数据仓库
• 服务端处理：使用 ASP.NET Core 后端执行数据库查询

服务端透视引擎

📄 阅读： references/server-side-pivot-engine.md

• 服务端聚合：将繁重的处理工作委托给 ASP.NET Core 后端
• 客户端配置：在 dataSourceSettings 中设置 mode: 'Server' 和 url 端点
• ASP.NET Core 设置：下载并配置 PivotController，并使用 Syncfusion.Pivot.Engine NuGet
• 数据源：服务端支持 Collection、JSON、CSV、DataTable 和 Dynamic 对象
• 大型数据集：通过服务端处理来处理 100K+ 行数据
• 虚拟滚动：与服务端模式结合使用，以获得最佳性能
• 导出操作：导出服务端处理的数据为 Excel/CSV
• 身份验证：通过 beforeServiceInvoke 事件或标头进行配置

性能优化

📄 阅读： references/performance-optimization.md

• 虚拟滚动：设置 enableVirtualization: true，以处理 100K+ 行数据
• 单页模式：使用 allowSinglePage: true，以获得更好的性能
• 分页：通过 pageSettings 配置行/列分页
• 数据压缩：设置 allowDataCompression: true，以汇总重复记录
• 延迟更新：使用 allowDeferLayoutUpdate: true，以批量执行字段操作
• 大型数据集处理：使用 mode: 'Server' 进行服务端处理
• 最佳实践：预筛选、优化排序、限制成员筛选，以及避免使用内置分组

状态持久化与超链接

📄 阅读： references/state-persistence-hyperlinks.md

• 状态持久化：使用 getPersistData() 保存和恢复透视配置
• 本地存储：在浏览器 localStorage 中持久化报表状态，以便用于用户会话
• 报表管理：保存、加载和删除命名报表
• JSON 序列化：以 JSON 格式导出/导入报表配置
• 超链接：通过 hyperlinkSettings 启用透视表单元格中的可点击超链接
• 超链接事件：通过相应的事件处理程序处理超链接点击
• 下钻超链接：链接到聚合数据的详细数据源

---

快速入门示例

import { PivotViewAllModule, CalculatedFieldService } from '@syncfusion/ej2-angular-pivotview';
import { Component, OnInit, ViewChild } from '@angular/core';
import { PivotViewComponent, IDataSet } from '@syncfusion/ej2-angular-pivotview';
import { DataSourceSettingsModel } from '@syncfusion/ej2-pivotview/src/model/datasourcesettings-model';

@Component({
  imports: [PivotViewAllModule],
  providers: [CalculatedFieldService],
  standalone: true,
  selector: 'app-pivot-grid',
  template: `
    <ejs-pivotview #pivotview id='PivotView' 
      [dataSourceSettings]="dataSourceSettings"
      [height]="'500px'"
      [width]="'100%'"
      [allowCalculatedField]="true" 
      [allowGrouping]="true"
      [toolbar]="toolbarItems">
    </ejs-pivotview>
  `
})
export class AppComponent implements OnInit {
    @ViewChild('pivotview') pivotViewComponent!: PivotViewComponent;
    
    public pivotData!: IDataSet[];
    public dataSourceSettings!: DataSourceSettingsModel;
    public toolbarItems: string[] = ['New', 'Save', 'SaveAs', 'Rename', 'Remove', 'Load', 'Export'];

    ngOnInit(): void {
        this.pivotData = [
            { 'Sold': 31, 'Amount': 52824, 'Country': 'France', 'Products': 'Mountain Bikes', 'Year': 'FY 2015', 'Quarter': 'Q1' },
            { 'Sold': 51, 'Amount': 86904, 'Country': 'France', 'Products': 'Mountain Bikes', 'Year': 'FY 2015', 'Quarter': 'Q2' },
            { 'Sold': 90, 'Amount': 153360, 'Country': 'France', 'Products': 'Mountain Bikes', 'Year': 'FY 2015', 'Quarter': 'Q3' },
            { 'Sold': 25, 'Amount': 42500, 'Country': 'France', 'Products': 'Road Bikes', 'Year': 'FY 2015', 'Quarter': 'Q1' },
            { 'Sold': 40, 'Amount': 68000, 'Country': 'Germany', 'Products': 'Mountain Bikes', 'Year': 'FY 2015', 'Quarter': 'Q2' }
        ];

        this.dataSourceSettings = {
            dataSource: this.pivotData,
            expandAll: false,
            rows: [{ name: 'Country' }, { name: 'Products' }],
            columns: [{ name: 'Year' }, { name: 'Quarter' }],
            values: [
                { name: 'AvgAmount', type: 'CalculatedField' },
                { name: 'Sold', type: 'Count' }
            ],
            calculatedFieldSettings: [
                {
                    name: 'AvgAmount',
                    formula: '"Sum(Amount)"/"Count(Sold)"'  // Calculated field: Average
                }
            ],
            formatSettings: [
                { name: 'Amount', format: 'C2' },             // Currency format
                { name: 'AvgAmount', format: 'C2' }           // Format calculated field
            ]
        };
    }
}

---

常见模式

模式 1：使用不同聚合类型的多个字段

每个字段只支持一种聚合类型。若要分析不同方面，请使用不同的字段及各自的聚合函数：

values: [
    { name: 'Amount', type: 'Sum' },      // Total sales amount
    { name: 'Quantity', type: 'Avg' },    // Average quantity sold
    { name: 'Sold', type: 'Count' },      // Number of transactions
    { name: 'Price', type: 'Min' },       // Minimum price
]

注意： values 数组中的每个字段只能使用一种类型。若要通过多种聚合类型进行分析，请使用不同字段，或创建组合多个聚合的计算字段。

模式 2：层次分组

通过多级分组组织数据：

rows: [
    { name: 'Country' },    // Primary level
    { name: 'Region' },     // Secondary level
    { name: 'City' }        // Tertiary level
],
columns: [
    { name: 'Year' },       // Year level
    { name: 'Quarter' }     // Quarter level
]

模式 3：将计算字段与聚合结合使用

将计算字段与多种聚合类型结合，用于高级分析：

values: [
    { name: 'Amount', type: 'Sum' },       // Total amount
    { name: 'Quantity', type: 'Avg' },     // Average quantity
    { name: 'AvgRevenue', type: 'CalculatedField' }  // Custom calculation
],
calculatedFieldSettings: [
    {
        name: 'AvgRevenue',
        formula: '"Sum(Amount)" / "Count(Quantity)"'  // Revenue per unit
    }
],
formatSettings: [
    { name: 'Amount', format: 'C2' },      // Currency format for Amount
    { name: 'AvgRevenue', format: 'C2' }   // Currency format for calculated field
]

模式 4：数值范围分组

将数值字段按范围分组：

groupSettings: [
    {
        name: 'ProductID',
        type: 'Number',
        rangeInterval: 5,
        startingAt: 1000,
        endingAt: 1010
    }
]

模式 5：日期层次分组

按时间层次组织日期：

groupSettings: [
    {
        name: 'OrderDate',
        type: 'Date',
        groupInterval: ['Years', 'Months'],  // Year then month hierarchy
        startingAt: new Date(2020, 0, 1),
        endingAt: new Date(2023, 11, 31)
    }
]

---

关键配置属性

属性	类型	位置	用途
rows	数组	dataSourceSettings	按垂直方向排列的字段，用于对数据分组
columns	数组	dataSourceSettings	按水平方向排列的字段，用于对数据分组
values	数组	dataSourceSettings	要聚合的字段，使用 type（Sum、Avg、Count、CalculatedField 等）
filters	数组	dataSourceSettings	用于筛选两个轴上数据的字段
type	字符串	values 字段	聚合类型：Sum、Avg、Count、Min、Max、Product、DistinctCount、Median、RunningTotals、PercentageOfRunningTotals（仅客户端）、DifferenceFrom、PercentageOfDifferenceFrom、PercentageOfGrandTotal、PercentageOfColumnTotal、PercentageOfRowTotal、PercentageOfParentTotal、PercentageOfParentColumnTotal、PercentageOfParentRowTotal、PopulationStDev、SampleStDev、PopulationVar、SampleVar、Index、CalculatedField
baseField	字符串	values 字段	用于 DifferenceFrom/基于 Percentage 的比较的字段引用（基准字段聚合）
baseItem	字符串	values 字段	用于基准字段比较的特定成员
allowCalculatedField	布尔值	组件	启用计算字段功能（需要 CalculatedFieldService 提供程序）
calculatedFieldSettings	数组	dataSourceSettings	定义计算字段的 name 和 formula 属性
formula	字符串	calculatedFieldSettings	使用聚合函数（Sum、Count、Avg、Min、Max）和运算符（+、-、*、/、^、<、>、==、!=、&、|、?）的数学表达式
formatSettings	数组	dataSourceSettings	用于设置值字段和计算字段的数字格式（C、N、P、E）的独立数组
allowGrouping	布尔值	组件	启用分组功能（需要 GroupingService 提供程序）
groupSettings	数组	dataSourceSettings	使用 name、type、rangeInterval、groupInterval 配置数字、日期或自定义分组
groupInterval	数组	groupSettings	分组层级（Years、Quarters、Months、Days、Hours、Minutes、Seconds）
aggregateTypes	数组	组件	将聚合下拉列表限制为特定类型（AggregateTypes 数组）
showAggregationOnValueField	布尔值	dataSourceSettings	在分组栏按钮文本中显示聚合类型（例如，“金额总和”而非“金额”）
sortSettings	数组	dataSourceSettings	使用 order、membersOrder、name 属性配置字段排序
enableValueSorting	布尔值	组件	启用按聚合值排序
allowMemberFilter	布尔值	dataSourceSettings	启用/禁用成员筛选 UI（默认 true）
allowLabelFilter	布尔值	dataSourceSettings	启用标签筛选 UI，以便按标题文本/数字/日期筛选
allowValueFilter	布尔值	dataSourceSettings	启用值筛选 UI，以便根据聚合值进行筛选
filterSettings	数组	dataSourceSettings	以编程方式设置筛选条件，包含 name、type（Include/Exclude/Label/Number/Date/Value）、condition、value1、value2、measure、items、levelCount、selectedField
condition（Top/Bottom）	字符串	filterSettings（type: 'Value'）	根据所选 measure 的聚合值筛选排名前/后 N 个成员（仅客户端）
maxNodeLimitInMemberEditor	数字	组件	成员编辑器中显示“更多项”消息前所显示的最大成员数（默认 1000）
loadOnDemandInMemberEditor	布尔值	组件	仅适用于 OLAP：在展开/选择层级之前仅加载第一个层级（默认 true）

重要：向值字段添加计算字段时，请使用 type: 'CalculatedField'，以便将其与常规聚合区分开来。格式设置必须应用于独立的 formatSettings 数组，而非值字段对象中。

---

后续步骤

基础（从这里开始）：

1. 阅读 Getting Started，了解设置和初始化
2. 阅读 Aggregation，实现聚合函数和基础字段聚合
3. 阅读 Grouping，配置数字、日期和自定义分组

数据处理： 4. 阅读 Calculated Fields，了解复杂计算和自定义字段公式 5. 阅读 Filtering & Sorting，了解标签/值筛选和自定义排序 6. 阅读 Data Formatting，了解数字格式和条件格式

可视化与交互： 7. 阅读 Pivot Chart Integration，了解图表绘制和钻取操作 8. 阅读 UI Customization，了解工具栏和自定义界面 9. 阅读 Drill-Down & Drill-Through，了解层级数据探索

高级功能： 10. 阅读 Export & Printing，了解多格式导出（Excel、PDF、CSV） 11. 阅读 State Persistence，了解配置的保存和恢复 12. 阅读 Database Connections，了解 SQL/NoSQL/大数据集成 13. 阅读 Server-Side Pivot Engine，了解如何在后端处理 100K+ 行数据 14. 阅读 Performance Optimization，了解大型数据集、延迟更新和虚拟滚动

---

基础参考资料

这些文件提供基础知识，功能指南可能会引用这些内容：

📄 references/core-concepts.md - 数据绑定类型（JSON、CSV、OLAP）、客户端与服务端对比、如何选择合适的数据源

📄 references/layout-and-columns.md - 经典布局、行/列尺寸、列功能、单元格选择和自定义

📄 references/field-list.md - 字段列表 UI（弹出/固定模式）、字段组织方式、延迟更新模式