SpreadJS 블로그 MESCIUS 기술 블로그 ·

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 내보내기까지 실전 코드와 함께 단계별로 안내합니다.

⭐ Key Points
이 글에서 다루는 핵심 내용
01 SpreadJS에는 30종 이상 차트 타입과 스파크라인(Line/Column/WinLoss)이 별도 설치 없이 내장되어 있습니다
02 Chart.js·ECharts 불필요 — 스프레드시트 데이터와 차트를 하나의 컴포넌트로 통합 관리합니다
03 셀 값이 변경되면 차트가 자동 실시간 갱신 — 추가 이벤트 코드 없이 데이터 바인딩이 동작합니다
04 콤보 차트와 보조 Y축도 코드 몇 줄로 설정할 수 있습니다
SpreadJS로 웹에서 차트 구현하는 방법: addChart() 실전 가이드 — 대표 이미지
↗
30+
차트 타입
Bar·Line·Pie·Scatter·Combo·Treemap 등
↗
3가지
스파크라인
Line·Column·WinLoss 셀 내 미니 차트
↗
0개
추가 라이브러리
Chart.js·ECharts 없이 완결

워크시트에 차트를 삽입하는 방법 — 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: 묶음 세로 막대 차트 삽입

실행 결과
💡 TIP
ChartType 열거형에는 columnClustered , barClustered , line , lineMarkers , pie , doughnut , xyScatter , area , treemap , waterfall , funnel 등 30종 이상이 포함됩니다. 타입 하나만 바꾸면 동일 데이터로 다른 차트를 즉시 확인할 수 있습니다.
워크시트에 차트를 삽입하는 방법 — addChart() API로 Bar·Line·Pie 구현하기 — SpreadJS 개념도

셀 안에 미니 차트를 그리는 방법 — 스파크라인 Line·Column·WinLoss 구현하기

스파크라인은 단일 셀 안에 미니 차트를 그리는 기능입니다. 테이블 행 끝에 트렌드 시각화를 붙이는 대시보드 패턴에 특히 유용합니다.

⚠ WARNING
DataOrientation.Horizontal (대문자 H)는 undefined 를 반환해 데이터를 읽지 못합니다. 반드시 소문자 horizontal / vertical 을 사용하세요. 이 버그는 화면에 단일 포인트만 렌더링되는 현상으로 나타납니다.

STEP 2: HTML

STEP 3: Line·Column·WinLoss 동시 구현

실행 결과
ⓘ NOTE
WinLoss 스파크라인은 양수(+1)와 음수(-1) 값만 인식합니다. 실제 판매 데이터를 WinLoss로 시각화하려면 목표 달성 여부를 1 / -1 로 변환한 별도 행을 준비해야 합니다.
⭐ IMPORTANT
스파크라인 데이터가 있는 열을 setColumnWidth(c, 0) 으로 숨기면 스파크라인이 해당 데이터를 읽지 못합니다. 숨겨야 할 보조 데이터는 별도 시트에 저장하고 크로스시트 문자열 범위( 'DataSheet!A1:L1' )로 참조하세요.

Bar와 Line을 한 차트에 — 콤보 차트와 보조 Y축 설정하는 방법

매출(Bar, 단위: 만원)과 성장률(Line, 단위: %)처럼 척도가 다른 두 지표를 한 차트에 넣을 때 콤보 차트가 필요합니다. SpreadJS는 chart.series().add() 로 시리즈마다 다른 chartType 을 지정하여 콤보 차트를 구현합니다.

STEP 2: HTML

STEP 3: Bar + Line 콤보 — 보조 Y축

실행 결과
⭐ IMPORTANT
axisGroup: GC.Spread.Sheets.Charts.AxisGroup.secondary 를 지정하면 해당 시리즈가 오른쪽 보조 Y축에 매핑됩니다. 단위가 전혀 다른 두 지표를 한 차트에 표시할 때 반드시 설정해야 시각적으로 올바르게 해석됩니다.
⭐ BEST PRACTICE
콤보 차트 권장 조합: Bar(매출) + Line(성장률), Bar(계획) + Line(실적), Area(누적) + Line(목표). 시각적 혼란을 피하기 위해 세 가지 이상 타입 조합은 지양합니다.
Bar와 Line을 한 차트에 — 콤보 차트와 보조 Y축 설정하는 방법 — SpreadJS 개념도

셀 데이터가 바뀌면 차트도 자동 갱신 — CellChanged 이벤트 활용하기

SpreadJS 차트는 dataRange 로 지정된 셀과 직접 연결되어 있습니다. setValue() 로 데이터를 바꾸는 순간 별도 갱신 코드 없이 차트가 즉시 재렌더링됩니다. CellChanged 이벤트는 변경 감지 후 추가 UI 로직(상태 메시지, 합계 재계산 등)을 연결할 때 활용합니다.

STEP 2: HTML

STEP 3: 버튼 입력 → 셀 값 변경 → 차트 자동 갱신

실행 결과
ⓘ NOTE
SpreadJS 차트의 자동 갱신은 dataRange 셀 범위에 대한 내부 관찰자(observer)로 구현됩니다. bind(CellChanged, ...) 는 선택 사항이며, 차트 갱신과는 독립적으로 추가 UI 처리에만 사용합니다.

차트를 PDF로 내보내는 방법 — 인쇄 레이아웃 최적화하기

SpreadJS는 차트가 포함된 시트를 PDF로 클라이언트 측에서 직접 내보낼 수 있습니다. 서버 렌더링 없이 브라우저에서 처리하므로 백엔드 구현이 필요 없습니다.

STEP 2: HTML

STEP 3: PDF 내보내기

실행 결과
💡 TIP
printInfo() 로 인쇄 방향( landscape / portrait ), 격자선 표시 여부, 페이지 맞춤( fitPagesWide )을 설정합니다. 차트가 포함된 보고서는 가로 방향( landscape ) + fitPagesWide(1) 로 지정하면 차트가 한 페이지에 깔끔하게 맞습니다.
⚠ WARNING
PDF 내보내기에서 한글이 깨지는 경우 GC.Spread.Sheets.PDF.PDFFontsManager.registerFont() 로 NanumGothic TTF를 등록해야 합니다. savePDF() 호출 전 폰트 로드를 완료( await fontPromise )하는 패턴이 필수입니다.

개발자가 자주 묻는 질문

Q01

SpreadJS에서 워크시트에 차트를 삽입하려면 어떤 API를 사용하나요?

sheet.charts.add(name, ChartType, x, y, width, height, dataRange, rowCol) 메서드 한 줄로 원하는 타입의 차트를 워크시트에 올릴 수 있습니다. 사전에 gc.spread.sheets.charts.19.0.6.min.js 플러그인을 반드시 로드해야 합니다.

Q02

웹 스프레드시트에서 셀 안에 스파크라인을 표시하려면 어떻게 하나요?

sheet.setSparkline(row, col, dataRange, DataOrientation, SparklineType, setting) 을 사용합니다. 타입으로 line , column , winloss 세 가지를 지원하며, DataOrientation 은 반드시 소문자( horizontal / vertical )로 지정해야 합니다.

Q03

SpreadJS 콤보 차트에서 Bar와 Line을 함께 쓸 때 보조 Y축을 추가하는 방법이 있나요?

chart.series().add() 호출 시 시리즈 객체에 axisGroup: GC.Spread.Sheets.Charts.AxisGroup.secondary 를 지정하면 해당 시리즈가 오른쪽 보조 Y축에 독립적으로 스케일됩니다.

Q04

SpreadJS에서 셀 값이 바뀌면 연결된 차트도 자동으로 갱신되나요?

네, 가능합니다. SpreadJS 차트는 dataRange 로 지정된 셀 범위와 직접 연결되어 있어, setValue() 등으로 셀 값을 변경하면 별도 갱신 코드 없이 차트가 즉시 다시 렌더링됩니다.

Q05

SpreadJS 차트가 포함된 시트를 PDF 파일로 내보낼 수 있나요?

가능합니다. spread.savePDF() 로 차트가 포함된 시트를 클라이언트 측에서 바로 PDF로 내보낼 수 있습니다. 인쇄 영역과 용지 방향 등은 printInfo() API로 세밀하게 제어할 수 있습니다.

MESCIUS SpreadJS

지금 바로 SpreadJS 를 무료로 체험해 보세요

30일 무료 체험판으로 모든 기능을 직접 확인하세요.

SpreadJS 무료 체험판 다운로드