SpreadJS로 웹 셀에 버튼·드롭다운·체크박스 구현하는 방법
SpreadJS는 JavaScript 기반 고성능 스프레드시트 라이브러리로, 웹 애플리케이션에서 HTML 폼을 별도로 추가하지 않고도 셀 하나에 버튼·체크박스·드롭다운 같은 인터랙티브 UI 컨트롤을 직접 배치할 수 있는 '셀 타입(Cell Type)' API를 제공합니다. GC.Spread.Sheets.CellTypes
네임스페이스 아래에 20종 이상의 내장 셀 타입이 준비되어 있으며, sheet.setCellType(row, col, cellType)
한 줄로 원하는 위치의 셀을 즉시 인터랙티브 컨트롤로 전환할 수 있습니다.
React·Vue·Angular·Vanilla JS로 웹 앱을 개발하다 보면 '그리드 셀 안에 클릭 가능한 버튼이나 선택 목록이 필요한데, 행마다 DOM 요소를 삽입하면 수백 행에서 성능이 무너진다'는 상황을 마주치게 됩니다. SpreadJS 셀 타입은 렌더링을 SpreadJS 엔진 내부에서 처리하기 때문에 수천 행에 UI 컨트롤이 붙어 있어도 성능 저하 없이 동작하며, 기존 HTML 레이아웃과의 충돌도 없습니다.
이 가이드에서는 ButtonCellType, CheckBoxCellType, ComboBoxCellType, 슬라이더 드롭다운, 그리고 paint()
메서드로 직접 그리는 완전 커스텀 셀 타입까지 — 실무 시나리오를 기반으로 한 실행 가능한 코드 예제와 함께 단계별로 설명합니다. 서버 API 데이터를 콤보박스에 동적으로 연결하는 패턴과 Excel(.xlsx) 내보내기 시 호환성 처리 방법도 함께 다룹니다.
fetch
+ items()
패턴으로 서버 응답 데이터를 런타임에 연결 가능
GC.Spread.Sheets.CellTypes.Base
를 상속하고 paint()
메서드를 오버라이드해 Canvas 기반 맞춤 셀 UI 직접 제작

셀에 UI 컨트롤을 추가하는 방법 — SpreadJS 셀 타입이란 무엇인가
SpreadJS의 셀 타입(Cell Type)은 셀의 데이터 표시 방식과 사용자 인터랙션 방식을 정의하는 객체입니다. GC.Spread.Sheets.CellTypes
네임스페이스 아래에 Button, CheckBox, ComboBox, HyperLink 등 다양한 타입이 내장되어 있습니다. 셀 타입 객체를 생성한 뒤 sheet.setCellType(row, col, cellType)
또는 sheet.getCell(row, col).cellType(cellType)
으로 특정 셀에 적용하는 방식으로 사용합니다.
아래 예제는 ButtonCellType과 CheckBoxCellType을 한 시트에 함께 배치하고, ButtonClicked
이벤트로 클릭을 처리하는 가장 기본적인 패턴입니다.
STEP 1: CDN 참조
STEP 2: HTML 구조
STEP 3: JavaScript
ButtonClicked
이벤트는 Button, CheckBox, HyperLink 셀 타입 모두에서 발생합니다. instanceof
로 셀 타입을 구분하면 단일 이벤트 핸들러로 모든 클릭 이벤트를 처리할 수 있습니다.
iOS 스타일 토글 스위치를 셀에 넣는 CheckBoxCellType 사용법
CheckBoxCellType은 3상태 모드와 함께 iOS 스타일 토글 스위치 모드를 지원합니다. .mode("toggle")
을 설정하고 toggleOptions()
으로 색상과 크기를 세밀하게 조정할 수 있어 모던한 인터페이스를 구현할 때 유용합니다.
true
/ false
의 불리언으로 저장됩니다. sheet.getValue(row, col)
로 언제든지 현재 상태를 읽을 수 있습니다.셀 드롭다운에 REST API 데이터를 동적으로 연결하는 ComboBoxCellType 활용법
ComboBoxCellType은 드롭다운 선택 UI를 셀 안에 내장합니다. 정적 항목 배열을 items()
로 즉시 설정하거나, REST API 응답 데이터를 fetch
후 동적으로 바인딩하는 두 가지 패턴을 모두 지원합니다.
fetch
패턴의 핵심: 비동기 응답을 받은 뒤 .items(mappedData)
를 호출하면 됩니다. SpreadJS DataManager의 dataBinding()
메서드를 사용하면 테이블과 셀을 실시간으로 양방향 바인딩할 수 있습니다.editorValueType
을 EditorValueType.value
로 설정하면 셀에는 text
가 아닌 value
속성의 값이 저장됩니다. getValue()
로 읽을 때 이 점을 반드시 확인하세요.셀에 슬라이더로 숫자 범위를 입력받는 드롭다운 컨트롤 넣기
SpreadJS에서 슬라이더는 독립적인 셀 타입이 아닌 셀 드롭다운(Cell Dropdown) 방식으로 구현합니다. Style.cellButtons
에 드롭다운 버튼을 추가하고 Style.dropDowns
에 DropDownType.slider
를 설정하면 됩니다. 클릭 시 드롭다운으로 슬라이더가 열려 값을 선택하면 셀에 숫자가 반영됩니다.

formatter: '0"%"'
를 함께 설정하면 셀에 저장된 숫자 값이 "75%"처럼 표시됩니다. 실제 값은 여전히 숫자이므로 수식 계산에 그대로 사용할 수 있습니다.Canvas로 직접 그리는 커스텀 셀 타입 — 나만의 셀 UI 제작 방법
내장 셀 타입으로 해결이 안 될 때는 GC.Spread.Sheets.CellTypes.Base
를 상속해 완전히 새로운 셀 타입을 제작합니다. paint()
메서드에서 Canvas 2D API로 원하는 대로 그리고, getHitInfo()
+ processMouseUp()
으로 마우스 인터랙션을 처리합니다.
아래 예제는 업무 달성률을 시각적인 프로그레스 바로 렌더링하는 커스텀 셀 타입입니다.
paint()
메서드에서 ctx.save()
와 ctx.restore()
로 Canvas 상태를 반드시 감싸야 합니다. 그렇지 않으면 렌더링 상태가 다른 셀에 영향을 줍니다.SpreadJS 셀 타입을 Excel(.xlsx)로 내보낼 때 알아야 할 호환성
SpreadJS 공식 문서에 따르면 cellType
설정은 Excel 내보내기 시 무시됩니다. 셀 타입은 SpreadJS 전용 기능이며 Excel의 네이티브 컨트롤과 직접 매핑되지 않습니다. 아래 표로 각 셀 타입의 내보내기 동작을 정리합니다.
| 셀 타입 | Excel 내보내기 동작 | 값 보존 |
|---|---|---|
| ButtonCellType | 무시 (일반 셀로 출력) | 셀 텍스트만 |
| CheckBoxCellType | 무시 (일반 셀로 출력) | true
/ false
값 |
| ComboBoxCellType | 무시 (일반 셀로 출력) | 선택된 텍스트/값 |
| 슬라이더 드롭다운 | 무시 | 숫자 값 |
| CustomCellType | 무시 | 저장된 원시 값 |
개발자가 자주 묻는 질문
웹 스프레드시트 셀 안에 클릭 가능한 버튼을 넣으려면 SpreadJS에서 어떻게 하나요?
new GC.Spread.Sheets.CellTypes.Button()
으로 버튼 셀 타입 인스턴스를 생성하고 .text()
와 .buttonBackColor()
로 레이블과 배경색을 지정합니다. 그 뒤 sheet.setCellType(row, col, btnType)
으로 셀에 적용하고, spread.bind(GC.Spread.Sheets.Events.ButtonClicked, callback)
을 등록하면 클릭 이벤트를 처리할 수 있습니다.
JavaScript로 스프레드시트 셀에 드롭다운 선택 목록을 넣으려면?
new GC.Spread.Sheets.CellTypes.ComboBox()
로 콤보박스 인스턴스를 만들고 .items(["항목1", "항목2"])
형태로 선택 목록을 지정합니다. 화면에 보여줄 텍스트와 실제 저장 값을 분리하려면 {text: "표시명", value: "실제값"}
형태의 객체 배열로 전달하면 됩니다.
SpreadJS 체크박스 셀을 클릭했을 때 이벤트를 감지하고 현재 값을 읽으려면?
CheckBox 셀 타입도 버튼과 동일하게 GC.Spread.Sheets.Events.ButtonClicked
이벤트를 사용합니다. 이벤트 핸들러 안에서 args.sheet.getValue(args.row, args.col)
을 호출하면 토글 직후 변경된 true
/ false
값을 바로 읽을 수 있습니다.
SpreadJS에서 기본 제공 셀 타입 외에 직접 디자인한 셀 UI를 만들 수 있나요?
네. function MyCell() {}
생성자 함수를 선언한 뒤 MyCell.prototype = new GC.Spread.Sheets.CellTypes.Base()
로 기반 클래스를 상속받습니다. 그 다음 paint(ctx, value, x, y, w, h, style, context)
메서드를 오버라이드하면 HTML Canvas API로 원하는 모양의 셀 UI를 완전히 직접 그릴 수 있습니다.
SpreadJS 콤보박스 셀에 외부 서버 API로 받은 데이터를 실시간으로 채워 넣으려면?
fetch(url).then(r => r.json()).then(data => { combo.items(data.map(d => ({text: d.name, value: d.id}))); sheet.getCell(row, col).cellType(combo); })
패턴으로 API 응답을 받은 뒤 items()
에 목록을 설정합니다. 양방향 실시간 연동이 필요하다면 SpreadJS DataManager의 dataBinding()
메서드로 테이블과 셀을 연결할 수도 있습니다.
