syncfusion-blazor-pivot-table

Syncfusion Blazor Pivot Table

Syncfusion Blazor Pivot Table（SfPivotView）是一款功能强大的多维数据分析组件，支持用户沿行、列、值和筛选轴组织、汇总和可视化数据，类似于 Excel 数据透视表。它支持关系型数据（JSON/IEnumerable）和 OLAP 多维数据集，并提供字段列表和分组栏等交互式运行时控件。

⚠️ 重要： 请务必查阅本技能中的参考文件（references/*.md），以核实 API 类名、属性和方法签名。这些文件包含经过验证且可正常运行的示例。请勿根据其他来源推测 API 详情。

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

关键安全提示： 实现数据透视表时，始终使用可信数据源。未经适当验证和清理，切勿从不可信或用户提供的 URL 获取或绑定数据。

安全最佳实践：

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

安全风险：

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

推荐做法：

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

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

何时使用此技能

• 在 Blazor WASM、Server 或 MAUI 应用中实现 SfPivotView
• 使用 JSON、远程或 OLAP 数据配置 PivotViewDataSourceSettings
• 使用字段列表、分组栏、聚合或计算字段
• 对数据透视数据应用筛选、排序或分组
• 在数据透视表中启用编辑、导出（Excel/PDF）或工具栏
• 在网格旁边或以图表替代网格的方式呈现数据透视图表
• 使用虚拟滚动、分页或服务器端引擎优化数据透视性能
• 应用数字/条件格式、钻取、透视
• 持久化数据透视状态或处理数据透视事件
• 构建 AI 驱动的 Smart Pivot 功能

导航指南

入门

📄 阅读： references/getting-started.md

• 安装 NuGet 包、注册服务、添加 CSS/JS
• 在 Blazor WASM、Server 或 MAUI 应用中初始化 SfPivotView
• 分配示例数据并配置行/列/值/筛选轴
• 最小可运行示例

数据绑定

📄 阅读： references/data-binding.md

• 绑定本地 JSON/IEnumerable 数据
• 使用 SfDataManager 与 JsonAdaptor、WebApiAdaptor、ODataV4Adaptor
• 远程数据绑定模式和延迟加载

OLAP 数据源

📄 阅读： references/olap.md

• 连接到 Microsoft SQL Server Analysis Services（SSAS）OLAP 多维数据集
• 配置 OLAP 多维数据集元素：层次结构、度量、维度、命名集
• 计算字段和 MDX 表达式
• 身份验证和基于角色的访问
• OLAP 专属功能：字段列表、分组栏、虚拟滚动

连接数据库

📄 阅读： references/connecting-to-data-sources.md

• 连接到 SQL Server、MySQL、PostgreSQL、MongoDB、Oracle、Snowflake、Elasticsearch
• 适用于 Blazor 的服务端数据服务模式
• 连接字符串设置和适配器配置

字段列表

📄 阅读： references/field-list.md

• 启用内置（弹出式）或独立字段列表
• 自定义字段：标题、可见性、拖动行为
• 延迟布局更新，以批量更改字段

分组栏

📄 阅读： references/grouping-bar.md

• 启用 ShowGroupingBar，以便通过拖放管理字段
• 在运行时筛选、排序和移除字段
• 自定义分组栏的外观和行为

聚合

📄 阅读： references/aggregation.md

• 所有 SummaryTypes（Sum、Count、Avg、Min、Max、总计百分比等）
• 通过 PivotViewValue.Type 为每个值字段设置聚合方式
• DifferenceFrom、PercentageOfDifferenceFrom、RunningTotals

计算字段

📄 阅读： references/calculated-field.md

• 通过 UI 对话框或 PivotViewCalculatedFieldSettings 创建基于公式的自定义字段
• 在值轴中显示计算字段
• 以编程方式打开对话框

筛选

📄 阅读： references/filtering.md

• 成员筛选（包含/排除）、标签筛选、值筛选
• 使用 PivotViewFilterSettings 以编程方式设置筛选
• 日期筛选和 OLAP 筛选

排序

📄 阅读： references/sorting.md

• 启用 EnableSorting，对成员进行排序（升序/降序）
• 使用 PivotViewSortSettings 以编程方式排序
• 按值对列标题进行排序

分组

📄 阅读： references/grouping.md

• 数字分组（范围）、日期分组（年/季度/月/日）、自定义分组
• 启用 AllowGrouping 和右键单击 UI
• 以编程方式配置分组

下钻

📄 阅读： references/drill-down.md

• 展开/折叠成员层次结构
• 使用 ExpandAll 在加载时显示所有级别
• 以编程方式执行下钻操作

钻取明细

📄 阅读： references/drill-through.md

• 使用钻取明细弹出窗口查看值单元格背后的原始数据

编辑

📄 阅读： references/editing.md

• 启用 PivotViewCellEditSettings，对原始数据执行 CRUD 操作
• 编辑模式：Normal、Dialog、Batch、Command Columns
• 行内编辑；通过确认对话框添加/更新/删除

格式设置

📄 阅读： references/formatting.md

• 通过 PivotViewFormatSettings 设置数字格式（N、C、P、自定义）
• 使用 PivotViewConditionalFormatSettings 设置条件格式
• 在运行时通过工具栏应用格式

布局与显示

📄 阅读： references/layout-and-display.md

• 组件宽度/高度、经典布局
• 行/列自定义（冻结表头、列宽、自动调整）
• 显示/隐藏总计和小计
• 单元格中的超链接、工具提示

工具栏

📄 阅读： references/tool-bar.md

• 启用 ShowToolbar 并使用内置项目（Grid、Chart、Export、Formatting、Field List）
• 自定义工具栏项目和事件处理
• 报表管理（保存、加载、重命名、删除）

Excel 导出

📄 阅读： references/excel-export.md

• Excel 导出：ExportToExcelAsync、样式、自定义文件名
• CSV 导出、导出为内存流
• 通过工具栏或以编程方式导出

PDF 导出

📄 阅读： references/pdf-export.md

• PDF 导出：ExportToPdfAsync、页面设置、主题
• 将图表与表格一起导出

性能优化

📄 阅读： references/performance-best-practices.md

• 对大型数据集使用虚拟滚动（EnableVirtualization）
• 使用分页（PivotViewPageSettings）作为虚拟滚动的替代方案
• 数据压缩、延迟布局更新
• WebAssembly 专属优化
• 使用服务器端数据透视引擎分担计算

数据透视图表

📄 阅读： references/pivot-chart.md

• 仅渲染图表、仅渲染网格，或同时渲染两者（PivotViewDisplayOption）
• 通过 PivotChartSettings 支持 15 种以上图表类型
• 在图表中下钻、使用多个坐标轴、导出图表

状态持久化与事件

📄 阅读： references/state-and-events.md

• 使用 EnablePersistence 自动保存到浏览器本地存储
• 以编程方式保存/加载布局（GetPersistDataAsync / LoadPersistDataAsync）
• 关键事件参考：BeforeColumnsRender、CellClick、DrillThrough、OnLoad

Smart Pivot（AI）

📄 阅读： references/smart-pivot.md

• 使用 Syncfusion.Blazor.AI NuGet 包启用 AI 驱动的功能
• 智能数据聚合、预测建模、自适应筛选
• 配置 OpenAI、Azure OpenAI 或 Ollama

快速入门示例

@using Syncfusion.Blazor.PivotView

<SfPivotView TValue="ProductDetails" Height="350">
    <PivotViewDataSourceSettings DataSource="@data" EnableSorting="true">
        <PivotViewColumns>
            <PivotViewColumn Name="Year"></PivotViewColumn>
        </PivotViewColumns>
        <PivotViewRows>
            <PivotViewRow Name="Country"></PivotViewRow>
            <PivotViewRow Name="Products"></PivotViewRow>
        </PivotViewRows>
        <PivotViewValues>
            <PivotViewValue Name="Sold" Caption="Units Sold"></PivotViewValue>
            <PivotViewValue Name="Amount" Caption="Sold Amount"></PivotViewValue>
        </PivotViewValues>
        <PivotViewFormatSettings>
            <PivotViewFormatSetting Name="Amount" Format="C0" UseGrouping="true"></PivotViewFormatSetting>
        </PivotViewFormatSettings>
    </PivotViewDataSourceSettings>
</SfPivotView>

@code {
    public List<ProductDetails> data { get; set; }
    protected override void OnInitialized()
    {
        data = ProductDetails.GetProductData().ToList();
    }
}

常见模式

启用字段列表和分组栏

<SfPivotView TValue="ProductDetails" ShowFieldList="true" ShowGroupingBar="true">

启用包含导出功能的工具栏

<SfPivotView TValue="ProductDetails" ShowToolbar="true"
             Toolbar="@toolbar" AllowExcelExport="true" AllowPdfExport="true">
@code {
    public List<ToolbarItems> toolbar = new List<ToolbarItems> {
        ToolbarItems.Grid, ToolbarItems.Chart, ToolbarItems.Export,
        ToolbarItems.SubTotal, ToolbarItems.GrandTotal, ToolbarItems.FieldList
    };
}

大型数据的虚拟滚动

<SfPivotView TValue="MyData" EnableVirtualization="true" ShowTooltip="false"
             Width="100%" Height="500">

仅显示数据透视图表

<SfPivotView TValue="ProductDetails">
    <PivotViewDisplayOption View=View.Chart></PivotViewDisplayOption>
    <PivotChartSettings Title="Sales Analysis">
        <PivotChartSeries Type=ChartSeriesType.Column></PivotChartSeries>
    </PivotChartSettings>
</SfPivotView>

关键属性

属性	类型	用途
TValue	Generic	数据行的模型类型
Height / Width	string/int	组件尺寸
ShowFieldList	bool	启用弹出式字段列表
ShowGroupingBar	bool	启用分组栏
ShowToolbar	bool	启用工具栏
EnableVirtualization	bool	虚拟滚动
AllowGrouping	bool	启用日期/数字分组
AllowCalculatedField	bool	启用计算字段
AllowExcelExport	bool	启用 Excel 导出
AllowPdfExport	bool	启用 PDF 导出
AllowEditing	bool（在 PivotViewCellEditSettings 中）	启用增删改查编辑
EnablePersistence	bool	将状态保存到 localStorage