SpreadJS 블로그 MESCIUS 기술 블로그 ·

SpreadJS Designer Component로 웹 엑셀 편집기 만드는 방법

React, Vue, Angular 같은 프레임워크로 웹 앱을 개발하다 보면 "웹에서도 Excel처럼 직접 편집할 수 있는 스프레드시트가 필요하다"는 요구 사항에 맞닥뜨리게 됩니다. 수식 계산, 복잡한 셀 서식, xlsx 파일 가져오기를 모두 직접 구현하려면 작업량이 방대해지는데, SpreadJS의 Designer Component는 리본 메뉴·수식 입력줄·xlsx 가져오기·내보내기를 갖춘 완전한 웹 엑셀 편집기를 new GC.Spread.Sheets.Designer.Designer(containerEl) 한 줄로 브라우저에 올릴 수 있는 JavaScript 스프레드시트 라이브러리입니다.

Designer Component를 초기화한 뒤에는 designer.getWorkbook() 으로 하위 워크북에 직접 접근해 셀 값 설정, 수식 입력, 시트 보호 등 세부 동작을 프로그래밍 방식으로 제어할 수 있습니다. 사용자 조작 없이 서버 템플릿을 자동으로 여는 경우처럼 고급 파일 처리가 필요할 때만 import() / export() API를 추가로 호출하면 됩니다.

이 가이드는 SpreadJS Designer Component의 초기화부터 xlsx 열기·저장, 뷰어 모드 구성, 리본 커스터마이징, 역할별 UI 동적 제어까지 단계별 Vanilla JS 예제로 안내합니다. 웹 개발 경험은 있지만 SpreadJS를 처음 접하는 프론트엔드 개발자를 대상으로 합니다.

⭐ Key Points
이 글에서 다루는 핵심 내용
01 한 줄 초기화: new GC.Spread.Sheets.Designer.Designer(el) 로 리본·수식 입력줄·시트 탭이 갖춰진 웹 엑셀 에디터를 코드 한 줄로 완성
02 xlsx 열기·저장 내장: 별도 코드 없이 리본의 [파일] → [가져오기]/[내보내기]로 Excel 파일을 불러오고 편집 후 다시 내려받기
03 뷰어 모드 전환: 시트 보호와 리본 탭 필터링을 함께 적용해 읽기 전용 웹 엑셀 뷰어 환경 구성
04 역할 기반 UI 제어: 관리자·뷰어 등 사용자 역할에 따라 편집 가능 셀 범위와 리본 메뉴를 실시간으로 전환
SpreadJS Designer Component로 웹 엑셀 편집기 만드는 방법 — 대표 이미지

SpreadJS Designer Component가 하는 일: 웹 엑셀 편집기를 한 줄로 완성하는 방법

SpreadJS Designer Component는 Excel과 동일한 리본 UI, 수식 입력줄, 시트 탭을 브라우저에서 그대로 제공하는 풀 에디터 컴포넌트입니다. 아래 코드 한 줄로 완성도 높은 웹 엑셀 편집 환경을 초기화할 수 있습니다.

new GC.Spread.Sheets.Designer.Designer(containerElement)

초기화 후에는 designer.getWorkbook() 으로 하위 SpreadJS 워크북에 직접 접근해 세부 기능을 제어합니다.

SpreadJS는 Excel 호환 수식 500개 이상을 지원하며, Designer Component를 통해 리본 UI·수식 입력줄·시트 탭이 포함된 완전한 스프레드시트 편집 환경을 브라우저에서 제공합니다. ERP·그룹웨어·보고서 시스템에서 Excel을 그대로 웹으로 가져와야 하는 SI 개발자의 핵심 솔루션입니다.

↗
500+
내장 수식
Excel 호환 계산 엔진
↗
1줄
초기화 코드
완전한 편집 UI 구현
↗
3가지
제어 모드
뷰어·에디터·역할별 전환
ⓘ NOTE
배포 환경에서는 SpreadJS 라이선스( GC.Spread.Sheets.LicenseKey )와 Designer Component 전용 라이선스( GC.Spread.Sheets.Designer.LicenseKey )를 별도로 설정해야 합니다. 라이선스 키 두 개는 Designer 인스턴스를 만들기 전에 설정해야 합니다. 라이선스 없이 실행하면 Designer Component는 로컬 환경( localhost , 127.0.0.1 , file:// )에서만 동작하고, 웹 서버에 배포하면 리본이 표시되지 않고 "Deployment License Key not found" 오류가 나타납니다. 웹 서버에서 평가하려면 평가용 배포 라이선스를 발급받아 설정하세요.

Designer Component 초기 설정과 xlsx 파일 불러오기·내려받기 방법

Designer Component는 초기화 과정에서 shapes·charts·print·pdf·io 플러그인을 사용합니다. 따라서 SpreadJS 본체 다음에 이 5개 플러그인을 먼저 로드한 뒤 Designer 리소스를 추가해야 합니다.

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

⭐ IMPORTANT
Designer Component는 shapes·charts·print·pdf·io 플러그인이 모두 필수입니다. 하나라도 빠지거나 Designer 스크립트보다 늦게 로드되면 초기화 단계에서 오류가 발생합니다(예: print 플러그인 누락 시 PaperKind is not defined ). barcode·slicers·피벗 등 나머지 플러그인은 필요한 기능에 따라 추가합니다.

STEP 2: HTML 구조

STEP 3: JavaScript (Designer 초기화)

실행 결과

Designer Component에는 Excel 파일 가져오기/내보내기 화면이 이미 내장되어 있어, xlsx 열기·저장 기능을 따로 구현할 필요가 없습니다.

  • ✓ xlsx 열기: 리본의 [파일] → [가져오기]에서 Excel 파일을 선택하면 서식·수식이 유지된 채 바로 열립니다.
  • ✓ xlsx 저장: [파일] → [내보내기]에서 편집한 내용을 xlsx 파일로 내려받습니다.
  • ✓ 암호가 걸린 파일: 가져오기/내보내기 화면의 암호 입력란으로 암호화된 Excel 파일도 처리할 수 있습니다.
💡 TIP
서버에 저장된 템플릿을 페이지 로드 시 자동으로 여는 것처럼 사용자 조작 없이 파일을 다뤄야 할 때만 designer.getWorkbook() 으로 얻은 워크북의 import() / export() API를 호출하면 됩니다.

웹 엑셀 뷰어 모드를 구현하는 방법: 읽기 전용 환경 구성하기

SpreadJS Designer Component에서 시트 보호와 리본 탭 비활성화를 조합해 읽기 전용 웹 엑셀 뷰어를 구현할 수 있습니다. GC.Spread.Sheets.Designer.DefaultConfig 를 JSON으로 깊은 복사한 뒤 편집 관련 탭을 제거하고, sheet.options.isProtected = true 로 셀 직접 편집을 차단합니다.

웹 엑셀 뷰어 모드를 구현하는 방법: 읽기 전용 환경 구성하기 — SpreadJS 개념도

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

STEP 2: HTML 구조

STEP 3: JavaScript (뷰어 모드 설정)

실행 결과
⚠ WARNING
sheet.options.isProtected = true 는 직접 셀 편집을 차단하지만 완전한 보안 수단은 아닙니다. 민감한 데이터라면 서버 사이드에서 역할을 검증하고, 편집 API 엔드포인트에 권한 체크를 추가하세요.

Excel 리본 메뉴 커스터마이징: 탭 필터링과 커스텀 명령 추가하기

Designer Component는 GC.Spread.Sheets.Designer.DefaultConfig 와 commandMap 을 통해 리본 탭·버튼 단위 커스터마이징을 지원합니다. 아래 예시는 Home 탭 맨 앞에 선택 영역을 노란색으로 강조하는 "강조" 버튼과 활성 셀에 오늘 날짜를 넣는 "오늘 날짜" 버튼을 추가합니다.

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

STEP 2: HTML 구조

STEP 3: JavaScript (사용자 정의 리본 버튼 추가)

실행 결과
⭐ BEST PRACTICE
탭을 삭제할 때는 config.ribbon = config.ribbon.filter(tab => tab.id !== '제거할탭ID') 패턴을 사용합니다. 주요 기본 탭 ID는 'home' , 'insert' , 'formulas' , 'data' , 'view' 입니다. 초기화 후 designer.setConfig(config) 로도 런타임 변경이 가능합니다.

로그인 역할(role)에 따라 편집 범위와 리본 UI를 동적으로 바꾸는 방법

로그인 역할(role)에 따라 편집 범위와 리본 UI를 동적으로 바꾸는 방법 — SpreadJS 개념도

관리자와 뷰어를 위한 두 가지 Designer 설정을 미리 준비하고 designer.setConfig() 로 런타임에 전환하면, 세션 갱신 없이 단일 페이지에서 역할별 편집 환경을 즉시 제공할 수 있습니다.

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

STEP 2: HTML 구조

STEP 3: JavaScript (역할별 UI 동적 전환)

실행 결과
💡 TIP
designer.setConfig() 는 런타임에 호출할 수 있어, 사용자 로그인 후 서버에서 역할 정보를 받아온 뒤 즉시 UI를 전환하는 패턴에 유용합니다. 특정 셀 범위만 편집 가능하게 허용하려면 해당 셀에 sheet.getCell(r, c).locked(false) ( locked 는 속성이 아니라 메서드)를 호출한 뒤 sheet.options.isProtected = true 로 시트를 보호합니다.

SpreadJS Designer 도입 시 자주 묻는 질문

Q01

웹 프론트엔드에서 Excel 같은 편집 기능을 구현할 수 있는 JavaScript 라이브러리는 무엇인가요?

SpreadJS의 Designer Component를 사용하면 리본 UI·수식 입력줄·xlsx 열기/저장이 모두 포함된 웹 엑셀 에디터를 즉시 구성할 수 있습니다. new GC.Spread.Sheets.Designer.Designer(containerEl) 한 줄로 완전한 편집 환경이 초기화됩니다.

Q02

SpreadJS에서 읽기 전용 뷰어 모드와 편집 모드를 어떻게 나눠 구현하나요?

시트 보호와 리본 탭 필터링을 함께 쓰면 뷰어와 에디터 두 모드를 구분할 수 있습니다. viewerConfig.ribbon = viewerConfig.ribbon.filter(tab => ['home','view'].includes(tab.id)) 로 편집 관련 탭을 제거하고, sheet.options.isProtected = true 를 적용해 셀 직접 수정을 막습니다.

Q03

SpreadJS Designer Component를 쓰면 xlsx 파일 열기와 저장 기능을 따로 구현해야 하나요?

별도 구현이 필요 없습니다. 필수 플러그인(shapes·charts·print·pdf·io)을 모두 로드하고 Designer Component를 초기화하면, 리본의 [파일] → [가져오기]로 Excel 파일을 불러오고 [파일] → [내보내기]로 xlsx로 내려받는 기능이 바로 작동합니다. 페이지 로드 시 서버 템플릿을 자동으로 여는 것처럼 코드에서 직접 파일을 다뤄야 할 경우에만 designer.getWorkbook() 의 import() / export() API를 사용합니다.

Q04

웹 앱에서 Excel 리본 메뉴를 커스터마이징하고 특정 버튼만 표시하는 방법이 있나요?

JSON.parse(JSON.stringify(GC.Spread.Sheets.Designer.DefaultConfig)) 로 기본 설정을 복사한 뒤, config.ribbon = config.ribbon.filter(tab => ['home', 'view'].includes(tab.id)) 형태로 보여줄 탭만 남깁니다. 버튼 하나하나를 제어하려면 config.commandMap 에서 해당 명령의 visibleContext 조건을 수정하면 됩니다.

Q05

SpreadJS에서 로그인 사용자의 역할(role)에 따라 편집 가능한 셀 범위를 다르게 설정하려면 어떻게 하나요?

사용자 역할 정보를 받아온 뒤 sheet.options.isProtected = true 로 전체 시트를 잠그고, 해당 역할에서 편집을 허용할 셀만 sheet.getCell(r, c).locked(false) 로 개방합니다. 리본 구성도 역할에 맞게 designer.setConfig() 로 동시에 교체합니다.

MESCIUS SpreadJS

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

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

SpreadJS 무료 체험판 다운로드