SpreadJS 블로그 MESCIUS 기술 블로그 ·

SpreadJS로 REST API 데이터를 웹 스프레드시트에 연결하는 방법

웹 앱에 '엑셀 같은 표'를 붙여야 한다는 요구사항을 맡아본 적 있으신가요? 주문 목록을 편집 가능한 그리드로 보여주거나, WebSocket으로 실시간 주가를 갱신하거나, GraphQL 쿼리 결과를 표로 렌더링하는 작업을 순수 JavaScript로 처음부터 구현하면 상당히 복잡합니다. SpreadJS는 JavaScript 환경에서 엔터프라이즈급 스프레드시트 UI를 구현할 수 있는 라이브러리로, 내장된 Data Manager를 통해 복잡한 상태 관리 로직 없이 선언적 설정만으로 REST API·WebSocket·GraphQL 등 다양한 데이터 소스를 스프레드시트에 연결할 수 있습니다.

React·Vue·Angular·Vanilla JS 어느 환경에서 개발하든 addTable() 한 번으로 API 엔드포인트를 데이터 소스로 등록하고, autoSync 옵션 하나로 편집한 셀을 서버에 자동 전송할 수 있습니다. 가상 스크롤이 기본 내장되어 있어 수십만 행의 대용량 데이터도 별도 설정 없이 부드럽게 처리됩니다.

이 가이드는 SpreadJS를 처음 접하는 웹·프론트엔드 개발자를 위해 REST API 연동 기초부터 WebSocket 실시간 업데이트, GraphQL 매핑, 대용량 최적화, 양방향 동기화까지 단계별 코드와 함께 설명합니다. 각 섹션의 STEP별 예제를 그대로 따라 하면 바로 동작하는 데모를 만들어볼 수 있습니다.

⭐ Key Points
이 글에서 다루는 핵심 내용
01 Data Manager API: addTable() 하나로 REST API를 스프레드시트 데이터 소스로 등록하고 자동 로드·렌더링할 수 있습니다
02 실시간 하이라이트: WebSocket 메시지 수신 시 setValue + backColor 로 변경된 셀을 즉시 시각적으로 표시합니다
03 GraphQL 호환: remote.read 함수에서 GraphQL 응답을 가공해 반환하면 Data Manager가 동일한 방식으로 처리합니다
04 양방향 동기화: autoSync / batch 모드 설정으로 셀 편집 내용을 서버에 자동 전송하는 쓰기 기능을 간단히 구현합니다
SpreadJS로 REST API 데이터를 웹 스프레드시트에 연결하는 방법 — 대표 이미지

REST API 데이터를 JavaScript 스프레드시트 셀에 표시하려면?

SpreadJS의 GC.Data.DataManager 는 REST API 엔드포인트를 데이터 소스로 등록하는 전용 API입니다. spread.dataManager().addTable() 의 remote.read.url 에 GET 엔드포인트를 지정하면 자동으로 데이터를 불러와 워크시트 테이블에 렌더링합니다.

STEP 1: 라이브러리 참조 (CDN)

STEP 2: HTML 구조

STEP 3: JavaScript

실행 결과
💡 TIP
addTable() 의 remote 옵션에 create , update , delete URL을 함께 지정하면 CRUD 전체를 Data Manager가 관리합니다. 읽기 전용이라면 read 만으로 충분합니다.

실시간 주가·센서 데이터를 스프레드시트 셀에 반영하는 방법

WebSocket 메시지가 도착할 때마다 특정 셀 값을 갱신하고 변경 셀을 시각적으로 하이라이트하는 패턴입니다. sheet.setValue() 로 값을 업데이트한 뒤 sheet.getCell().backColor() 로 플래시 효과를 주고, setTimeout 으로 원래 색으로 복원합니다.

STEP 1: 라이브러리 참조 (CDN)

STEP 2: HTML 구조

STEP 3: JavaScript

실행 결과
ⓘ NOTE
실제 WebSocket 연결 시 const ws = new WebSocket('wss://your-server/stream'); 후 ws.onmessage = (e) => handleWsMessage(...JSON.parse(e.data)) 패턴으로 교체하면 됩니다. suspendPaint() / resumePaint() 감싸기는 빠른 메시지가 연속 도착할 때 렌더링 병목을 막아줍니다.

GraphQL API 응답을 웹 스프레드시트 데이터 소스로 쓰는 방법

GraphQL은 REST와 달리 필요한 필드만 선택적으로 요청해 네트워크 효율을 높입니다. Data Manager의 remote.read 를 URL 대신 함수로 지정하면 GraphQL fetch 를 직접 처리하고 결과 배열을 반환할 수 있습니다.

GraphQL과 Data Manager를 연결하는 기본 구현 패턴

GraphQL API 응답을 웹 스프레드시트 데이터 소스로 쓰는 방법 — SpreadJS 개념도

아래 데모는 GraphQL 응답 구조를 그대로 시뮬레이션합니다.

STEP 1: 라이브러리 참조 (CDN)

STEP 2: HTML 구조

STEP 3: JavaScript

실행 결과
⭐ IMPORTANT
GraphQL 응답의 data.employees 처럼 중첩 객체에서 배열을 추출해 반환하는 것이 핵심입니다. remote.read 함수는 항상 Promise<any[]> 형태를 반환해야 Data Manager가 올바르게 동작합니다.

수만 행 데이터를 버벅임 없이 로드하는 성능 최적화 방법

SpreadJS는 DOM에 화면에 보이는 셀만 렌더링하는 가상 스크롤(Virtual Scroll)을 기본 내장합니다. 별도 설정 없이도 수십만 행을 60FPS로 처리하지만, 대량 데이터 입력 시에는 suspendPaint() / resumePaint() 패턴을 반드시 적용해야 합니다.

↗
100만+
행 처리 능력
가상 스크롤 기반
↗
60FPS
렌더링 성능
DOM 최소화 설계
↗
10배+
입력 속도 향상
suspendPaint 적용 시

STEP 1: 라이브러리 참조 (CDN)

STEP 2: HTML 구조

STEP 3: JavaScript

실행 결과
⚠ WARNING
suspendPaint() 후 예외가 발생하면 resumePaint() 가 호출되지 않아 화면이 갱신되지 않습니다. try-finally로 감싸거나, Data Manager의 batch: true 모드를 활용해 서버 페이징과 결합하는 것을 권장합니다.

스프레드시트 셀 수정 내용을 서버에 자동 저장하려면?

SpreadJS는 Data Manager의 autoSync 옵션으로 셀 편집 즉시 서버에 PUT 요청을 자동 전송합니다. 고빈도 편집에는 batch: true + submitChanges() 를 사용해 변경 사항을 모아 한 번에 전송하는 것이 효율적입니다.

autoSync와 batch 모드: 어떤 상황에 무엇을 쓸까?

CellChanged 이벤트로 커스텀 동기화 로직을 직접 구현할 수도 있습니다.

STEP 1: 라이브러리 참조 (CDN)

STEP 2: HTML 구조

STEP 3: JavaScript

실행 결과
스프레드시트 셀 수정 내용을 서버에 자동 저장하려면? — SpreadJS 개념도
⭐ BEST PRACTICE
고빈도 편집(대량 붙여넣기, 수식 자동완성 등)에서는 autoSync: true 대신 batch: true 를 사용하세요. 모든 변경을 모아 submitChanges() 한 번으로 서버에 전송해 네트워크 요청을 대폭 줄일 수 있습니다.

자주 하는 질문

Q01

웹 앱에서 REST API 데이터를 스프레드시트 셀에 자동으로 표시하려면 어떻게 하나요?

먼저 spread.dataManager().addTable('name', { remote: { read: { url: '/api/data' } } }) 로 테이블을 등록합니다. 이후 fetch() 로 데이터를 가져온 뒤 sheet.tables.addFromDataSource() 로 워크시트에 바인딩하면 헤더와 행이 자동으로 렌더링됩니다.

Q02

WebSocket으로 받은 실시간 데이터를 스프레드시트에 즉시 반영하려면?

ws.onmessage 핸들러 안에서 sheet.setValue(row, col, value) 로 셀 값을 갱신하고, sheet.getCell(row, col).backColor('#FFF9C4') 로 변경 셀을 하이라이트한 뒤 setTimeout 으로 색을 복원하면 됩니다. 연속 메시지가 빠르게 들어올 때는 suspendPaint() / resumePaint() 로 감싸면 렌더링 성능이 안정적으로 유지됩니다.

Q03

GraphQL API에서 받은 데이터를 SpreadJS 테이블에 표시할 수 있나요?

가능합니다. Data Manager의 remote.read 를 URL 문자열 대신 함수로 지정하면 됩니다. 함수 안에서 GraphQL fetch 요청을 실행하고 응답 본문의 json.data.targetField 배열을 Promise 로 반환하면, Data Manager가 나머지 렌더링을 동일하게 처리합니다.

Q04

SpreadJS에서 대용량 데이터를 끊김 없이 로드하는 최적화 방법은?

spread.suspendPaint() 로 렌더링을 일시 중단한 후 setRowCount() 로 행 수를 미리 확보하고, 대량 setValue 를 완료한 뒤 resumePaint() 를 호출하세요. 가상 스크롤은 기본 내장되어 있어 별도 설정 없이 수십만 행을 처리합니다.

Q05

스프레드시트에서 사용자가 셀을 편집하면 서버 데이터베이스에 자동으로 반영되게 하려면?

Data Manager addTable() 에 autoSync: true 와 remote.update.url 을 지정하면 셀 편집 즉시 PUT 요청이 자동으로 전송됩니다. 여러 셀을 모아 한 번에 저장하는 시나리오에는 batch: true 설정 후 tablesheet.submitChanges() 를 호출하는 방식이 더 효율적입니다.

MESCIUS SpreadJS

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

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

SpreadJS 무료 체험판 다운로드