# 圖表

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

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

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

- Source: [sheets/features/charts.zh-TW.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/sheets/features/charts.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/chart-ui",
      "locale": "@univerjs-pro/chart-ui/locale/zh-TW",
      "style": "@univerjs-pro/chart-ui/lib/index.css"
    },
    {
      "client": "@univerjs-pro/sheets-chart",
      "locale": "@univerjs-pro/sheets-chart/locale/zh-TW",
      "facade": "@univerjs-pro/sheets-chart/facade"
    },
    {
      "client": "@univerjs-pro/sheets-chart-ui",
      "locale": "@univerjs-pro/sheets-chart-ui/locale/zh-TW",
      "style": "@univerjs-pro/sheets-chart-ui/lib/index.css"
    }
  ],
  "license": true,
  "server": false
}
```

圖表會將工作表資料視覺化，並使用圖表模型及 UI 套件。

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

## 外掛模式

#### npm

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

#### pnpm

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

#### yarn

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

#### bun

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

```ts
import ChartUIZhTW from '@univerjs-pro/chart-ui/locale/zh-TW'
import { UniverSheetsChartPlugin } from '@univerjs-pro/sheets-chart'
import { UniverSheetsChartUIPlugin } from '@univerjs-pro/sheets-chart-ui'
import SheetsChartUIZhTW from '@univerjs-pro/sheets-chart-ui/locale/zh-TW'
import SheetsChartZhTW from '@univerjs-pro/sheets-chart/locale/zh-TW'
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'
import '@univerjs-pro/chart-ui/facade'
import '@univerjs-pro/sheets-chart/facade'
import '@univerjs-pro/chart-ui/lib/index.css'
import '@univerjs-pro/sheets-chart-ui/lib/index.css'

const univer = new Univer({
  locale: LocaleType.ZH_TW,
  locales: {
    [LocaleType.ZH_TW]: mergeLocales(ChartUIZhTW, SheetsChartZhTW, SheetsChartUIZhTW),
  },
})

univer.registerPlugin(UniverSheetsChartPlugin)
univer.registerPlugin(UniverSheetsChartUIPlugin)
```

## 行動裝置支援

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

| 套件                              | 桌面版註冊                       | 行動版註冊                             |
| ------------------------------- | --------------------------- | --------------------------------- |
| `@univerjs-pro/sheets-chart-ui` | `UniverSheetsChartUIPlugin` | `UniverSheetsChartMobileUIPlugin` |

## 預設模式

圖表功能包含在 `@univerjs/preset-sheets-advanced`，執行時需要繪圖預設。

#### npm

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

#### pnpm

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

#### yarn

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

#### bun

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

```ts
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 { UniverSheetsDrawingPreset } from '@univerjs/preset-sheets-drawing'
import UniverPresetSheetsDrawingZhTW from '@univerjs/preset-sheets-drawing/locales/zh-TW'
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'
import '@univerjs/preset-sheets-advanced/lib/index.css'
import '@univerjs/preset-sheets-core/lib/index.css'
import '@univerjs/preset-sheets-drawing/lib/index.css'

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

## 建立及更新圖表

`worksheet.newChart(type)` 建立的是獨立建構器。只有將 `build()` 的結果傳給 `worksheet.insertChart(info)` 後，圖表才會插入工作表。

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

const worksheet = workbook.getActiveSheet()
const info = worksheet
  .newChart(univerAPI.Enum.ChartTypeString.Column)
  .setSource({
    range: 'A1:D6',
    orientation: univerAPI.Enum.ChartSourceOrientation.Columns,
  })
  .setPosition('F2')
  .setSize(640, 360)
  .setCategoryField(0)
  .setValueFields([1, 2, 3])
  .setTitle('Quarterly revenue')
  .build()

const chart = await worksheet.insertChart(info)
chart.setLegend({ visible: true }).bringToFront()

const updatedInfo = chart.toBuilder(univerAPI.Enum.ChartTypeString.Line).setSubtitle('FY 2026').build()
await chart.update(updatedInfo)

const svg = await chart.exportImage({ format: 'svg' })
```

對已插入的 `chart` 呼叫 setter 會立即更新圖表。需要完整的獨立副本或切換類型時，請搭配使用 `toBuilder(type)` 與 `update(info)`。若目前沒有可產生圖片的 UI 算繪器，`exportImage()` 會傳回 `undefined`。

使用 `worksheet.getCharts()` 與 `worksheet.getChart(id)` 取得即時圖表。需要刪除時呼叫 `await chart.remove()`，共用 ECharts 主題則透過 `univerAPI.registerTheme(name, theme)` 註冊。

## 多層級分類軸

當相鄰資料欄組成層級關係時，請依根節點到葉節點的順序，將從零開始的欄索引傳給 `setCategoryFields()`，並啟用多層級分類軸。

```ts
const info = worksheet
  .newChart(univerAPI.Enum.ChartTypeString.Column)
  .setSource({
    range: 'A1:D7',
    orientation: univerAPI.Enum.ChartSourceOrientation.Columns,
  })
  .setCategoryFields([0, 1])
  .setMultiLevelCategoryAxis(true)
  .setValueFields([2, 3])
  .setPosition('F2')
  .build()

const chart = await worksheet.insertChart(info)
chart.setCategoryFields([0, 1]).setMultiLevelCategoryAxis(true)
```

呼叫 `clearCategoryFields()` 可移除有序分類對應。`setMultiLevelCategoryAxis(false)` 只會關閉層級算繪，並保留已選取的欄位。

## 支援的圖表類型

透過 `univerAPI.Enum.ChartTypeString` 使用 `Line`、`Column`、`ColumnStacked`、`ColumnPercentStacked`、`Bar`、`BarStacked`、`BarPercentStacked`、`Pie`、`Donut`、`Area`、`AreaStacked`、`AreaPercentStacked`、`Radar`、`Scatter`、`Combination`、`WordCloud`、`Funnel`、`Bubble`、`Relation`、`Waterfall`、`Pareto`、`Sankey`、`Heatmap`、`Boxplot`、`Candlestick`、`Histogram`、`Treemap`、`Sunburst`、`Gauge` 與 `Chord`。

共用建構器設定請參閱[圖表 Facade 參考](https://docs.univer.ai/zh-TW/reference/facade/chart.md)。

## 隱藏資料與獨立分類

`setPlotVisibleOnly(false)` 包含隱藏列欄中的值，`getPlotVisibleOnly()` 可讀取設定。`setSeriesToCategory()` 將各值欄位索引對應至分類欄位索引。索引指向原始來源向量，不因可見數列篩選而重新編號。未指定項繼承共用分類，`{}` 清除覆寫。

例如來源為 A:D 時，D 欄值數列可使用 C 欄分類，B 欄繼續使用共用的 A 欄分類。

```ts
const chart = worksheet.getCharts()[0]
if (!chart) throw new Error('No chart')
chart.setPlotVisibleOnly(false)
chart.setSeriesToCategory({ 3: [2] })
```

聚合與互動式報表請參閱[樞紐分析圖](https://docs.univer.ai/zh-TW/guides/sheets/features/pivot-chart.md)。

## 三維圖表

三維圖表沿用相同的圖表外掛註冊設定。選擇三維類型後，透過獨立建構器設定視角。

支援的類型包括 `Line3D`、`Column3D`、`ColumnStacked3D`、`ColumnPercentStacked3D`、`Bar3D`、`BarStacked3D`、`BarPercentStacked3D`、`Pie3D`、`Area3D`、`AreaStacked3D` 和 `AreaPercentStacked3D`。

```ts
const info = worksheet
  .newChart(univerAPI.Enum.ChartTypeString.Column3D)
  .setSource('A1:C5')
  .setCategoryField(0)
  .setValueFields([1, 2])
  .setPosition('F18')
  .setSize(640, 360)
  .setThreeD({
    view: { rotX: 20, rotY: 30, rightAngleAxes: false, perspective: 30 },
    gapDepth: 120,
  })
  .build()

await worksheet.insertChart(info)
```

對帶有座標軸的圖表，只有 `rightAngleAxes: false` 時才套用 `perspective`。`clearThreeD()` 清除自訂三維檢視設定，但保留三維類型和深度軸；清除深度軸請使用 `clearDepthAxis()`。三維座標軸圖表不提供次座標軸或趨勢線，`Pie3D` 使用實心圓形圖。

## 對數數值軸

二維折線圖、區域圖、直條圖、橫條圖及組合圖的數值軸支援 `scaleType: 'log'`。縱向數值軸使用 `setYAxis()`；橫條圖的橫向數值軸使用 `setXAxis()`。`setRightYAxis()` 用於設定既有的次級數值軸。

預設底數為 `10`。自訂 `logBase` 必須是 `2` 到 `1000` 之間的有限數，也支援 `2.5` 等非整數；數值軸上下界必須為正。零和負數資料點不參與對數繪製，原始資料保持不變。百分比堆疊圖和三維圖表不支援對數軸。

```ts
const info = worksheet
  .newChart(univerAPI.Enum.ChartTypeString.Line)
  .setSource('A1:B5')
  .setYAxis({ scaleType: 'log', logBase: 10 })
  .setPosition('F36')
  .setSize(640, 360)
  .build()

const chart = await worksheet.insertChart(info)

await chart.update(
  chart.toBuilder(univerAPI.Enum.ChartTypeString.Line)
    .setYAxis({ scaleType: 'linear' })
    .build(),
)
```

新圖表需建構後插入；修改既有圖表時，透過 `await chart.update(builder.build())` 套用建構器結果。設定 `scaleType: 'linear'` 會移除對數底數；修改其他軸屬性會保留原有刻度。