# 데이터 유효성 검사

- Human documentation: [https://docs.univer.ai/ko-KR/guides/sheets/features/data-validation](https://docs.univer.ai/ko-KR/guides/sheets/features/data-validation)

- Agent Markdown: [https://docs.univer.ai/ko-KR/guides/sheets/features/data-validation.md](https://docs.univer.ai/ko-KR/guides/sheets/features/data-validation.md)

- Requested language: `ko-KR`

- Content language: `ko-KR`

- Documentation version: `1.0.4`

- Source: [sheets/features/data-validation.ko-KR.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/sheets/features/data-validation.ko-KR.mdx)

---

#### Package metadata

```json
{
  "preset": [
    {
      "client": "@univerjs/preset-sheets-data-validation",
      "locale": "@univerjs/preset-sheets-data-validation/locales/en-US",
      "style": "@univerjs/preset-sheets-data-validation/lib/index.css"
    }
  ],
  "plugins": [
    {
      "client": "@univerjs/data-validation",
      "locale": "@univerjs/data-validation/locale/en-US"
    },
    {
      "client": "@univerjs/sheets-data-validation",
      "facade": "@univerjs/sheets-data-validation/facade",
      "locale": "@univerjs/sheets-data-validation/locale/en-US"
    },
    {
      "client": "@univerjs/sheets-data-validation-ui",
      "locale": "@univerjs/sheets-data-validation-ui/locale/en-US",
      "style": "@univerjs/sheets-data-validation-ui/lib/index.css"
    }
  ],
  "mobile": true,
  "server": false
}
```

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

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

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

## 플러그인 모드

### 설치

#### npm

```bash
npm install @univerjs/data-validation @univerjs/sheets-data-validation @univerjs/sheets-data-validation-ui
```

#### pnpm

```bash
pnpm add @univerjs/data-validation @univerjs/sheets-data-validation @univerjs/sheets-data-validation-ui
```

#### yarn

```bash
yarn add @univerjs/data-validation @univerjs/sheets-data-validation @univerjs/sheets-data-validation-ui
```

#### bun

```bash
bun 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' // [!code ++]
import { UniverSheetsDataValidationPlugin } from '@univerjs/sheets-data-validation' // [!code ++]
import { UniverSheetsDataValidationUIPlugin } from '@univerjs/sheets-data-validation-ui' // [!code ++]
import SheetsDataValidationEnUS from '@univerjs/sheets-data-validation-ui/locale/en-US' // [!code ++]
import '@univerjs/sheets-data-validation-ui/lib/index.css' // [!code ++]
import '@univerjs/sheets-data-validation/facade' // [!code ++]

const univer = new Univer({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: mergeLocales(
      SheetsDataValidationEnUS, // [!code ++]
    ),
  },
})

univer.registerPlugin(UniverDataValidationPlugin) // [!code ++]
univer.registerPlugin(UniverSheetsDataValidationPlugin) // [!code ++]
univer.registerPlugin(UniverSheetsDataValidationUIPlugin) // [!code ++]
```

### 플러그인 및 설정

```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`](https://github.com/dream-num/univer/blob/dev/packages/sheets-data-validation-ui/src/config/config.ts)에서 확인할 수 있습니다.

## 모바일 지원

먼저 [모바일 에디터](https://docs.univer.ai/ko-KR/guides/sheets/getting-started/installation.md#mobile-support)를 구성하세요. 이 페이지의 플러그인 모드 초기화 코드에서 아래 데스크톱 등록을 같은 패키지의 모바일 버전으로 바꾸고 **문서를 열기 전에** 완료하세요. 모델 플러그인, 스타일, 언어 파일과 Facade 가져오기는 유지하며 두 버전을 동시에 등록하지 마세요.

| 패키지                                   | 데스크톱 등록                              | 모바일 등록                                     |
| ------------------------------------- | ------------------------------------ | ------------------------------------------ |
| `@univerjs/sheets-data-validation-ui` | `UniverSheetsDataValidationUIPlugin` | `UniverSheetsDataValidationMobileUIPlugin` |

## 프리셋 모드

### 설치

#### npm

```bash
npm install @univerjs/preset-sheets-data-validation
```

#### pnpm

```bash
pnpm add @univerjs/preset-sheets-data-validation
```

#### yarn

```bash
yarn add @univerjs/preset-sheets-data-validation
```

#### bun

```bash
bun 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' // [!code ++]
import UniverPresetSheetsDataValidationEnUS from '@univerjs/preset-sheets-data-validation/locales/en-US' // [!code ++]
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'
import '@univerjs/preset-sheets-core/lib/index.css'
import '@univerjs/preset-sheets-data-validation/lib/index.css' // [!code ++]

const { univerAPI } = createUniver({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: mergeLocales(
      UniverPresetSheetsCoreEnUS,
      UniverPresetSheetsDataValidationEnUS, // [!code ++]
    ),
  },
  presets: [
    UniverSheetsCorePreset(),
    UniverSheetsDataValidationPreset(), // [!code ++]
  ],
})
```

### 프리셋 및 설정

```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`](https://github.com/dream-num/univer/tree/dev/presets/packages/preset-sheets-data-validation)에서 확인할 수 있습니다.

## Facade API

전체 Facade API 타입 정의는 [FacadeAPI](https://docs.univer.ai/ko-KR/reference/facade.md)에서 확인할 수 있습니다.

### 가져오기

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

```typescript
import '@univerjs/sheets-data-validation/facade'
```

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

[`univerAPI.newDataValidation()`](https://docs.univer.ai/ko-KR/reference/facade/univer.md#newdatavalidation)는 새 데이터 유효성 검사 빌더를 만들고 `FDataValidationBuilder` 인스턴스를 반환합니다. 이 인스턴스에서 메서드를 체이닝해 데이터 유효성 검사 규칙을 생성할 수 있습니다.

다음은 [`FDataValidationBuilder`](https://docs.univer.ai/ko-KR/reference/facade/data-validation-builder.md)의 주요 멤버 메서드입니다.

| 메서드                               | 설명                                                           |
| --------------------------------- | ------------------------------------------------------------ |
| 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:B10
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',
  })
  .build()
fRange.setDataValidation(rule)
```

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

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// Clear data validation of range A1:B10
const fRange = fWorksheet.getRange('A1:B10')
fRange.setDataValidation(null)
```

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

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

다음은 [`FDataValidation`](https://docs.univer.ai/ko-KR/reference/facade/data-validation.md)의 주요 멤버 메서드입니다.

| 메서드               | 설명                                                 |
| ----------------- | -------------------------------------------------- |
| 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:B10
const 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 seconds
setTimeout(() => {
  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 seconds
setTimeout(() => {
  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)
})
```

### 이벤트 리스너

전체 이벤트 타입 정의는 [이벤트](https://docs.univer.ai/ko-KR/reference/facade/events.md)를 참조하세요.

데이터 유효성 검사 모듈은 유효성 검사 규칙의 추가, 업데이트, 삭제와 유효성 검사 상태 변경을 모니터링하는 여러 이벤트를 제공합니다. 모든 이벤트는 `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,
})
```