# 群組

- Human documentation: [https://docs.univer.ai/zh-TW/guides/sheets/features/outline](https://docs.univer.ai/zh-TW/guides/sheets/features/outline)

- Agent Markdown: [https://docs.univer.ai/zh-TW/guides/sheets/features/outline.md](https://docs.univer.ai/zh-TW/guides/sheets/features/outline.md)

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

- Source: [sheets/features/outline.zh-TW.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/sheets/features/outline.zh-TW.mdx)

---

#### Package metadata

```json
{
  "mobile": true,
  "preset": [
    {
      "client": "@univerjs/preset-sheets-advanced",
      "locale": "@univerjs/preset-sheets-advanced/locales/zh-TW",
      "style": "@univerjs/preset-sheets-advanced/lib/index.css"
    }
  ],
  "plugins": [
    {
      "client": "@univerjs-pro/sheets-outline",
      "facade": "@univerjs-pro/sheets-outline/facade"
    },
    {
      "client": "@univerjs-pro/sheets-outline-ui",
      "locale": "@univerjs-pro/sheets-outline-ui/locale/zh-TW",
      "style": "@univerjs-pro/sheets-outline-ui/lib/index.css"
    }
  ],
  "license": true,
  "server": false
}
```

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

## 簡介

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

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

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

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

> Interactive example: [Open the playground](/playground/sheets/outline)

## 外掛模式

### 安裝

#### npm

```bash
npm install @univerjs-pro/sheets-outline @univerjs-pro/sheets-outline-ui
```

#### pnpm

```bash
pnpm add @univerjs-pro/sheets-outline @univerjs-pro/sheets-outline-ui
```

#### yarn

```bash
yarn add @univerjs-pro/sheets-outline @univerjs-pro/sheets-outline-ui
```

#### bun

```bash
bun add @univerjs-pro/sheets-outline @univerjs-pro/sheets-outline-ui
```

### 使用

```typescript
import { UniverSheetsOutlinePlugin } from '@univerjs-pro/sheets-outline' // [!code ++]
import { UniverSheetsOutlineUIPlugin } from '@univerjs-pro/sheets-outline-ui' // [!code ++]
import SheetsOutlineUIZhTW from '@univerjs-pro/sheets-outline-ui/locale/zh-TW' // [!code ++]
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'

import '@univerjs-pro/sheets-outline/facade' // [!code ++]

import '@univerjs-pro/sheets-outline-ui/lib/index.css' // [!code ++]

const univer = new Univer({
  locale: LocaleType.ZH_TW,
  locales: {
    [LocaleType.ZH_TW]: mergeLocales(
      SheetsOutlineUIZhTW, // [!code ++]
    ),
  },
})

univer.registerPlugin(UniverSheetsOutlinePlugin)
univer.registerPlugin(UniverSheetsOutlineUIPlugin)
```

如果您擁有 Univer 的商業授權，請參閱[在用戶端中使用授權](https://docs.univer.ai/zh-TW/server/license.md#in-plugin-mode)進行配置。

## 行動裝置支援

先設定[行動版編輯器](https://docs.univer.ai/zh-TW/guides/sheets/getting-started/installation.md#mobile-support)。在本頁外掛模式的初始化程式碼中，將下列桌面版註冊替換為同一套件匯出的行動版外掛，並在**開啟文件前**完成。保留模型外掛、樣式、語言套件與 Facade 匯入，請勿同時註冊兩個版本。

| 套件                                | 桌面版註冊                         | 行動版註冊                               |
| --------------------------------- | ----------------------------- | ----------------------------------- |
| `@univerjs-pro/sheets-outline-ui` | `UniverSheetsOutlineUIPlugin` | `UniverSheetsOutlineMobileUIPlugin` |

## 預設模式

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

### 安裝

#### npm

```bash
npm install @univerjs/preset-sheets-advanced
```

#### pnpm

```bash
pnpm add @univerjs/preset-sheets-advanced
```

#### yarn

```bash
yarn add @univerjs/preset-sheets-advanced
```

#### bun

```bash
bun add @univerjs/preset-sheets-advanced
```

### 使用

```typescript
import { UniverSheetsAdvancedPreset } from '@univerjs/preset-sheets-advanced' // [!code ++]
import UniverPresetSheetsAdvancedZhTW from '@univerjs/preset-sheets-advanced/locales/zh-TW' // [!code ++]
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' // [!code ++]

const { univerAPI } = createUniver({
  locale: LocaleType.ZH_TW,
  locales: {
    [LocaleType.ZH_TW]: mergeLocales(
      UniverPresetSheetsCoreZhTW,
      UniverPresetSheetsAdvancedZhTW, // [!code ++]
    ),
  },
  presets: [
    UniverSheetsCorePreset(),
    UniverSheetsAdvancedPreset(), // [!code ++]
  ],
})
```

如果您擁有 Univer 的商業授權，請參閱[在用戶端中使用授權](https://docs.univer.ai/zh-TW/server/license.md#in-preset-mode)進行配置。

## Facade API

完整 Facade API 類型定義，請查看 [FacadeAPI](https://docs.univer.ai/zh-TW/reference/facade/univer.md)。

### 導入

> [!INFO: 外掛模式提示]
> 僅外掛模式需要手動引入 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()
```

## 群組資料結構

每個群組具有以下屬性：

| 屬性          | 類型                     | 說明                     |
| ----------- | ---------------------- | ---------------------- |
| `id`        | `string`               | 群組的唯一識別碼               |
| `unitId`    | `string`               | 活頁簿單元 ID               |
| `subUnitId` | `string`               | 工作表 ID                 |
| `axis`      | `DimensionOutlineAxis` | 群組的軸（`row` 或 `column`） |
| `start`     | `number`               | 從 0 開始的包含起始索引          |
| `end`       | `number`               | 從 0 開始的包含結束索引          |
| `collapsed` | `boolean`              | 群組目前是否摺疊               |

## 驗證與錯誤

建立群組時，會執行以下驗證：

* **無效範圍**：範圍必須有效（非負數、非零計數）。
* **超出邊界**：範圍必須在工作表邊界內。
* **交叉群組**：新群組不能與現有群組交叉。
* **最大深度**：群組有最大巢狀深度限制。

取消群組的範圍需完全包含群組範圍，否則會驗證失敗。

如果驗證失敗，命令將不會執行，錯誤將透過 `SheetsOutlineErrorService` 發出。