syncfusion-react-pivot-table

在 React 中实现 PivotView

Syncfusion React PivotView 组件提供强大的数据分析和报表功能。用户可以通过交互式数据透视表组织、分析和汇总多维数据，并使用分组、筛选、聚合、下钻分析和导出等功能。

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

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

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

安全最佳实践：

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

安全风险：

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

建议做法：

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

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

何时使用此技能

在以下情况下使用此技能：

• 创建用于数据分析的交互式数据透视表
• 设置数据聚合与汇总
• 构建动态报表仪表板
• 配置具有层次结构的行／列分组
• 实施数据筛选和排序
• 添加下钻／钻取功能
• 将报表导出为 Excel 或 PDF
• 优化大型数据集的性能
• 设置数据透视表显示样式和格式
• 在不同会话间保留数据透视表状态

导航指南

设置

📄 阅读： references/getting-started.md

• 安装、软件包设置、基础组件创建、CSS 导入、NextJS 集成

📄 阅读（可选）： references/nextjs-integration.md

• Next.js App Router 和 Pages Router 设置、动态导入、SSR 注意事项、API 路由、部署

数据管理

📄 阅读： references/data-binding.md

• JSON 数据绑定、CSV 数据绑定、远程数据绑定、字段映射、DataManager 设置

📄 阅读： references/connecting-to-databases.md

• 数据库连接、Web API 设置、SQL Server、MySQL、PostgreSQL、MongoDB、Oracle、Elasticsearch、Snowflake

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

• OLAP 连接、服务器端引擎配置、实时数据更新

可视化与交互

📄 阅读： references/pivot-chart.md

• 集成数据透视图、图表类型、可视化选项、图表自定义

📄 阅读： references/classic-layout.md

• 经典布局配置、布局切换、UI 控制选项

📄 阅读： references/drill.md

• 下钻和钻取功能、编辑、导航控件、事件处理

数据组织与显示

📄 阅读： references/field-list.md

• 内置字段列表（弹出式）、独立字段列表（固定式）、字段列表模式、UI 交互、配置选项

📄 阅读： references/grouping-bar.md

• 分组栏配置、拖放操作、筛选/排序/移除图标、字段面板、值类型图标、排除选项

📄 阅读： references/data-shaping.md

• 聚合函数、计算字段（定义和编辑）、汇总自定义选项

📄 阅读： references/aggregation.md

• 24 种以上的聚合类型（Sum、Average、Count 等）、高级聚合、基准字段配置、运行时修改

📄 阅读： references/calculated-field.md

• 交互式计算字段对话框、公式语法和运算符、基于代码的方法、格式设置

📄 阅读： references/grouping.md

• 数据分组功能、按范围对数字分组、按层级对日期分组、编程配置、取消分组

📄 阅读： references/data-formatting.md

• 数字格式设置、条件格式设置、单元格样式、工具提示自定义

📄 阅读： references/grid-customization.md

• 单元格模板、行高、列宽、文本对齐、列大小调整和重新排序、维度配置

📄 阅读： references/row-and-column.md

• 单元格模板自定义、维度配置、行高、列宽、大小调整、重新排序、文本对齐

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

• 成员筛选、标签筛选、值筛选、排序操作、筛选自定义

📄 根据需要单独阅读：

• references/member-filtering.md - 选择/排除特定成员、交互式筛选对话框、将当前选择追加到现有筛选条件
• references/label-filtering.md - 按文本模式、日期范围、数字范围筛选
• references/value-filtering.md - 按聚合值筛选、Top/Bottom N 个成员（客户端）、清除值筛选
• references/value-sorting.md - 按度量值排序、排名分析、多级排序

📄 阅读： references/show-hide-totals.md

• 总计显示、组总计配置、小计计算选项

📄 阅读： references/state-persistence.md

• 保存和加载数据透视表状态、持久化配置、状态管理模式

📄 阅读： references/toolbar.md

• 工具栏控件、按钮自定义、工具栏事件和操作

📄 阅读： references/tooltip.md

• 工具提示配置、自定义工具提示模板、工具提示格式设置

📄 阅读： references/hyperlink.md

• 超链接配置、单元格链接、导航设置、链接自定义

导航与分析

📄 阅读： references/drill.md

• 下钻和钻取功能、分层数据探索、编辑功能

📄 需要时单独阅读：

• references/drill-down.md - 下钻专属功能
• references/drill-through.md - 钻取和原始数据探索

导出与输出

📄 阅读： references/export.md

• Excel 导出、PDF 导出、导出配置、自定义导出处理程序

📄 需要时单独阅读：

• references/excel-export.md - Excel 导出详情
• references/pdf-export.md - PDF 导出详情

📄 阅读： references/print.md

• 数据透视表打印、图表打印、打印配置、浏览器兼容性

高级功能与性能

📄 阅读： references/defer-update.md

• 延迟布局更新、“应用”按钮、批量字段操作、大型数据集的性能优化

📄 阅读： references/performance.md

• 虚拟滚动、分页配置、性能最佳实践、数据压缩

📄 需要时单独阅读：

• references/virtual-scrolling.md - 高效渲染 100K+ 行、虚拟滚动设置、响应式优化

快速入门

安装 Tailwind 3 主题包。此主题包中的每个组件都包含一个 index.css 文件，会自动加载所有必需的依赖样式。

npm install @syncfusion/ej2-tailwind3-theme --save

默认情况下，Vite 项目包含一个带有默认样式的 index.css 文件。这些默认样式可能会与 Syncfusion 组件样式冲突。请清空 index.css 文件中的所有内容，以避免样式冲突。

数据透视表组件所需的样式通过 src/App.css 文件导入：

/* App.css */
@import '../node_modules/@syncfusion/ej2-tailwind3-theme/styles/pivotview/index.css';

import { PivotViewComponent, Inject, GroupingBar, FieldList, IDataSet } from '@syncfusion/ej2-react-pivotview';
import './App.css';

const pivotData: IDataSet[] = [
  { Country: 'USA', Product: 'Laptops', Sales: 5000, Year: 2020 },
  { Country: 'USA', Product: 'Mobiles', Sales: 3000, Year: 2020 },
  { Country: 'Canada', Product: 'Laptops', Sales: 2500, Year: 2020 },
  { Country: 'Canada', Product: 'Mobiles', Sales: 1500, Year: 2020 }
];

function cellTemplate(props: any): JSX.Element {
  return (
    <span style={{ fontWeight: 'bold', color: '#333' }}>
      {props.cellInfo?.value}
    </span>
  );
}

function App() {
  const dataSourceSettings: DataSourceSettingsModel = {
    dataSource: pivotData as IDataSet[],
    rows: [{ name: 'Country' }],
    columns: [{ name: 'Product' }],
    values: [{ name: 'Sales', caption: 'Total Sales' }],
    showGrandTotals: true
  };

  return (
    <PivotViewComponent
      id="pivotview"
      dataSourceSettings={dataSourceSettings}
      cellTemplate={cellTemplate}
      showGroupingBar={true}
      showFieldList={true}
      height={350}
    >
      <Inject services={[GroupingBar, FieldList]} />
    </PivotViewComponent>
  );
}

export default App;

常见模式

模式 1：包含行字段和列字段的基本数据透视表

const dataSourceSettings: DataSourceSettingsModel = {
  dataSource: data as IDataSet[],
  rows: [{ name: 'Country' }, { name: 'Region' }],
  columns: [{ name: 'Year' }, { name: 'Quarter' }],
  values: [{ name: 'Sales', caption: 'Total Sales' }]
};

模式 2：添加筛选器和聚合

const dataSourceSettings: DataSourceSettingsModel = {
  dataSource: data as IDataSet[],
  rows: [{ name: 'Country' }],
  columns: [{ name: 'Product' }],
  values: [
    { name: 'Sales', type: 'Sum' },
    { name: 'Quantity', type: 'Avg' }
  ],
  filters: [{ name: 'Year' }]
};

模式 3：计算字段

import { PivotViewComponent, Inject, CalculatedField, FieldList } from '@syncfusion/ej2-react-pivotview';
import { DataSourceSettingsModel } from '@syncfusion/ej2-pivotview/src/model/datasourcesettings-model';

const dataSourceSettings: DataSourceSettingsModel = {
  dataSource: data as IDataSet[],
  rows: [{ name: 'Country' }],
  columns: [{ name: 'Product' }],
  values: [
    { name: 'Sold', caption: 'Units Sold' },
    { name: 'Amount', caption: 'Amount' },
    { name: 'Total', caption: 'Total', type: 'CalculatedField' }  // ← Must add to values
  ],
  calculatedFieldSettings: [
    {
      name: 'Total',
      formula: '"Sum(Amount)"+"Sum(Sold)"'  // ← Formula with aggregation functions
    }
  ]
};

模式 4：带条件格式的单元格模板

function cellTemplate(props: any): JSX.Element {
  const value = props.cellInfo?.value;
  const isTotal = props.cellInfo?.isGrandTotal || props.cellInfo?.isDeserialized;
  
  const getStyle = () => {
    const numValue = parseFloat(value);
    if (numValue > 4000) return { color: '#4CAF50', fontWeight: 'bold' }; // Green for high values
    if (numValue < 1000) return { color: '#f44336', fontWeight: 'bold' }; // Red for low values
    return { color: '#333' };
  };

  return (
    <span style={getStyle()}>
      {isTotal ? <strong>{value}</strong> : value}
    </span>
  );
}

const dataSourceSettings: DataSourceSettingsModel = {
  dataSource: data as IDataSet[],
  rows: [{ name: 'Country' }],
  columns: [{ name: 'Product' }],
  values: [{ name: 'Sales' }]
};

关键属性与配置

属性	类型	描述
dataSourceSettings	object	配置数据源、字段、行、列、值、筛选器、聚合、计算字段和格式
cellTemplate	function	自定义单元格渲染函数，为值单元格返回 JSX.Element
gridSettings	GridSettings	配置行高、列宽、文本换行、调整大小和重新排序
height	string/number	组件高度，单位为像素或百分比
width	string/number	组件宽度，单位为像素或百分比
showGroupingBar	boolean	显示/隐藏分组栏，以便通过拖放管理字段
showFieldList	boolean	显示/隐藏字段列表面板（内置或侧边面板）
allowCalculatedField	boolean	允许通过字段列表对话框创建和编辑计算字段
allowExcelExport	boolean	启用 Excel 导出功能
allowPdfExport	boolean	启用 PDF 导出功能
allowMemberFilter	boolean	启用字段列表中的成员筛选（选择/取消选择成员）
allowLabelFilter	boolean	启用标签筛选（按文本/标签值筛选）
allowValueFilter	boolean	启用值筛选（按聚合值筛选）
allowDrillThrough	boolean	启用钻取功能以查看数据透视表数据
allowConditionalFormatting	boolean	启用基于值的单元格条件格式
allowDeferLayoutUpdate	boolean	在字段列表中批量处理字段操作，仅在点击“应用”后生效
enableVirtualization	boolean	为大型数据集启用虚拟滚动
enablePaging	boolean	启用行/列分页
showToolbar	boolean	显示/隐藏包含预设操作的工具栏
pageSettings	PageSettings	配置分页的行和列页面大小

GridSettings 配置

• rowHeight：指定行高，单位为像素
• columnWidth：设置默认列宽
• allowResizing：启用列/行调整大小
• allowReordering：允许通过拖放重新排列字段
• allowTextWrap：启用单元格文本换行
• columnRender：用于自定义列的事件处理程序（例如，设置文本对齐方式）

相关技能

• Syncfusion React Grid - 用于通用数据网格功能
• React Data Binding - 用于数据源管理模式