# 圖表

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

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

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

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

---

#### Package metadata

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

## 註冊圖表支援

投影片圖表由模型套件和 UI 套件組成；`@univerjs-pro/chart-ui` 為圖表 UI 提供共用控制項、語言套件和樣式。

```ts
import ChartUIZhTW from '@univerjs-pro/chart-ui/locale/zh-TW'
import { UniverSlidesChartPlugin } from '@univerjs-pro/slides-chart'
import { UniverSlidesChartUIPlugin } from '@univerjs-pro/slides-chart-ui'
import SlidesChartUIZhTW from '@univerjs-pro/slides-chart-ui/locale/zh-TW'
import { LocaleType, mergeLocales } from '@univerjs/core'
import '@univerjs-pro/chart-ui/facade'
import '@univerjs-pro/chart-ui/lib/index.css'
import '@univerjs-pro/slides-chart-ui/lib/index.css'
import '@univerjs-pro/slides-chart/facade'

univerAPI.loadLocales(LocaleType.ZH_TW, mergeLocales(ChartUIZhTW, SlidesChartUIZhTW))
univer.registerPlugin(UniverSlidesChartPlugin)
univer.registerPlugin(UniverSlidesChartUIPlugin)
```

開啟或匯入可能含有圖表元素的簡報前，請先註冊圖表支援。

## 行動裝置支援

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

| 套件                              | 桌面版註冊                       | 行動版註冊                             |
| ------------------------------- | --------------------------- | --------------------------------- |
| `@univerjs-pro/slides-chart-ui` | `UniverSlidesChartUIPlugin` | `UniverSlidesChartMobileUIPlugin` |

## 建立及更新圖表

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

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

const slide = presentation.getActiveSlide()
const info = slide
  .newChart(univerAPI.Enum.ChartTypeString.Column)
  .setSource([
    ['Month', 'Revenue', 'Cost'],
    ['Jan', 120, 80],
    ['Feb', 180, 96],
    ['Mar', 240, 132],
  ])
  .setTitle('Quarterly revenue')
  .setAbsolutePosition(80, 120)
  .setSize(520, 320)
  .setZOrder(1)
  .build()

const chart = await slide.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`。

使用 `slide.getCharts()` 與 `slide.getChart(id)` 取得即時圖表。需要刪除時呼叫 `await chart.remove()`。Slides 建構器另外提供 `setPlaceholder()`、`setStroke()` 與 `setZOrder()`。

## 多層級分類軸

對於內嵌層級資料，請依根節點到葉節點的順序選取分類欄位，並啟用多層級算繪：

```ts
const info = slide
  .newChart(univerAPI.Enum.ChartTypeString.Column)
  .setSource([
    ['Region', 'Quarter', 'Revenue'],
    ['North', 'Q1', 120],
    ['North', 'Q2', 148],
    ['South', 'Q1', 98],
    ['South', 'Q2', 132],
  ])
  .setCategoryFields([0, 1])
  .setMultiLevelCategoryAxis(true)
  .setValueFields([2])
  .setAbsolutePosition(80, 120)
  .setSize(520, 320)
  .build()

await slide.insertChart(info)
```

## 綁定 Sheet 資料

引用其他文件的圖表資料需要 [`UniverChartEmbedPlugin`](https://docs.univer.ai/zh-TW/reference/packages/plugins/univerjs-pro/chart-embed.md)。安裝後，請在開啟簡報前的初始化階段註冊一次。若需明確設定 `UniverEmbedPlugin`，請先註冊該外掛。行動端使用相同設定；內嵌陣列資料不需要此外掛。

#### npm

```bash
npm install @univerjs-pro/chart-embed
```

#### pnpm

```bash
pnpm add @univerjs-pro/chart-embed
```

#### yarn

```bash
yarn add @univerjs-pro/chart-embed
```

#### bun

```bash
bun add @univerjs-pro/chart-embed
```

```ts
import { UniverChartEmbedPlugin } from '@univerjs-pro/chart-embed'

univer.registerPlugin(UniverChartEmbedPlugin)
```

若圖表需要跟隨 Sheet 範圍而非儲存值副本，請將資源參照傳給 `setSource()`：

```ts
const info = slide
  .newChart(univerAPI.Enum.ChartTypeString.Column)
  .setSource({
    unit: { selector: 'sales-workbook', type: 'sheet' },
    part: {
      kind: 'range',
      sheetName: 'Data',
      range: 'A1:B20',
      ref: 'Data!A1:B20',
    },
  })
  .setAbsolutePosition(120, 80)
  .setSize(640, 360)
  .build()

const chart = await slide.insertChart(info)
```

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

共享建構器也支援[三維圖表設定](https://docs.univer.ai/zh-TW/guides/sheets/features/charts.md#three-dimensional-charts)和[對數數值軸](https://docs.univer.ai/zh-TW/guides/sheets/features/charts.md#logarithmic-axes)。在投影片中沿用本頁的 `slide.newChart()`，傳入內嵌資料或文件資料參照。