SpreadJS 블로그 MESCIUS 기술 블로그 ·

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) 내보내기 시 호환성 처리 방법도 함께 다룹니다.

⭐ Key Points
이 글에서 다루는 핵심 내용
01 20종 이상 내장 셀 타입: SpreadJS ButtonCellType, CheckBoxCellType, ComboBoxCellType 등 — HTML 폼 없이 셀 한 줄 코드로 UI 컨트롤 배치
02 REST API 동적 바인딩: 콤보박스에 fetch + items() 패턴으로 서버 응답 데이터를 런타임에 연결 가능
03 완전 커스텀 셀 타입: GC.Spread.Sheets.CellTypes.Base 를 상속하고 paint() 메서드를 오버라이드해 Canvas 기반 맞춤 셀 UI 직접 제작
04 Excel 내보내기 호환성: xlsx로 내보낼 때 셀 타입 정보는 SpreadJS 전용 — SJS 포맷으로 저장하면 완전 보존
SpreadJS로 웹 셀에 버튼·드롭다운·체크박스 구현하는 방법 — 대표 이미지

셀에 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

실행 결과
💡 TIP
ButtonClicked 이벤트는 Button, CheckBox, HyperLink 셀 타입 모두에서 발생합니다. instanceof 로 셀 타입을 구분하면 단일 이벤트 핸들러로 모든 클릭 이벤트를 처리할 수 있습니다.
셀에 UI 컨트롤을 추가하는 방법 — SpreadJS 셀 타입이란 무엇인가 — SpreadJS 개념도

iOS 스타일 토글 스위치를 셀에 넣는 CheckBoxCellType 사용법

CheckBoxCellType은 3상태 모드와 함께 iOS 스타일 토글 스위치 모드를 지원합니다. .mode("toggle") 을 설정하고 toggleOptions() 으로 색상과 크기를 세밀하게 조정할 수 있어 모던한 인터페이스를 구현할 때 유용합니다.

실행 결과
ⓘ NOTE
토글 스위치 모드에서도 값은 true / false 의 불리언으로 저장됩니다. sheet.getValue(row, col) 로 언제든지 현재 상태를 읽을 수 있습니다.

셀 드롭다운에 REST API 데이터를 동적으로 연결하는 ComboBoxCellType 활용법

ComboBoxCellType은 드롭다운 선택 UI를 셀 안에 내장합니다. 정적 항목 배열을 items() 로 즉시 설정하거나, REST API 응답 데이터를 fetch 후 동적으로 바인딩하는 두 가지 패턴을 모두 지원합니다.

실행 결과
💡 TIP
fetch 패턴의 핵심: 비동기 응답을 받은 뒤 .items(mappedData) 를 호출하면 됩니다. SpreadJS DataManager의 dataBinding() 메서드를 사용하면 테이블과 셀을 실시간으로 양방향 바인딩할 수 있습니다.
⚠ WARNING
editorValueType 을 EditorValueType.value 로 설정하면 셀에는 text 가 아닌 value 속성의 값이 저장됩니다. getValue() 로 읽을 때 이 점을 반드시 확인하세요.

셀에 슬라이더로 숫자 범위를 입력받는 드롭다운 컨트롤 넣기

SpreadJS에서 슬라이더는 독립적인 셀 타입이 아닌 셀 드롭다운(Cell Dropdown) 방식으로 구현합니다. Style.cellButtons 에 드롭다운 버튼을 추가하고 Style.dropDowns 에 DropDownType.slider 를 설정하면 됩니다. 클릭 시 드롭다운으로 슬라이더가 열려 값을 선택하면 셀에 숫자가 반영됩니다.

셀에 슬라이더로 숫자 범위를 입력받는 드롭다운 컨트롤 넣기 — SpreadJS 개념도
실행 결과
ⓘ NOTE
formatter: '0"%"' 를 함께 설정하면 셀에 저장된 숫자 값이 "75%"처럼 표시됩니다. 실제 값은 여전히 숫자이므로 수식 계산에 그대로 사용할 수 있습니다.

Canvas로 직접 그리는 커스텀 셀 타입 — 나만의 셀 UI 제작 방법

내장 셀 타입으로 해결이 안 될 때는 GC.Spread.Sheets.CellTypes.Base 를 상속해 완전히 새로운 셀 타입을 제작합니다. paint() 메서드에서 Canvas 2D API로 원하는 대로 그리고, getHitInfo() + processMouseUp() 으로 마우스 인터랙션을 처리합니다.

아래 예제는 업무 달성률을 시각적인 프로그레스 바로 렌더링하는 커스텀 셀 타입입니다.

실행 결과
⭐ BEST PRACTICE
paint() 메서드에서 ctx.save() 와 ctx.restore() 로 Canvas 상태를 반드시 감싸야 합니다. 그렇지 않으면 렌더링 상태가 다른 셀에 영향을 줍니다.

SpreadJS 셀 타입을 Excel(.xlsx)로 내보낼 때 알아야 할 호환성

SpreadJS 공식 문서에 따르면 cellType 설정은 Excel 내보내기 시 무시됩니다. 셀 타입은 SpreadJS 전용 기능이며 Excel의 네이티브 컨트롤과 직접 매핑되지 않습니다. 아래 표로 각 셀 타입의 내보내기 동작을 정리합니다.

셀 타입 Excel 내보내기 동작 값 보존
ButtonCellType 무시 (일반 셀로 출력) 셀 텍스트만
CheckBoxCellType 무시 (일반 셀로 출력) true / false 값
ComboBoxCellType 무시 (일반 셀로 출력) 선택된 텍스트/값
슬라이더 드롭다운 무시 숫자 값
CustomCellType 무시 저장된 원시 값
⭐ IMPORTANT
SpreadJS 자체 포맷인 SJS 또는 SSJSON으로 저장하면 셀 타입을 포함한 모든 설정이 완전히 보존됩니다. Excel 호환이 필요하면서 UI 컨트롤을 유지하려면, Excel 쪽에 데이터 유효성 검사(드롭다운)나 양식 컨트롤을 별도로 구성해야 합니다.
↗
20+
내장 셀 타입
Button·CheckBox·ComboBox 포함
↗
100%
VanillaJS 지원
별도 프레임워크 불필요
↗
SJS/SSJSON
완전 직렬화
셀 타입 포함 전체 보존

개발자가 자주 묻는 질문

Q01

웹 스프레드시트 셀 안에 클릭 가능한 버튼을 넣으려면 SpreadJS에서 어떻게 하나요?

new GC.Spread.Sheets.CellTypes.Button() 으로 버튼 셀 타입 인스턴스를 생성하고 .text() 와 .buttonBackColor() 로 레이블과 배경색을 지정합니다. 그 뒤 sheet.setCellType(row, col, btnType) 으로 셀에 적용하고, spread.bind(GC.Spread.Sheets.Events.ButtonClicked, callback) 을 등록하면 클릭 이벤트를 처리할 수 있습니다.

Q02

JavaScript로 스프레드시트 셀에 드롭다운 선택 목록을 넣으려면?

new GC.Spread.Sheets.CellTypes.ComboBox() 로 콤보박스 인스턴스를 만들고 .items(["항목1", "항목2"]) 형태로 선택 목록을 지정합니다. 화면에 보여줄 텍스트와 실제 저장 값을 분리하려면 {text: "표시명", value: "실제값"} 형태의 객체 배열로 전달하면 됩니다.

Q03

SpreadJS 체크박스 셀을 클릭했을 때 이벤트를 감지하고 현재 값을 읽으려면?

CheckBox 셀 타입도 버튼과 동일하게 GC.Spread.Sheets.Events.ButtonClicked 이벤트를 사용합니다. 이벤트 핸들러 안에서 args.sheet.getValue(args.row, args.col) 을 호출하면 토글 직후 변경된 true / false 값을 바로 읽을 수 있습니다.

Q04

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를 완전히 직접 그릴 수 있습니다.

Q05

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() 메서드로 테이블과 셀을 연결할 수도 있습니다.

MESCIUS SpreadJS

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

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

SpreadJS 무료 체험판 다운로드