Web SDK

分组

分组功能（也称为大纲或维度大纲）允许您在电子表格中对行或列进行分组。这对于通过创建可折叠的区块来组织和汇总大量数据非常有用。

简介

在 Univer Sheets 中，分组功能使您能够：

  • 对行或列进行分组：创建行或列的层级组以组织数据。
  • 折叠和展开组：通过单击显示或隐藏分组的行或列。
  • 嵌套组：创建多个层级的组以支持复杂的数据层次结构。

分组功能通常用于以下场景：

  • 汇总详细数据：将详细行归到汇总行下，以创建更清晰的视图。
  • 组织大型数据集：将相关的列或行组合在一起，便于导航。
  • 创建可折叠报表：允许用户根据需要展开或折叠报表的各个部分。
预览

预设模式

分组功能包含在 @univerjs/preset-sheets-advanced 预设中。

安装

Shell
pnpm add @univerjs/preset-sheets-advanced

使用

TypeScript
import { UniverSheetsAdvancedPreset } from '@univerjs/preset-sheets-advanced'import UniverPresetSheetsAdvancedZhCN from '@univerjs/preset-sheets-advanced/locales/zh-CN'import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'import UniverPresetSheetsCoreZhCN from '@univerjs/preset-sheets-core/locales/zh-CN'import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'import '@univerjs/preset-sheets-core/lib/index.css'import '@univerjs/preset-sheets-advanced/lib/index.css'const { univerAPI } = createUniver({  locale: LocaleType.ZH_CN,  locales: {    [LocaleType.ZH_CN]: mergeLocales(      UniverPresetSheetsCoreZhCN,      UniverPresetSheetsAdvancedZhCN,     ),  },  presets: [    UniverSheetsCorePreset(),    UniverSheetsAdvancedPreset(),   ],})

如果您拥有 Univer 的商业许可证，请参阅在客户端中使用许可证进行配置。

插件模式

安装

Shell
pnpm add @univerjs-pro/sheets-outline @univerjs-pro/sheets-outline-ui

使用

TypeScript
import { UniverSheetsOutlinePlugin } from '@univerjs-pro/sheets-outline'import { UniverSheetsOutlineUIPlugin } from '@univerjs-pro/sheets-outline-ui'import SheetsOutlineUIZhCN from '@univerjs-pro/sheets-outline-ui/locale/zh-CN'import { LocaleType, mergeLocales, Univer } from '@univerjs/core'import '@univerjs-pro/sheets-outline/facade'import '@univerjs-pro/sheets-outline-ui/lib/index.css'const univer = new Univer({  locale: LocaleType.ZH_CN,  locales: {    [LocaleType.ZH_CN]: mergeLocales(      SheetsOutlineUIZhCN,     ),  },})univer.registerPlugin(UniverSheetsOutlinePlugin)univer.registerPlugin(UniverSheetsOutlineUIPlugin)

如果您拥有 Univer 的商业许可证，请参阅在客户端中使用许可证进行配置。

Facade API

完整 Facade API 类型定义，请查看 FacadeAPI。

引入

插件模式提示

仅插件模式需要手动引入 Facade 包。预设模式已内置对应的 Facade 包，无需额外导入。

TypeScript
import '@univerjs-pro/sheets-outline/facade'

创建行分组

您可以使用 Facade API 创建行分组：

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// 将第 2 到 6 行分组（从 0 开始索引：startRow=1, numRows=5）fWorksheet.addRowOutline(1, 5)

创建列分组

同样，您可以创建列分组：

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// 将第 B 到 E 列分组（从 0 开始索引：startColumn=1, numColumns=4）fWorksheet.addColumnOutline(1, 4)

折叠和展开分组

您可以通过编程方式折叠或展开分组：

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const rowOutlines = fWorksheet.getDimensionOutlines(univerAPI.Enum.DimensionOutlineAxis.ROW)if (rowOutlines.length > 0) {  // 折叠第一个行分组  fWorksheet.setDimensionOutlineCollapsed(rowOutlines[0].id, true)  // 稍后展开  fWorksheet.setDimensionOutlineCollapsed(rowOutlines[0].id, false)}

移除分组

您可以通过分组 ID 移除特定的分组：

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const rowOutlines = fWorksheet.getDimensionOutlines(univerAPI.Enum.DimensionOutlineAxis.ROW)if (rowOutlines.length > 0) {  fWorksheet.removeDimensionOutline(rowOutlines[0].id)}

清除范围内的分组

您可以清除特定范围内的所有分组：

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// 移除第 2 到 10 行范围内完全包含的所有行分组fWorksheet.clearDimensionOutlines(univerAPI.Enum.DimensionOutlineAxis.ROW, 1, 9)

查询分组

您可以检索工作表上的所有分组：

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// 获取所有行分组const rowOutlines = fWorksheet.getDimensionOutlines(univerAPI.Enum.DimensionOutlineAxis.ROW)rowOutlines.forEach((outline) => {  console.log(outline.id, outline.start, outline.end, outline.collapsed)})// 获取所有分组（包括行和列）const allOutlines = fWorksheet.getDimensionOutlines()

分组数据结构

每个分组具有以下属性：

属性类型说明
idstring分组的唯一标识符
unitIdstring工作簿单元 ID
subUnitIdstring工作表 ID
axisDimensionOutlineAxis分组的轴（row 或 column）
startnumber从 0 开始的包含起始索引
endnumber从 0 开始的包含结束索引
collapsedboolean分组当前是否折叠

验证与错误

创建分组时，会执行以下验证：

  • 无效范围：范围必须有效（非负数、非零计数）。
  • 超出边界：范围必须在工作表边界内。
  • 交叉组：新组不能与现有组交叉。
  • 最大深度：分组有最大嵌套深度限制。

取消分组的范围需完全包含分组范围，否则会验证失败。

如果验证失败，命令将不会执行，错误将通过 SheetsOutlineErrorService 发出。

你觉得这篇文档如何？

© 2026 DreamNum Co., Ltd.