데이터 유효성 검사
데이터 유효성 검사는 셀에 규칙을 설정해 입력된 데이터가 특정 요건을 충족하도록 하는 기능입니다. 입력 오류를 방지하고 데이터의 정확성과 일관성을 높이는 데 도움이 됩니다.
현재 다음 데이터 유효성 검사 유형을 지원합니다.
- 숫자
- 정수
- 텍스트 길이
- 날짜
- 체크박스
- 드롭다운 목록(단일/다중 선택)
- 사용자 지정 수식
플러그인 모드
설치
pnpm add @univerjs/data-validation @univerjs/sheets-data-validation @univerjs/sheets-data-validation-uinpm install @univerjs/data-validation @univerjs/sheets-data-validation @univerjs/sheets-data-validation-uiyarn add @univerjs/data-validation @univerjs/sheets-data-validation @univerjs/sheets-data-validation-uibun add @univerjs/data-validation @univerjs/sheets-data-validation @univerjs/sheets-data-validation-ui사용법
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)플러그인 및 설정
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-ui | UniverSheetsDataValidationUIPlugin | UniverSheetsDataValidationMobileUIPlugin |
프리셋 모드
설치
pnpm add @univerjs/preset-sheets-data-validationnpm install @univerjs/preset-sheets-data-validationyarn add @univerjs/preset-sheets-data-validationbun add @univerjs/preset-sheets-data-validation사용법
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(), ],})프리셋 및 설정
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 패키지가 이미 포함되어 있으므로 별도로 가져올 필요가 없습니다.
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 | 데이터 유효성 검사 규칙의 옵션을 설정합니다. |
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)범위의 데이터 유효성 검사 지우기
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 | 워크시트에서 데이터 유효성 검사 규칙을 삭제합니다. |
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()데이터 유효성 검사 업데이트/삭제
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)유효성 검사 오류 가져오기
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: 오류를 일으킨 규칙의 IDinputValue: 오류를 일으킨 입력값rule: 규칙 내용의 스냅샷
유효성 검사기 상태 가져오기
유효성 검사기 상태는 DataValidationStatus 열거형 값이며 다음 상태를 포함합니다.
valid: 셀 값이 유효성 검사를 통과함invalid: 셀 값이 유효성 검사를 통과하지 못함validating: 셀을 검사하는 중
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: 유효성 검사 규칙이 변경된 후 트리거됩니다.
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: 유효성 검사 규칙을 추가하기 전에 트리거됩니다.
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: 유효성 검사 규칙을 삭제하기 전에 트리거됩니다.
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: 모든 유효성 검사 규칙을 삭제하기 전에 트리거됩니다.
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: 유효성 검사 규칙의 조건을 업데이트하기 전에 트리거됩니다.
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: 유효성 검사 규칙의 범위를 업데이트하기 전에 트리거됩니다.
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: 유효성 검사 규칙의 옵션을 업데이트하기 전에 트리거됩니다.
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: 셀의 유효성 검사 상태가 변경될 때 트리거됩니다.
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: 유효하지 않은 데이터 입력을 허용하지만 안내 메시지를 표시합니다.
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)목록 렌더링 모드 변경
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,})이 가이드는 어떠셨나요?