데이터 유효성 검사

데이터 유효성 검사는 셀에 규칙을 설정해 입력된 데이터가 특정 요건을 충족하도록 하는 기능입니다. 입력 오류를 방지하고 데이터의 정확성과 일관성을 높이는 데 도움이 됩니다.

현재 다음 데이터 유효성 검사 유형을 지원합니다.

  • 숫자
  • 정수
  • 텍스트 길이
  • 날짜
  • 체크박스
  • 드롭다운 목록(단일/다중 선택)
  • 사용자 지정 수식

플러그인 모드

설치

Shell
pnpm add @univerjs/data-validation @univerjs/sheets-data-validation @univerjs/sheets-data-validation-ui

사용법

TypeScript
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'import { UniverDataValidationPlugin } from '@univerjs/data-validation'import { UniverSheetsDataValidationPlugin } from '@univerjs/sheets-data-validation'import { UniverSheetsDataValidationUIPlugin } from '@univerjs/sheets-data-validation-ui'import SheetsDataValidationEnUS from '@univerjs/sheets-data-validation-ui/locale/en-US'import '@univerjs/sheets-data-validation-ui/lib/index.css'import '@univerjs/sheets-data-validation/facade'const univer = new Univer({  locale: LocaleType.EN_US,  locales: {    [LocaleType.EN_US]: mergeLocales(      SheetsDataValidationEnUS,     ),  },})univer.registerPlugin(UniverDataValidationPlugin)univer.registerPlugin(UniverSheetsDataValidationPlugin)univer.registerPlugin(UniverSheetsDataValidationUIPlugin)

플러그인 및 설정

TypeScript
univer.registerPlugin(UniverSheetsDataValidationUIPlugin, {  /**   * Whether to display the edit button in the drop-down menu   * @default true   */  showEditOnDropdown: true,  /**   * Whether to display the search box in the drop-down menu   * @default true   */  showSearchOnDropdown: true,})

전체 설정 옵션은 IUniverSheetsDataValidationUIConfig에서 확인할 수 있습니다.

모바일 지원

먼저 모바일 에디터를 구성하세요. 이 페이지의 플러그인 모드 초기화 코드에서 아래 데스크톱 등록을 같은 패키지의 모바일 버전으로 바꾸고 문서를 열기 전에 완료하세요. 모델 플러그인, 스타일, 언어 파일과 Facade 가져오기는 유지하며 두 버전을 동시에 등록하지 마세요.

패키지데스크톱 등록모바일 등록
@univerjs/sheets-data-validation-uiUniverSheetsDataValidationUIPluginUniverSheetsDataValidationMobileUIPlugin

프리셋 모드

설치

Shell
pnpm add @univerjs/preset-sheets-data-validation

사용법

TypeScript
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'import UniverPresetSheetsCoreEnUS from '@univerjs/preset-sheets-core/locales/en-US'import { UniverSheetsDataValidationPreset } from '@univerjs/preset-sheets-data-validation'import UniverPresetSheetsDataValidationEnUS from '@univerjs/preset-sheets-data-validation/locales/en-US'import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'import '@univerjs/preset-sheets-core/lib/index.css'import '@univerjs/preset-sheets-data-validation/lib/index.css'const { univerAPI } = createUniver({  locale: LocaleType.EN_US,  locales: {    [LocaleType.EN_US]: mergeLocales(      UniverPresetSheetsCoreEnUS,      UniverPresetSheetsDataValidationEnUS,     ),  },  presets: [    UniverSheetsCorePreset(),    UniverSheetsDataValidationPreset(),   ],})

프리셋 및 설정

TypeScript
UniverSheetsDataValidationPreset({  /**   * Whether to display the edit button in the drop-down menu   * @default true   */  showEditOnDropdown: true,  /**   * Whether to display the search box in the drop-down menu   * @default true   */  showSearchOnDropdown: true,})

전체 설정 옵션은 IUniverSheetsDataValidationPresetConfig에서 확인할 수 있습니다.

Facade API

전체 Facade API 타입 정의는 FacadeAPI에서 확인할 수 있습니다.

가져오기

Plugin mode note

플러그인 모드에서만 Facade 패키지를 직접 가져와야 합니다. 프리셋 모드에는 해당 Facade 패키지가 이미 포함되어 있으므로 별도로 가져올 필요가 없습니다.

TypeScript
import '@univerjs/sheets-data-validation/facade'

데이터 유효성 검사 규칙 추가

univerAPI.newDataValidation()는 새 데이터 유효성 검사 빌더를 만들고 FDataValidationBuilder 인스턴스를 반환합니다. 이 인스턴스에서 메서드를 체이닝해 데이터 유효성 검사 규칙을 생성할 수 있습니다.

다음은 FDataValidationBuilder의 주요 멤버 메서드입니다.

메서드설명
build데이터 유효성 검사 규칙을 만듭니다.
requireCheckbox입력값이 불리언 값이어야 하도록 규칙을 설정하며, 이 값은 체크박스로 렌더링됩니다.
requireDateAfter유효성 검사 유형을 DATE로 설정하고 특정 날짜 이후로 규칙을 구성합니다.
requireDateBefore유효성 검사 유형을 DATE로 설정하고 특정 날짜 이전으로 규칙을 구성합니다.
requireDateBetween유효성 검사 유형을 DATE로 설정하고 특정 날짜 범위 내로 규칙을 구성합니다.
requireDateEqualTo유효성 검사 유형을 DATE로 설정하고 특정 날짜와 같도록 규칙을 구성합니다.
requireDateNotBetween유효성 검사 유형을 DATE로 설정하고 특정 날짜 범위 밖으로 규칙을 구성합니다.
requireDateOnOrAfter유효성 검사 유형을 DATE로 설정하고 특정 날짜 당일 또는 이후로 규칙을 구성합니다.
requireDateOnOrBefore유효성 검사 유형을 DATE로 설정하고 특정 날짜 당일 또는 이전으로 규칙을 구성합니다.
requireFormulaSatisfied지정된 수식의 평가 결과가 true여야 하도록 규칙을 설정합니다.
requireNumberBetween지정된 두 숫자 사이이거나 두 숫자 중 하나인 값을 요구하도록 규칙을 설정합니다.
requireNumberEqualTo지정된 값과 같은 숫자를 요구하도록 규칙을 설정합니다.
requireNumberGreaterThan지정된 값보다 큰 숫자를 요구하도록 규칙을 설정합니다.
requireNumberGreaterThanOrEqualTo지정된 값보다 크거나 같은 숫자를 요구하도록 규칙을 설정합니다.
requireNumberLessThan지정된 값보다 작은 숫자를 요구하도록 규칙을 설정합니다.
requireNumberLessThanOrEqualTo지정된 값보다 작거나 같은 숫자를 요구하도록 규칙을 설정합니다.
requireNumberNotBetween지정된 두 숫자 사이에 있지 않고 두 숫자 중 어느 것과도 같지 않은 값을 요구하도록 규칙을 설정합니다.
requireNumberNotEqualTo지정된 값과 같지 않은 숫자를 요구하도록 규칙을 설정합니다.
requireValueInList지정된 값 목록에서 값을 입력하도록 규칙을 설정합니다. 단일/다중 선택과 드롭다운 표시/숨기기를 지원합니다.
requireValueInRange특정 범위 내의 값을 입력하도록 규칙을 설정합니다. 단일/다중 선택과 드롭다운 표시/숨기기를 지원합니다.
setOptions데이터 유효성 검사 규칙의 옵션을 설정합니다.
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// Create a new data validation rule that requires a number between 1 and 10 for the range A1:B10const fRange = fWorksheet.getRange('A1:B10')const rule = univerAPI.newDataValidation()  .requireNumberBetween(1, 10)  .setOptions({    allowBlank: true,    showErrorMessage: true,    error: 'Please enter a number between 1 and 10',  })  .build()fRange.setDataValidation(rule)

범위의 데이터 유효성 검사 지우기

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// Clear data validation of range A1:B10const fRange = fWorksheet.getRange('A1:B10')fRange.setDataValidation(null)

범위/워크시트의 데이터 유효성 검사 가져오기

반환된 데이터 유효성 검사 규칙 객체는 FDataValidation 인스턴스입니다. 이 인스턴스를 사용해 유효성 검사 규칙의 조건과 옵션 등을 가져올 수 있습니다.

다음은 FDataValidation의 주요 멤버 메서드입니다.

메서드설명
copy현재 규칙 객체를 사용해 새 FDataValidationBuilder 인스턴스를 만듭니다.
getCriteriaType규칙의 데이터 유효성 검사 유형을 가져옵니다.
getCriteriaValues조건 평가에 사용되는 값을 가져옵니다.
getHelpText사용자에게 안내와 도움을 제공하는 도움말 텍스트 정보를 가져옵니다.
getRanges데이터 유효성 검사 규칙이 적용된 범위를 가져옵니다.
setCriteria데이터 유효성 검사 규칙의 조건을 설정합니다.
setOptions데이터 유효성 검사 규칙의 옵션을 설정합니다.
setRanges데이터 유효성 검사 규칙에 범위를 설정합니다.
delete워크시트에서 데이터 유효성 검사 규칙을 삭제합니다.
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// Get all data validation rules in current sheet.const rulesOfSheet = fWorksheet.getDataValidations()// Get a data validation rule by rule ID.const ruleById = fWorksheet.getDataValidation(rulesOfSheet[0]?.rule?.uid)const fRange = fWorksheet.getRange('A1:B10')// Get first data validation rule in current range.const ruleOfRange = fRange.getDataValidation()console.log('ruleOfRange:', ruleOfRange, ruleOfRange?.getCriteriaValues())// Get all data validation rules in current range.const rulesOfRange = fRange.getDataValidations()

데이터 유효성 검사 업데이트/삭제

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// Create a new data validation rule that requires a number equal to 20 for the range A1:B10const fRange = fWorksheet.getRange('A1:B10')const rule = univerAPI.newDataValidation()  .requireNumberEqualTo(20)  .build()fRange.setDataValidation(rule)const newRuleRange = fWorksheet.getRange('C1:D10')// Update the rule after 3 secondssetTimeout(() => {  fRange.getDataValidation()    // Change the range to C1:D10    .setRanges([newRuleRange])    // Change the criteria to require a number between 1 and 10    .setCriteria(      univerAPI.Enum.DataValidationType.DECIMAL,      [univerAPI.Enum.DataValidationOperator.BETWEEN, '1', '10'],    )    // Change option to stop input on validation errors and show error message    .setOptions({      allowBlank: true,      showErrorMessage: true,      error: 'Please enter a valid value',      errorStyle: univerAPI.Enum.DataValidationErrorStyle.STOP,    })}, 3000)// Delete the rule after 6 secondssetTimeout(() => {  newRuleRange.getDataValidation().delete()}, 6000)

유효성 검사 오류 가져오기

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// Get all data validation errors for current workbook.const workbookErrors = await fWorkbook.getAllDataValidationErrorAsync()console.log('workbookErrors:', workbookErrors)// Get all data validation errors for current sheet.const worksheetErrors = await fWorksheet.getAllDataValidationErrorAsync()console.log('worksheetErrors:', worksheetErrors)// Get data validation errors for current range.const fRange = fWorksheet.getRange('A1:B10')const rangeErrors = await fRange.getDataValidationErrorAsync()console.log('rangeErrors:', rangeErrors)

각 오류 객체에는 다음 필드가 포함됩니다.

  • sheetName: 오류가 발생한 워크시트의 이름
  • row: 오류를 일으킨 셀의 행 인덱스
  • column: 오류를 일으킨 셀의 열 인덱스
  • ruleId: 오류를 일으킨 규칙의 ID
  • inputValue: 오류를 일으킨 입력값
  • rule: 규칙 내용의 스냅샷

유효성 검사기 상태 가져오기

유효성 검사기 상태는 DataValidationStatus 열거형 값이며 다음 상태를 포함합니다.

  • valid: 셀 값이 유효성 검사를 통과함
  • invalid: 셀 값이 유효성 검사를 통과하지 못함
  • validating: 셀을 검사하는 중
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// Get data validation validator status for current workbook.fWorkbook.getValidatorStatus().then((status) => {  console.log('===statusOfWorkbook', status)})// Get data validation validator status for current sheet.fWorksheet.getValidatorStatusAsync().then((status) => {})// Get data validation validator status for current range.const fRange = fWorksheet.getRange('A1:B10')fRange.getValidatorStatus().then((status) => {  console.log('===tatusOfRange', status)})

이벤트 리스너

전체 이벤트 타입 정의는 이벤트를 참조하세요.

데이터 유효성 검사 모듈은 유효성 검사 규칙의 추가, 업데이트, 삭제와 유효성 검사 상태 변경을 모니터링하는 여러 이벤트를 제공합니다. 모든 이벤트는 univerAPI.addEvent()로 수신할 수 있습니다.

유효성 검사 규칙 변경 이벤트

univerAPI.Event.SheetDataValidationChanged: 유효성 검사 규칙이 변경된 후 트리거됩니다.

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.SheetDataValidationChanged, (params) => {  const { origin, worksheet, workbook, changeType, oldRule, rule } = params})// Remove the event listener, use `disposable.dispose()`

univerAPI.Event.BeforeSheetDataValidationAdd: 유효성 검사 규칙을 추가하기 전에 트리거됩니다.

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationAdd, (params) => {  const { worksheet, workbook, rule } = params  // Cancel the data validation rule addition operation  params.cancel = true})// Remove the event listener, use `disposable.dispose()`

univerAPI.Event.BeforeSheetDataValidationDelete: 유효성 검사 규칙을 삭제하기 전에 트리거됩니다.

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationDelete, (params) => {  const { worksheet, workbook, ruleId, rule } = params  // Cancel the data validation rule deletion operation  params.cancel = true})// Remove the event listener, use `disposable.dispose()`

univerAPI.Event.BeforeSheetDataValidationDeleteAll: 모든 유효성 검사 규칙을 삭제하기 전에 트리거됩니다.

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationDeleteAll, (params) => {  const { worksheet, workbook, rules } = params  // Cancel the data validation rule deletion operation  params.cancel = true})// Remove the event listener, use `disposable.dispose()`

유효성 검사 규칙 업데이트 이벤트

univerAPI.Event.BeforeSheetDataValidationCriteriaUpdate: 유효성 검사 규칙의 조건을 업데이트하기 전에 트리거됩니다.

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationCriteriaUpdate, (params) => {  const { worksheet, workbook, ruleId, rule, newCriteria } = params  // Cancel the data validation rule criteria update operation  params.cancel = true})// Remove the event listener, use `disposable.dispose()`

univerAPI.Event.BeforeSheetDataValidationRangeUpdate: 유효성 검사 규칙의 범위를 업데이트하기 전에 트리거됩니다.

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationRangeUpdate, (params) => {  const { worksheet, workbook, ruleId, rule, newRanges } = params  // Cancel the data validation rule range update operation  params.cancel = true})// Remove the event listener, use `disposable.dispose()`

univerAPI.Event.BeforeSheetDataValidationOptionsUpdate: 유효성 검사 규칙의 옵션을 업데이트하기 전에 트리거됩니다.

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationOptionsUpdate, (params) => {  const { worksheet, workbook, ruleId, rule, newOptions } = params  // Cancel the data validation rule options update operation  params.cancel = true})// Remove the event listener, use `disposable.dispose()`

유효성 검사 상태 이벤트

univerAPI.Event.SheetDataValidatorStatusChanged: 셀의 유효성 검사 상태가 변경될 때 트리거됩니다.

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.SheetDataValidatorStatusChanged, (params) => {  const { worksheet, workbook, row, column, status, rule } = params})// Remove the event listener, use `disposable.dispose()`

각 이벤트에는 다음 공통 매개변수가 포함됩니다.

  • workbook: 현재 통합 문서 인스턴스
  • worksheet: 현재 워크시트 인스턴스

특수 매개변수:

  • rule: 관련 유효성 검사 규칙 객체
  • ruleId: 유효성 검사 규칙의 고유 식별자
  • status: 유효성 검사 상태(SheetDataValidatorStatusChanged 이벤트에만 해당)
  • newCriteria: 새 유효성 검사 조건(BeforeSheetDataValidationCriteriaUpdate 이벤트에만 해당)
  • newRanges: 새 유효성 검사 범위(BeforeSheetDataValidationRangeUpdate 이벤트에만 해당)
  • newOptions: 새 유효성 검사 옵션(BeforeSheetDataValidationOptionsUpdate 이벤트에만 해당)

이름이 Before로 시작하는 모든 이벤트의 콜백에서는 params.cancel = true를 사용해 해당 작업을 중단할 수 있습니다.

오류 스타일

errorStyle 옵션은 유효하지 않은 데이터가 입력되었을 때의 동작을 제어합니다. 이 옵션은 DataValidationErrorStyle 열거형 값이며 다음 항목을 포함합니다.

  • STOP: 사용자가 유효하지 않은 데이터를 입력하지 못하게 합니다.
  • WARNING: 유효하지 않은 데이터 입력을 허용하지만 경고를 표시합니다.
  • INFO: 유효하지 않은 데이터 입력을 허용하지만 안내 메시지를 표시합니다.
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const fRange = fWorksheet.getRange('A1:B10')const rule = univerAPI.newDataValidation()  .requireNumberBetween(1, 10)  .setOptions({    allowBlank: true,    showErrorMessage: true,    error: 'Please enter a number between 1 and 10',    errorStyle: univerAPI.Enum.DataValidationErrorStyle.STOP,  })  .build()fRange.setDataValidation(rule)

목록 렌더링 모드 변경

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const fRange = fWorksheet.getRange('A1:B10')fRange.getDataValidation()?.setOptions({  // support TEXT, ARROW, CUSTOM  // default is `CUSTOM`  renderMode: univerAPI.Enum.DataValidationRenderMode.TEXT,})

이 가이드는 어떠셨나요?

© 2026 DreamNum Co., Ltd.