SpreadJS로 웹에서 차트 구현하는 방법: addChart() 실전 가이드
웹 앱에 스프레드시트 기능을 추가할 때 '차트까지 넣어야 한다'는 요구사항을 받으면 대부분 Chart.js나 ECharts를 별도로 설치하고 데이터를 두 곳에서 동기화하는 작업을 반복하게 됩니다. SpreadJS는 JavaScript 기반 스프레드시트 컴포넌트로, Bar·Line·Pie를 비롯한 30종 이상의 차트 타입과 셀 내 미니 차트인 스파크라인(Line/Column/WinLoss)을 외부 라이브러리 없이 단일 패키지 안에 모두 내장하고 있습니다.
SpreadJS의 가장 큰 차별점은 스프레드시트 데이터와 차트가 같은 컴포넌트 안에서 직접 연결된다는 점입니다. setValue()
로 셀 값을 바꾸면 별도 갱신 코드 없이 차트가 즉시 다시 그려지고, 콤보 차트나 보조 Y축처럼 복잡한 구성도 메서드 몇 줄로 처리됩니다. React·Vue·Angular·Vanilla JS 환경 모두에서 동일하게 동작합니다.
이 글에서는 addChart()
API로 기본 차트를 삽입하는 것부터 시작해, 스파크라인 세 가지 타입 구현, 콤보 차트의 보조 Y축 설정, 셀 변경 이벤트 연동, PDF 내보내기까지 실전 코드와 함께 단계별로 안내합니다.

워크시트에 차트를 삽입하는 방법 — addChart()
API로 Bar·Line·Pie 구현하기
SpreadJS 차트는 sheet.charts.add()
한 메서드 호출로 워크시트에 즉시 올릴 수 있습니다. 데이터 범위를 지정하면 이후 셀 값이 바뀔 때마다 차트가 자동으로 갱신됩니다.
메서드 시그니처:
| 파라미터 | 타입 | 설명 |
|---|---|---|
name
|
string | 차트 고유 이름 |
chartType
|
ChartType | GC.Spread.Sheets.Charts.ChartType.*
|
x, y
|
number | 차트 좌상단 위치(픽셀) |
width, height
|
number | 차트 크기(픽셀) |
dataRange
|
string | "A1:D5"
형태 셀 범위 |
rowCol
|
RowCol | 데이터 방향 — rows
또는 columns
|
차트 플러그인 스크립트를 별도로 로드해야 합니다.
STEP 1: CDN 참조
STEP 2: HTML 구조
STEP 3: 묶음 세로 막대 차트 삽입
ChartType
열거형에는 columnClustered
, barClustered
, line
, lineMarkers
, pie
, doughnut
, xyScatter
, area
, treemap
, waterfall
, funnel
등 30종 이상이 포함됩니다. 타입 하나만 바꾸면 동일 데이터로 다른 차트를 즉시 확인할 수 있습니다.
셀 안에 미니 차트를 그리는 방법 — 스파크라인 Line·Column·WinLoss 구현하기
스파크라인은 단일 셀 안에 미니 차트를 그리는 기능입니다. 테이블 행 끝에 트렌드 시각화를 붙이는 대시보드 패턴에 특히 유용합니다.
DataOrientation.Horizontal
(대문자 H)는 undefined
를 반환해 데이터를 읽지 못합니다. 반드시 소문자 horizontal
/ vertical
을 사용하세요. 이 버그는 화면에 단일 포인트만 렌더링되는 현상으로 나타납니다.STEP 2: HTML
STEP 3: Line·Column·WinLoss 동시 구현
1
/ -1
로 변환한 별도 행을 준비해야 합니다.
setColumnWidth(c, 0)
으로 숨기면 스파크라인이 해당 데이터를 읽지 못합니다. 숨겨야 할 보조 데이터는 별도 시트에 저장하고 크로스시트 문자열 범위( 'DataSheet!A1:L1'
)로 참조하세요.Bar와 Line을 한 차트에 — 콤보 차트와 보조 Y축 설정하는 방법
매출(Bar, 단위: 만원)과 성장률(Line, 단위: %)처럼 척도가 다른 두 지표를 한 차트에 넣을 때 콤보 차트가 필요합니다. SpreadJS는 chart.series().add()
로 시리즈마다 다른 chartType
을 지정하여 콤보 차트를 구현합니다.
STEP 2: HTML
STEP 3: Bar + Line 콤보 — 보조 Y축
axisGroup: GC.Spread.Sheets.Charts.AxisGroup.secondary
를 지정하면 해당 시리즈가 오른쪽 보조 Y축에 매핑됩니다. 단위가 전혀 다른 두 지표를 한 차트에 표시할 때 반드시 설정해야 시각적으로 올바르게 해석됩니다.

셀 데이터가 바뀌면 차트도 자동 갱신 — CellChanged 이벤트 활용하기
SpreadJS 차트는 dataRange
로 지정된 셀과 직접 연결되어 있습니다. setValue()
로 데이터를 바꾸는 순간 별도 갱신 코드 없이 차트가 즉시 재렌더링됩니다. CellChanged
이벤트는 변경 감지 후 추가 UI 로직(상태 메시지, 합계 재계산 등)을 연결할 때 활용합니다.
STEP 2: HTML
STEP 3: 버튼 입력 → 셀 값 변경 → 차트 자동 갱신
dataRange
셀 범위에 대한 내부 관찰자(observer)로 구현됩니다. bind(CellChanged, ...)
는 선택 사항이며, 차트 갱신과는 독립적으로 추가 UI 처리에만 사용합니다.차트를 PDF로 내보내는 방법 — 인쇄 레이아웃 최적화하기
SpreadJS는 차트가 포함된 시트를 PDF로 클라이언트 측에서 직접 내보낼 수 있습니다. 서버 렌더링 없이 브라우저에서 처리하므로 백엔드 구현이 필요 없습니다.
STEP 2: HTML
STEP 3: PDF 내보내기
printInfo()
로 인쇄 방향( landscape
/ portrait
), 격자선 표시 여부, 페이지 맞춤( fitPagesWide
)을 설정합니다. 차트가 포함된 보고서는 가로 방향( landscape
) + fitPagesWide(1)
로 지정하면 차트가 한 페이지에 깔끔하게 맞습니다.GC.Spread.Sheets.PDF.PDFFontsManager.registerFont()
로 NanumGothic TTF를 등록해야 합니다. savePDF()
호출 전 폰트 로드를 완료( await fontPromise
)하는 패턴이 필수입니다.개발자가 자주 묻는 질문
SpreadJS에서 워크시트에 차트를 삽입하려면 어떤 API를 사용하나요?
sheet.charts.add(name, ChartType, x, y, width, height, dataRange, rowCol)
메서드 한 줄로 원하는 타입의 차트를 워크시트에 올릴 수 있습니다. 사전에 gc.spread.sheets.charts.19.0.6.min.js
플러그인을 반드시 로드해야 합니다.
웹 스프레드시트에서 셀 안에 스파크라인을 표시하려면 어떻게 하나요?
sheet.setSparkline(row, col, dataRange, DataOrientation, SparklineType, setting)
을 사용합니다. 타입으로 line
, column
, winloss
세 가지를 지원하며, DataOrientation
은 반드시 소문자( horizontal
/ vertical
)로 지정해야 합니다.
SpreadJS 콤보 차트에서 Bar와 Line을 함께 쓸 때 보조 Y축을 추가하는 방법이 있나요?
chart.series().add()
호출 시 시리즈 객체에 axisGroup: GC.Spread.Sheets.Charts.AxisGroup.secondary
를 지정하면 해당 시리즈가 오른쪽 보조 Y축에 독립적으로 스케일됩니다.
SpreadJS에서 셀 값이 바뀌면 연결된 차트도 자동으로 갱신되나요?
네, 가능합니다. SpreadJS 차트는 dataRange
로 지정된 셀 범위와 직접 연결되어 있어, setValue()
등으로 셀 값을 변경하면 별도 갱신 코드 없이 차트가 즉시 다시 렌더링됩니다.
SpreadJS 차트가 포함된 시트를 PDF 파일로 내보낼 수 있나요?
가능합니다. spread.savePDF()
로 차트가 포함된 시트를 클라이언트 측에서 바로 PDF로 내보낼 수 있습니다. 인쇄 영역과 용지 방향 등은 printInfo()
API로 세밀하게 제어할 수 있습니다.
