SpreadJS로 웹 입력 폼 데이터 검증 구현하기
React·Vue·Angular로 웹 애플리케이션을 개발하다 보면 "사용자가 잘못된 값을 입력했을 때 서버 요청 없이 즉시 오류를 잡아야 한다"는 요구사항을 자주 마주합니다. SpreadJS는 엑셀과 동일한 셀 단위 데이터 검증 기능을 JavaScript로 구현할 수 있는 웹 스프레드시트 컴포넌트로, GC.Spread.Sheets.DataValidation
API를 통해 숫자·날짜·텍스트·목록·수식 등 6가지 유효성 검사 타입을 몇 줄의 코드로 선언적으로 적용할 수 있습니다.
검사 로직을 직접 구현하다 보면 조건문이 셀 수만큼 늘어나고, 비즈니스 규칙이 바뀔 때마다 여러 곳을 함께 수정해야 합니다. SpreadJS는 sheet.setDataValidator()
로 Validator 객체를 셀이나 범위에 한 번만 선언하면 되어, 검사 규칙을 중앙에서 체계적으로 관리할 수 있습니다.
이 글에서는 기초적인 숫자·날짜 범위 검사부터 셀 범위와 연동되는 드롭다운 목록, 크로스셀 조건을 수식으로 표현하는 커스텀 Formula Validator, 오류 UX 제어, 시트 전체 일괄 검사까지 실무에 바로 활용할 수 있는 코드 예제로 단계별 안내합니다.

SpreadJS DataValidation이란? 6가지 검사 타입 한눈에 보기
SpreadJS 유효성 검사는 GC.Spread.Sheets.DataValidation
네임스페이스에서 6가지 팩토리 메서드로 생성하고, sheet.setDataValidator()
로 셀 또는 범위에 적용합니다. spread.options.highlightInvalidData = true
를 설정하면 유효하지 않은 셀에 즉시 빨간 원이 표시됩니다.
| 팩토리 메서드 | 검사 기준 |
|---|---|
createNumberValidator
|
정수·소수 범위 |
createDateValidator
|
날짜 범위 |
createTextLengthValidator
|
텍스트 길이 |
createListValidator
|
정적 쉼표 구분 목록 |
createFormulaListValidator
|
셀 범위 동적 목록 |
createFormulaValidator
|
커스텀 수식 (true/false 반환) |
아래 데모는 수량(정수 1~100), 납기일(2025년 범위), 비고(50자 이하) 세 가지 검사를 한 화면에 구성합니다.
STEP 1: CDN 라이브러리 참조
STEP 2: HTML 구조
STEP 3: JavaScript
setDataValidator(row, col, dv)
는 단일 셀, setDataValidator(row, col, rowCount, colCount, dv)
는 범위 전체에 한 번에 적용합니다. 입력 폼 열 전체에 검사를 적용할 때 유용합니다.
드롭다운 목록 검사 구현하기: 고정 값 목록 vs 셀 범위 동적 연동
목록 유효성 검사는 두 가지 방식으로 구성합니다. 값이 고정되면 createListValidator
로 쉼표 구분 문자열을 직접 전달하고, 마스터 데이터를 참조하려면 createFormulaListValidator
에 셀 범위 수식을 전달합니다. 후자는 범위의 데이터를 변경하면 드롭다운 목록이 자동으로 갱신되어 ERP·MES 환경의 동적 코드 테이블에 적합합니다.
STEP 2: HTML 구조
STEP 3: JavaScript
createFormulaListValidator
에 절대 참조( $E$1:$E$4
)를 사용하면 검사 범위가 셀 위치에 관계없이 고정됩니다. 마스터 데이터가 동적으로 추가되는 경우 $E$1:$E$100
처럼 여유 범위를 잡아두거나, 해당 열을 Excel 표(Table)로 구성하세요.dv.inCellDropdown(false)
로 설정하면 드롭다운 버튼이 사라지고 직접 입력만 허용됩니다. 사용자가 선택지를 알아야 하는 폼에서는 기본값(true)을 유지하는 것이 UX상 권장됩니다.복잡한 조건 검사를 수식 한 줄로: 커스텀 Formula Validator 사용법
createFormulaValidator(formula)
는 수식 결과가 true
일 때만 유효한 것으로 판정합니다. "종료일이 시작일보다 커야 한다", "할인율이 마진율을 초과할 수 없다" 같은 크로스셀 규칙을 JavaScript 코드 없이 스프레드시트 수식으로 표현할 수 있어 유지보수가 간편합니다. 범위에 적용하면 상대 참조가 각 행 위치에 맞게 자동 이동합니다.
STEP 2: HTML 구조
STEP 3: JavaScript
setDataValidator(1, 2, 4, 1, dv)
로 범위에 적용하면 수식이 각 행의 상대 참조로 자동 이동합니다. C2>=B2
로 지정해도 3행에는 C3>=B3
으로 동작하는 방식은 Excel 데이터 유효성 검사와 동일합니다.
입력 오류를 사용자에게 알리는 방법: 에러 스타일과 이벤트 처리
에러 스타일은 잘못된 입력을 얼마나 강하게 제한할지 결정합니다. ErrorStyle.stop
/ ErrorStyle.warning
/ ErrorStyle.information
은 유효성 검사 실패 유형을 구분하기 위한 설정값이며, 각각을 어떻게 제한할 것인지에 대해서는 ValidationError
이벤트를 사용하여 입력 허용·거부·재입력을 코드로 제어해야 합니다.
ValidationError
이벤트의 args.validationResult
를 DataValidationResult.forceApply
로 설정하면 오류 값이 그대로 셀에 저장됩니다. discard
로 설정하면 이전 값으로 복원하고, retry
로 설정하면 편집 모드를 유지합니다.시트 전체에서 오류 셀을 자동으로 찾아 하이라이트하는 방법
제출 버튼을 누르기 전 시트 전체를 검사하고 오류 셀을 한눈에 표시하는 패턴은 데이터 입력 폼에서 필수입니다. sheet.getDataValidator(row, col)
로 검사기 존재 여부를 확인하고, sheet.isValid(row, col, value)
로 현재 값을 판정한 뒤, 오류 셀에 backColor
를 적용해 즉시 시각화합니다.
STEP 2: HTML 구조
STEP 3: JavaScript
highlightInvalidData
를 false
로 설정하고 저장·제출 시점에만 isValid()
배치 검사를 실행하면, 편집 중에는 조용한 UX를 제공하다가 제출 전에 한 번에 오류 셀을 표시하는 "저장 전 일괄 검증" 패턴을 구현할 수 있습니다.자주 묻는 질문 (FAQ)
JavaScript로 웹 스프레드시트 셀에 숫자 입력 범위를 제한하려면 어떻게 하나요?
GC.Spread.Sheets.DataValidation.createNumberValidator(ComparisonOperators.between, '최솟값', '최댓값', true)
로 Validator를 만들고 sheet.setDataValidator(row, col, dv)
로 셀에 적용합니다. 네 번째 인수 true
는 정수 전용, false
는 소수 허용입니다.
SpreadJS에서 다른 셀 범위 데이터를 드롭다운 목록으로 연동하는 방법은 무엇인가요?
createFormulaListValidator('$A$1:$A$10')
형식으로 절대 참조 범위를 전달하면 해당 범위의 값이 드롭다운으로 표시되고, 범위 데이터를 변경하면 목록이 자동으로 갱신됩니다.
SpreadJS 유효성 검사 오류 팝업의 제목과 내용을 한국어로 변경하는 방법은?
dv.showErrorMessage(true)
, dv.errorTitle('한국어 제목')
, dv.errorMessage('한국어 메시지')
세 메서드를 연속 호출하면 오류 팝업의 제목과 내용을 자유롭게 설정할 수 있습니다. 각 메서드는 validator 객체를 반환해 체이닝도 가능합니다.
SpreadJS에서 두 셀 값을 비교하는 커스텀 검증 규칙을 수식으로 작성할 수 있나요?
createFormulaValidator('C2>=B2')
처럼 셀 참조를 포함한 수식으로 표현할 수 있습니다. 수식이 true
면 유효, false
면 오류로 처리됩니다. 범위에 적용하면 상대 참조가 각 행 위치에 맞게 자동 이동합니다.
SpreadJS 시트에서 유효하지 않은 셀을 모두 찾아 색상으로 강조 표시하려면?
sheet.getDataValidator(row, col)
로 검사기 존재 여부를 확인한 뒤, sheet.isValid(row, col, sheet.getValue(row, col))
로 현재 값의 유효성을 판정합니다. 오류 셀에 sheet.getCell(row, col).backColor('#FFCDD2')
를 적용하면 즉시 시각화됩니다.
