# 차트

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

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

- Requested language: `ko-KR`

- Content language: `ko-KR`

- Documentation version: `1.0.4`

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

---

#### Package metadata

```json
{
  "mobile": true,
  "preset": [],
  "plugins": [
    {
      "client": "@univerjs-pro/chart-ui",
      "locale": "@univerjs-pro/chart-ui/locale/ko-KR",
      "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/ko-KR",
      "style": "@univerjs-pro/slides-chart-ui/lib/index.css"
    }
  ],
  "license": true,
  "server": false
}
```

## 차트 지원 등록

슬라이드 차트는 모델 패키지와 UI 패키지로 구성됩니다. `@univerjs-pro/chart-ui`는 공용 편집 컨트롤, 로캘, 스타일을 제공합니다.

```ts
import ChartUIKoKR from '@univerjs-pro/chart-ui/locale/ko-KR'
import { UniverSlidesChartPlugin } from '@univerjs-pro/slides-chart'
import { UniverSlidesChartUIPlugin } from '@univerjs-pro/slides-chart-ui'
import SlidesChartUIKoKR from '@univerjs-pro/slides-chart-ui/locale/ko-KR'
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.KO_KR, mergeLocales(ChartUIKoKR, SlidesChartUIKoKR))
univer.registerPlugin(UniverSlidesChartPlugin)
univer.registerPlugin(UniverSlidesChartUIPlugin)
```

차트 요소를 포함할 수 있는 프레젠테이션을 열거나 가져오기 전에 차트 지원을 등록하세요.

## 모바일 지원

먼저 [모바일 에디터](https://docs.univer.ai/ko-KR/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/ko-KR/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)
```

공유 차트 설정은 [Chart Facade 참고 문서](https://docs.univer.ai/ko-KR/reference/facade/chart.md)를 확인하세요.