Web SDK

群組

群組功能（也稱為大綱或維度大綱）允許您在試算表中對列或欄進行群組。這對於透過建立可摺疊的區塊來組織和彙總大量資料非常有用。

簡介

在 Univer Sheets 中，群組功能使您能夠：

  • 對列或欄進行群組：建立列或欄的層級群組以組織資料。
  • 摺疊和展開群組：透過點選顯示或隱藏群組的列或欄。
  • 巢狀群組：建立多個層級的群組以支援複雜的資料層次結構。

群組功能通常用於以下場景：

  • 彙總詳細資料：將詳細列歸到彙總列下，以建立更清晰的檢視。
  • 組織大型資料集：將相關的欄或列組合在一起，便於導覽。
  • 建立可摺疊報表：允許使用者根據需要展開或摺疊報表的各個部分。

外掛模式

安裝

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 SheetsOutlineUIZhTW from '@univerjs-pro/sheets-outline-ui/locale/zh-TW'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_TW,  locales: {    [LocaleType.ZH_TW]: mergeLocales(      SheetsOutlineUIZhTW,     ),  },})univer.registerPlugin(UniverSheetsOutlinePlugin)univer.registerPlugin(UniverSheetsOutlineUIPlugin)

如果您擁有 Univer 的商業授權，請參閱在用戶端中使用授權進行配置。

行動裝置支援

先設定行動版編輯器。在本頁外掛模式的初始化程式碼中，將下列桌面版註冊替換為同一套件匯出的行動版外掛，並在開啟文件前完成。保留模型外掛、樣式、語言套件與 Facade 匯入，請勿同時註冊兩個版本。

套件桌面版註冊行動版註冊
@univerjs-pro/sheets-outline-uiUniverSheetsOutlineUIPluginUniverSheetsOutlineMobileUIPlugin

預設模式

群組功能包含在 @univerjs/preset-sheets-advanced 預設中。

安裝

Shell
pnpm add @univerjs/preset-sheets-advanced

使用

TypeScript
import { UniverSheetsAdvancedPreset } from '@univerjs/preset-sheets-advanced'import UniverPresetSheetsAdvancedZhTW from '@univerjs/preset-sheets-advanced/locales/zh-TW'import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'import UniverPresetSheetsCoreZhTW from '@univerjs/preset-sheets-core/locales/zh-TW'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_TW,  locales: {    [LocaleType.ZH_TW]: mergeLocales(      UniverPresetSheetsCoreZhTW,      UniverPresetSheetsAdvancedZhTW,     ),  },  presets: [    UniverSheetsCorePreset(),    UniverSheetsAdvancedPreset(),   ],})

如果您擁有 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.