指南Univer Sheets功能数据透视表Pro

数据透视表

Facade API付费版本需要 Univer 服务端Univer on Node.jsPreset
-UniverSheetsAdvancedPreset

数据透视表是一种强大的数据分析工具,它能够快速汇总、组织和分析大量数据,从而帮助用户发现数据中的模式和趋势。

该功能包含以下插件包:

  • @univerjs-pro/engine-pivot 提供了数据透视表最基本的数据计算能力,该插件的工作不依赖任何第三方的插件
  • @univerjs-pro/sheets-pivot 将 engine-pivot 组装成 Univer Sheets 插件以便支持表格的渲染,协同,公式等能力
  • @univerjs-pro/sheets-pivot-ui 提供一个最基本的拖拽操作界面 & 筛选以及其他交互所需要的 Dialog

目前已经支持的功能有:

  • 11 种 Excel 支持的汇总方式
  • 维度标签筛选,排序(使用 localCompare 方式)
  • 表格视图
  • 展开合并
  • 支持多个值维度,同时可以定制多值维度所在区域(value position)和位置(value index)
  • 支持维度重命名,维度设置 format
  • 自动响应数据源变化,感知公式变化

我们还计划在不久的将来支持如下功能:

  • 分组,支持日期分组,数字分组以及元素分组
  • 筛选排序,支持值筛选排序,支持条件格式
  • 值显示方式,支持完整的 11 种值显示方式
  • 计算字段 & 计算项
  • 增强排版能力,支持紧促视图和大纲视图,合并项和空行等

Presets 安装

按照 打印功能 中的引导安装即可。

高级安装

插件安装和引入

npm install @univerjs-pro/engine-pivot @univerjs-pro/sheets-pivot @univerjs-pro/sheets-pivot-ui
import { LocaleType, Tools } from '@univerjs/core';
import { UniverSheetsPivotTablePlugin } from '@univerjs-pro/sheets-pivot';
import { UniverSheetsPivotTableUIPlugin } from '@univerjs-pro/sheets-pivot-ui';
import SheetsPivotTableZhCN from '@univerjs-pro/sheets-pivot/locale/zh-CN';
import SheetsPivotTableUIZhCN from '@univerjs-pro/sheets-pivot-ui/locale/zh-CN';
 
import '@univerjs-pro/sheets-pivot-ui/lib/index.css';
 
import '@univerjs-pro/sheets-pivot/facade';
 
const univer = new Univer({
  theme: defaultTheme,
  locale: LocaleType.ZH_CN,
  locales: {
    [LocaleType.ZH_CN]: Tools.deepMerge(
      SheetsPivotTableZhCN,
      SheetsPivotTableUIZhCN
    ),
  },
});
 

插件注册

透视表插件支持针对不同的使用场景灵活注册,提供两种模式以适配不同的计算需求。

单独注册在主进程

透视表插件可以单独在主进程中注册。这种模式适用于轻量级任务,操作简单,无需额外配置插件 config。开发者只需引入 UniverSheetsPivotTablePlugin 即可。

univer.registerPlugin(UniverSheetsPivotTablePlugin);
univer.registerPlugin(UniverSheetsPivotTableUIPlugin);

主进程和 worker 进程同时注册

对于需要高性能的场景,透视表插件支持同时注册在主进程和 worker 进程中。通过这种模式,插件可以利用多线程架构实现高效的数据分发和计算处理,显著减轻主进程的计算负担,并提升整体性能。

在这种模式下,主进程主要负责数据的分发、同步和渲染,worker 进程专注于复杂的计算任务。为实现这一模式,需要在注册时通过 config 进行精细化配置。

// 浏览器主进程插件注册文件
// notExecuteFormula 为 true 表示主进程不执行计算,只负责数据的分发、同步和渲染
univer.registerPlugin(UniverSheetsPivotTablePlugin, { notExecuteFormula: true });
univer.registerPlugin(UniverSheetsPivotTableUIPlugin);
 
// web worker 进程插件注册文件
// notExecuteFormula 为 false 表示 worker 进程执行计算
univer.registerPlugin(UniverSheetsPivotTablePlugin, { notExecuteFormula: false });

Univer on Node.js 高级安装

import { LocaleType, Tools } from '@univerjs/core';
import { UniverSheetsPivotTablePlugin } from '@univerjs-pro/sheets-pivot';
import SheetsPivotTableZhCN from '@univerjs-pro/sheets-pivot/locale/zh-CN';
 
import '@univerjs-pro/sheets-pivot/facade';
 
const univer = new Univer({
  theme: defaultTheme,
  locale: LocaleType.ZH_CN,
  locales: {
    [LocaleType.ZH_CN]: Tools.deepMerge(
      SheetsPivotTableZhCN,
    ),
  },
});
 
univer.registerPlugin(UniverSheetsPivotTablePlugin, { notExecuteFormula: false });

Facade API

添加透视表

import { PositionType } from '@univerjs-pro/sheets-pivot'
 
const univerAPI = FUniver.newAPI(univer)
const fWorkbook = univerAPI.getActiveWorkbook()
const unitId = fWorkbook.getId()
const fSheet = fWorkbook.getActiveSheet()
const subUnitId = fSheet.getSheetId()
const sheetName = fSheet.getSheetName()
const sourceInfo = {
  unitId,
  subUnitId,
  sheetName,
  range: {
    startRow: 0,
    startColumn: 0,
    endRow: 8,
    endColumn: 5,
  },
}
const anchorCellInfo = {
  unitId,
  subUnitId,
  row: 0,
  col: 8,
}
const FPivot = await fWorkbook.addPivotTable(sourceInfo, PositionType.Exiting, anchorCellInfo)

FPivotTable

方法 getPivotTableByCell 可以在 FWorkbook 实例中使用,通过锚定单元格获取透视表实例。如果目标单元格在透视表中,它将返回 FPivotTable 实例。

const fPivotTable = fWorkbook.getPivotTableByCell(unitId, subUnitId, 0, 8)

透视表实例中有一些方法,可以用来操作透视表。

方法描述
remove删除透视表实例
getConfig获取当前透视表的配置信息,其中包括数据源范围,锚定单元格, 维度配置信息
addField添加一个维度
removeField删除一个维度
updateFieldPosition更新维度的所在区域以及顺序
updateValuePosition更新 ∑Value 的位置
setSubtotalType设置汇总方式
setLabelSort设置标签排序
setLabelFilter设置标签筛选
renameField重命名维度
/**
 * @description Get the pivot table config by the pivot table id.
 * @typedef PivotTableConfig
 * @property {TargetInfo} targetCellInfo  The target cell info of the pivot table.
 * @property {SourceInfo} sourceRangeInfo The source data range info of the pivot table.
 * @property {boolean} isEmpty The pivot table is empty or not.
 * @property {object} fieldsConfig The snapshot of the pivot table fields config.
 * @returns {PivotTableConfig|undefined} The pivot table config or undefined.
 */
getConfig():IPivotTableConfig;
/**
 * @description Remove a pivot table from the workbook by pivot table id
 */
async remove():void;
/**
 *@description Add a pivot field to the pivot table.
  * @param {string|number} dataFieldIdOrIndex The data field id.
  * @param {PivotTableFiledAreaEnum} fieldArea The area of the field.
  * @param {number} index The index of the field in the target area.
  * @returns {boolean} Whether the pivot field is added successfully.
  */
async addField(dataFieldIdOrIndex: string | number, fieldArea: PivotTableFiledAreaEnum, index: number): Promise<boolean>;
/**
 * @description Remove a pivot field from the pivot table
 * @param {string[]} fieldIds The deleted field ids.
 * @returns {boolean} Whether the pivot field is removed successfully.
 */
async removeField(fieldIds: string[]): Promise<boolean>;
/**
 * @description Update the pivot table field position.
 * @param {string} fieldId - The moved field id.
 * @param {PivotTableFiledAreaEnum} area - The target area of the field.
 * @param {number} index - The target index of the field, if the index is bigger than the field count in the target area, the field will be moved to the last, if the index is smaller than 0, the field will be moved to the first.
 * @returns {boolean} Whether the pivot field is moved successfully.
 */
async updateFieldPosition(fieldId: string, area: PivotTableFiledAreaEnum, index: number): Promise<boolean>;
/**
 * @description If there are multiple value fields in the pivot table, you can update the position of the value field, which only can be position in row or column.
 * @param {PivotTableValuePositionEnum} position - The position of the value field.
 * @param {number} index - The index of the value field.
 * @returns {boolean} Whether the pivot value field is moved successfully.
 */
async updateValuePosition(position: PivotTableValuePositionEnum, index: number): Promise<boolean>;
/**
 * @description Set the pivot table subtotal type for value field, it only works for the value field.
 * @param {string} fieldId - The field id.
 * @param {PivotSubtotalTypeEnum} subtotalType - The subtotal type of the field.
 * @returns {boolean} Whether the pivot table subtotal type is set successfully.
 */
async setSubtotalType(fieldId: string, subtotalType: PivotSubtotalTypeEnum): Promise<boolean>;
/**
 * @description Set the pivot table sort info.
 * @param {string} tableFieldId - The field id of the sort.
 * @param {PivotTableSortInfo} info - The sort info.
 * @typedef PivotTableSortInfo
 * @property {PivotDataFieldSortOperatorEnum} type The sort operator of the field items.
 * @returns {boolean} Whether the pivot table sort info is set successfully.
 */
async setLabelSort(tableFieldId: string, info: IPivotTableSortInfo): Promise<boolean>;
/**
 * @description Set the pivot table filter.
 * @param {string} tableFieldId - The field id of the filter.
 * @param {string[]} items - The items of the filter.
 * @returns {boolean} Whether the pivot table filter is set successfully.
 */
async setLabelFilter(tableFieldId: string, items: string[], isAll?: boolean): Promise<boolean>;
/**
 * @description Rename the pivot table field.
 * @param {string} fieldId - The field id. 
 * @param {string} name - The new name of the field.
 * @returns {boolean} Whether the pivot table field is renamed successfully.
 */
async renameField(fieldId: string, name: string): Promise<boolean>;