차트

Headless 지원

차트는 차트 모델과 UI 패키지로 워크시트 데이터를 시각화합니다.

플러그인 모드

Shell
pnpm add @univerjs-pro/chart-ui @univerjs-pro/sheets-chart @univerjs-pro/sheets-chart-ui
TypeScript
import ChartUIKoKR from '@univerjs-pro/chart-ui/locale/ko-KR'import { UniverSheetsChartPlugin } from '@univerjs-pro/sheets-chart'import { UniverSheetsChartUIPlugin } from '@univerjs-pro/sheets-chart-ui'import SheetsChartUIKoKR from '@univerjs-pro/sheets-chart-ui/locale/ko-KR'import SheetsChartKoKR from '@univerjs-pro/sheets-chart/locale/ko-KR'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.KO_KR,  locales: {    [LocaleType.KO_KR]: mergeLocales(ChartUIKoKR, SheetsChartKoKR, SheetsChartUIKoKR),  },})univer.registerPlugin(UniverSheetsChartPlugin)univer.registerPlugin(UniverSheetsChartUIPlugin)

모바일 지원

먼저 모바일 에디터를 구성하세요. 이 페이지의 플러그인 모드 초기화 코드에서 아래 데스크톱 등록을 같은 패키지의 모바일 버전으로 바꾸고 문서를 열기 전에 완료하세요. 모델 플러그인, 스타일, 언어 파일과 Facade 가져오기는 유지하며 두 버전을 동시에 등록하지 마세요.

패키지데스크톱 등록모바일 등록
@univerjs-pro/sheets-chart-uiUniverSheetsChartUIPluginUniverSheetsChartMobileUIPlugin

프리셋 모드

차트 기능은 @univerjs/preset-sheets-advanced에 포함되며 런타임에는 drawing 프리셋이 필요합니다.

Shell
pnpm add @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced
TypeScript
import { UniverSheetsAdvancedPreset } from '@univerjs/preset-sheets-advanced'import UniverPresetSheetsAdvancedKoKR from '@univerjs/preset-sheets-advanced/locales/ko-KR'import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'import UniverPresetSheetsCoreKoKR from '@univerjs/preset-sheets-core/locales/ko-KR'import { UniverSheetsDrawingPreset } from '@univerjs/preset-sheets-drawing'import UniverPresetSheetsDrawingKoKR from '@univerjs/preset-sheets-drawing/locales/ko-KR'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.KO_KR,  locales: {    [LocaleType.KO_KR]: mergeLocales(      UniverPresetSheetsCoreKoKR,      UniverPresetSheetsDrawingKoKR,      UniverPresetSheetsAdvancedKoKR,    ),  },  presets: [UniverSheetsCorePreset(), UniverSheetsDrawingPreset(), UniverSheetsAdvancedPreset()],})

차트 만들기와 업데이트

worksheet.newChart(type)는 분리된 빌더를 만듭니다. build() 결과를 worksheet.insertChart(info)에 전달하기 전까지 워크시트에는 아무것도 추가되지 않습니다.

TypeScript
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)로 등록합니다.

다단계 범주 축

인접한 원본 열이 계층을 이룰 때는 루트에서 리프 순서로 0부터 시작하는 인덱스를 setCategoryFields()에 전달하고 다단계 축을 활성화합니다.

TypeScript
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 참조를 확인하세요.

숨겨진 데이터와 독립 범주

setPlotVisibleOnly(false)는 숨겨진 행과 열의 값을 포함하고 getPlotVisibleOnly()는 설정을 읽습니다. setSeriesToCategory()는 값 필드 인덱스를 범주 필드 인덱스에 연결합니다. 인덱스는 원본 벡터를 기준으로 하며 표시 계열 필터링에 따라 바뀌지 않습니다. 생략한 항목은 공통 범주를 사용하고 {}는 재정의를 지웁니다.

A:D 데이터에서 D 값 계열은 C를 범주로 사용하고 B는 공통 범주 A를 계속 사용할 수 있습니다.

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

집계 보고서는 피벗 차트를 참고하세요.

3D 차트

3D 차트는 동일한 차트 플러그인 등록 구성을 사용합니다. 3D 유형을 선택한 후 독립 빌더에서 시점을 설정합니다.

지원 유형은 Line3D, Column3D, ColumnStacked3D, ColumnPercentStacked3D, Bar3D, BarStacked3D, BarPercentStacked3D, Pie3D, Area3D, AreaStacked3D, AreaPercentStacked3D입니다.

TypeScript
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()는 3D 유형과 깊이 축을 유지한 채 사용자 지정 뷰 설정을 지웁니다. 깊이 축은 clearDepthAxis()로 지웁니다. 3D 축 차트에는 보조 축이나 추세선 API가 없으며 Pie3D는 구멍이 없는 원형 차트입니다.

로그 값 축

2D 꺾은선, 영역, 세로 막대, 가로 막대 및 조합 차트의 숫자 축에 scaleType: 'log'를 설정할 수 있습니다. 세로 숫자 축은 setYAxis(), 가로 막대 차트의 가로 숫자 축은 setXAxis()를 사용합니다. setRightYAxis()는 기존 보조 숫자 축을 설정합니다.

기본 밑은 10입니다. logBase는 2~1000의 유한한 수이며 2.5 같은 소수도 허용합니다. 축 경계는 양수여야 합니다. 0과 음수 데이터 점은 원본을 변경하지 않고 로그 플롯에서 제외됩니다. 백분율 누적 차트와 3D 차트는 로그 축을 지원하지 않습니다.

TypeScript
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'는 로그 밑을 제거하고, 다른 축 속성 수정은 기존 배율을 유지합니다.

이 가이드는 어떠셨나요?

© 2026 DreamNum Co., Ltd.