SpreadJS 블로그 MESCIUS 기술 블로그 ·

SpreadJS로 웹 입력 폼 데이터 검증 구현하기

React·Vue·Angular로 웹 애플리케이션을 개발하다 보면 "사용자가 잘못된 값을 입력했을 때 서버 요청 없이 즉시 오류를 잡아야 한다"는 요구사항을 자주 마주합니다. SpreadJS는 엑셀과 동일한 셀 단위 데이터 검증 기능을 JavaScript로 구현할 수 있는 웹 스프레드시트 컴포넌트로, GC.Spread.Sheets.DataValidation API를 통해 숫자·날짜·텍스트·목록·수식 등 6가지 유효성 검사 타입을 몇 줄의 코드로 선언적으로 적용할 수 있습니다.

검사 로직을 직접 구현하다 보면 조건문이 셀 수만큼 늘어나고, 비즈니스 규칙이 바뀔 때마다 여러 곳을 함께 수정해야 합니다. SpreadJS는 sheet.setDataValidator() 로 Validator 객체를 셀이나 범위에 한 번만 선언하면 되어, 검사 규칙을 중앙에서 체계적으로 관리할 수 있습니다.

이 글에서는 기초적인 숫자·날짜 범위 검사부터 셀 범위와 연동되는 드롭다운 목록, 크로스셀 조건을 수식으로 표현하는 커스텀 Formula Validator, 오류 UX 제어, 시트 전체 일괄 검사까지 실무에 바로 활용할 수 있는 코드 예제로 단계별 안내합니다.

⭐ Key Points
이 글에서 다루는 핵심 내용
01 6가지 내장 Validator: SpreadJS는 숫자·날짜·텍스트 길이·목록·수식 등 6가지 유효성 검사 타입을 별도 라이브러리 없이 기본 제공합니다
02 정적·동적 드롭다운: 드롭다운 목록은 고정 문자열 배열과 셀 범위를 통한 동적 참조를 모두 지원합니다
03 수식 기반 커스텀 검사: 커스텀 Formula Validator로 크로스셀 조건·비즈니스 로직을 JavaScript 없이 수식으로 표현합니다
04 세밀한 오류 UX: ValidationError 이벤트와 ErrorStyle 설정으로 오류 피드백 UX(중지/경고/정보)를 세밀하게 제어합니다
SpreadJS로 웹 입력 폼 데이터 검증 구현하기 — 대표 이미지

SpreadJS DataValidation이란? 6가지 검사 타입 한눈에 보기

SpreadJS 유효성 검사는 GC.Spread.Sheets.DataValidation 네임스페이스에서 6가지 팩토리 메서드로 생성하고, sheet.setDataValidator() 로 셀 또는 범위에 적용합니다. spread.options.highlightInvalidData = true 를 설정하면 유효하지 않은 셀에 즉시 빨간 원이 표시됩니다.

↗
6가지
내장 Validator 타입
숫자·날짜·텍스트·목록·수식 모두 커버
↗
3단계
에러 UX 제어
중지(Stop)·경고(Warning)·정보(Information)
↗
1줄
범위 적용
setDataValidator(row, col, rowCount, colCount, dv)
팩토리 메서드 검사 기준
createNumberValidator 정수·소수 범위
createDateValidator 날짜 범위
createTextLengthValidator 텍스트 길이
createListValidator 정적 쉼표 구분 목록
createFormulaListValidator 셀 범위 동적 목록
createFormulaValidator 커스텀 수식 (true/false 반환)

아래 데모는 수량(정수 1~100), 납기일(2025년 범위), 비고(50자 이하) 세 가지 검사를 한 화면에 구성합니다.

STEP 1: CDN 라이브러리 참조

STEP 2: HTML 구조

STEP 3: JavaScript

실행 결과
💡 TIP
setDataValidator(row, col, dv) 는 단일 셀, setDataValidator(row, col, rowCount, colCount, dv) 는 범위 전체에 한 번에 적용합니다. 입력 폼 열 전체에 검사를 적용할 때 유용합니다.
SpreadJS DataValidation이란? 6가지 검사 타입 한눈에 보기 — SpreadJS 개념도

드롭다운 목록 검사 구현하기: 고정 값 목록 vs 셀 범위 동적 연동

목록 유효성 검사는 두 가지 방식으로 구성합니다. 값이 고정되면 createListValidator 로 쉼표 구분 문자열을 직접 전달하고, 마스터 데이터를 참조하려면 createFormulaListValidator 에 셀 범위 수식을 전달합니다. 후자는 범위의 데이터를 변경하면 드롭다운 목록이 자동으로 갱신되어 ERP·MES 환경의 동적 코드 테이블에 적합합니다.

STEP 2: HTML 구조

STEP 3: JavaScript

실행 결과
ⓘ NOTE
createFormulaListValidator 에 절대 참조( $E$1:$E$4 )를 사용하면 검사 범위가 셀 위치에 관계없이 고정됩니다. 마스터 데이터가 동적으로 추가되는 경우 $E$1:$E$100 처럼 여유 범위를 잡아두거나, 해당 열을 Excel 표(Table)로 구성하세요.
⚠ WARNING
dv.inCellDropdown(false) 로 설정하면 드롭다운 버튼이 사라지고 직접 입력만 허용됩니다. 사용자가 선택지를 알아야 하는 폼에서는 기본값(true)을 유지하는 것이 UX상 권장됩니다.

복잡한 조건 검사를 수식 한 줄로: 커스텀 Formula Validator 사용법

createFormulaValidator(formula) 는 수식 결과가 true 일 때만 유효한 것으로 판정합니다. "종료일이 시작일보다 커야 한다", "할인율이 마진율을 초과할 수 없다" 같은 크로스셀 규칙을 JavaScript 코드 없이 스프레드시트 수식으로 표현할 수 있어 유지보수가 간편합니다. 범위에 적용하면 상대 참조가 각 행 위치에 맞게 자동 이동합니다.

STEP 2: HTML 구조

STEP 3: JavaScript

실행 결과
⭐ IMPORTANT
setDataValidator(1, 2, 4, 1, dv) 로 범위에 적용하면 수식이 각 행의 상대 참조로 자동 이동합니다. C2>=B2 로 지정해도 3행에는 C3>=B3 으로 동작하는 방식은 Excel 데이터 유효성 검사와 동일합니다.
복잡한 조건 검사를 수식 한 줄로: 커스텀 Formula Validator 사용법 — SpreadJS 개념도

입력 오류를 사용자에게 알리는 방법: 에러 스타일과 이벤트 처리

에러 스타일은 잘못된 입력을 얼마나 강하게 제한할지 결정합니다. ErrorStyle.stop / ErrorStyle.warning / ErrorStyle.information 은 유효성 검사 실패 유형을 구분하기 위한 설정값이며, 각각을 어떻게 제한할 것인지에 대해서는 ValidationError 이벤트를 사용하여 입력 허용·거부·재입력을 코드로 제어해야 합니다.

실행 결과
💡 TIP
ValidationError 이벤트의 args.validationResult 를 DataValidationResult.forceApply 로 설정하면 오류 값이 그대로 셀에 저장됩니다. discard 로 설정하면 이전 값으로 복원하고, retry 로 설정하면 편집 모드를 유지합니다.

시트 전체에서 오류 셀을 자동으로 찾아 하이라이트하는 방법

제출 버튼을 누르기 전 시트 전체를 검사하고 오류 셀을 한눈에 표시하는 패턴은 데이터 입력 폼에서 필수입니다. sheet.getDataValidator(row, col) 로 검사기 존재 여부를 확인하고, sheet.isValid(row, col, value) 로 현재 값을 판정한 뒤, 오류 셀에 backColor 를 적용해 즉시 시각화합니다.

STEP 2: HTML 구조

STEP 3: JavaScript

실행 결과
⭐ BEST PRACTICE
highlightInvalidData 를 false 로 설정하고 저장·제출 시점에만 isValid() 배치 검사를 실행하면, 편집 중에는 조용한 UX를 제공하다가 제출 전에 한 번에 오류 셀을 표시하는 "저장 전 일괄 검증" 패턴을 구현할 수 있습니다.

자주 묻는 질문 (FAQ)

Q01

JavaScript로 웹 스프레드시트 셀에 숫자 입력 범위를 제한하려면 어떻게 하나요?

GC.Spread.Sheets.DataValidation.createNumberValidator(ComparisonOperators.between, '최솟값', '최댓값', true) 로 Validator를 만들고 sheet.setDataValidator(row, col, dv) 로 셀에 적용합니다. 네 번째 인수 true 는 정수 전용, false 는 소수 허용입니다.

Q02

SpreadJS에서 다른 셀 범위 데이터를 드롭다운 목록으로 연동하는 방법은 무엇인가요?

createFormulaListValidator('$A$1:$A$10') 형식으로 절대 참조 범위를 전달하면 해당 범위의 값이 드롭다운으로 표시되고, 범위 데이터를 변경하면 목록이 자동으로 갱신됩니다.

Q03

SpreadJS 유효성 검사 오류 팝업의 제목과 내용을 한국어로 변경하는 방법은?

dv.showErrorMessage(true) , dv.errorTitle('한국어 제목') , dv.errorMessage('한국어 메시지') 세 메서드를 연속 호출하면 오류 팝업의 제목과 내용을 자유롭게 설정할 수 있습니다. 각 메서드는 validator 객체를 반환해 체이닝도 가능합니다.

Q04

SpreadJS에서 두 셀 값을 비교하는 커스텀 검증 규칙을 수식으로 작성할 수 있나요?

createFormulaValidator('C2>=B2') 처럼 셀 참조를 포함한 수식으로 표현할 수 있습니다. 수식이 true 면 유효, false 면 오류로 처리됩니다. 범위에 적용하면 상대 참조가 각 행 위치에 맞게 자동 이동합니다.

Q05

SpreadJS 시트에서 유효하지 않은 셀을 모두 찾아 색상으로 강조 표시하려면?

sheet.getDataValidator(row, col) 로 검사기 존재 여부를 확인한 뒤, sheet.isValid(row, col, sheet.getValue(row, col)) 로 현재 값의 유효성을 판정합니다. 오류 셀에 sheet.getCell(row, col).backColor('#FFCDD2') 를 적용하면 즉시 시각화됩니다.

MESCIUS SpreadJS

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

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

SpreadJS 무료 체험판 다운로드