# 樞紐分析圖

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

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

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

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

---

先註冊[樞紐分析表](https://docs.univer.ai/zh-TW/guides/sheets/features/pivot-table.md)與[圖表](https://docs.univer.ai/zh-TW/guides/sheets/features/charts.md)依賴，再於建立活頁簿前註冊以下兩個外掛。將 UI 語言包合併至 `locales`，並載入樣式。此功能需要 Pro 授權。

#### npm

```bash
npm install @univerjs-pro/sheets-pivot-chart @univerjs-pro/sheets-pivot-chart-ui
```

#### pnpm

```bash
pnpm add @univerjs-pro/sheets-pivot-chart @univerjs-pro/sheets-pivot-chart-ui
```

#### yarn

```bash
yarn add @univerjs-pro/sheets-pivot-chart @univerjs-pro/sheets-pivot-chart-ui
```

#### bun

```bash
bun add @univerjs-pro/sheets-pivot-chart @univerjs-pro/sheets-pivot-chart-ui
```

```ts
import { UniverSheetsPivotChartPlugin } from '@univerjs-pro/sheets-pivot-chart'
import { UniverSheetsPivotChartUIPlugin } from '@univerjs-pro/sheets-pivot-chart-ui'
import SheetsPivotChartLocale from '@univerjs-pro/sheets-pivot-chart-ui/locale/zh-TW'
import { LocaleType } from '@univerjs/core'

import '@univerjs-pro/sheets-pivot-chart/facade'
import '@univerjs-pro/sheets-pivot-chart-ui/lib/index.css'

univerAPI.loadLocales(LocaleType.ZH_TW, SheetsPivotChartLocale)

univer.registerPlugin(UniverSheetsPivotChartPlugin)
univer.registerPlugin(UniverSheetsPivotChartUIPlugin)
```

Sheets 進階預設已包含這兩個外掛。搭配核心及繪圖預設，並明確匯入 `@univerjs-pro/sheets-pivot-chart/facade` 以啟用以下 API。

## 獨立報表

此模式由圖表持有報表。插入後加入列欄位和值欄位；範例使用來源的前兩欄。

```ts
const workbook = univerAPI.getActiveWorkbook()
const sheet = workbook?.getActiveSheet()
if (!sheet) throw new Error('No active worksheet')

sheet.getRange('A1:B4').setValues([
  ['Region', 'Sales'], ['East', 100], ['West', 200], ['East', 50],
])
const chart = await sheet.insertPivotChart(
  sheet.newPivotChart(univerAPI.Enum.ChartTypeString.Column)
    .setSource('A1:B4').setPosition('D2').setSize(640, 360).build(),
)
const fields = chart.getSourceFieldsInfo()
await chart.addField(fields[0].id, univerAPI.Enum.PivotTableFiledAreaEnum.Row, 0)
await chart.addField(fields[1].id, univerAPI.Enum.PivotTableFiledAreaEnum.Value, 0)
```

## 連結樞紐分析表

欄位、篩選、排序及摺疊變更會同步至連結的樞紐分析表及其他連結圖表；外觀與位置各自獨立。刪除圖表不會刪除表格；刪除表格後圖表暫不可用，還原同一表格後重新連結。

```ts
const pivotTable = workbook.getPivotTableById('pivot-table-1')
if (!pivotTable) throw new Error('PivotTable not found')

const linkedChart = await sheet.insertPivotChart(
  pivotTable.newChart(univerAPI.Enum.ChartTypeString.Line).setPosition('D22').build(),
)
linkedChart.setFieldButtonsVisible(true).setExpandCollapseButtonsVisible(true)
```

## 支援類型與 Worker

支援折線、直條、橫條、面積、圓餅、環圈及組合圖，以及適用的堆疊類型。不支援散佈、泡泡、雷達及瀑布樞紐分析圖。圓餅圖使用第一個值數列，環圈圖保留多個數列。分類不包含小計與總計。

使用 [Worker](https://docs.univer.ai/zh-TW/guides/sheets/getting-started/worker.md) 時，主執行緒設定 `UniverSheetsAdvancedPreset({ useWorker: true })`，Worker 中設定 `UniverSheetsAdvancedWorkerPreset()`。外掛模式見[套件參考](https://docs.univer.ai/zh-TW/reference/packages/plugins/univerjs-pro/sheets-pivot-chart.md#worker-calculation)；完整 API 見 [FSheetPivotChart](https://docs.univer.ai/zh-TW/reference/facade/sheet-pivot-chart.md)。

## 複製與刪除工作表

複製工作表也會以新識別碼複製其中的樞紐分析圖。獨立報表的資料來源位於被複製的工作表時，副本會使用新工作表與獨立快取。連結的樞紐分析圖會指向隨工作表一起複製的樞紐分析表；對其他工作表的參照保持不變。刪除工作表會清除其中的樞紐分析圖及相關資源，復原可還原圖表定義與來源資料。