# Проверка данных

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

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

- Requested language: `ru-RU`

- Content language: `ru-RU`

- Documentation version: `1.2.0`

- Source: [sheets/features/data-validation.ru-RU.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/sheets/features/data-validation.ru-RU.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/ru-RU/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/ru-RU/reference/facade.md).

### Импорт

> [!INFO: Примечание о режиме плагинов]
> Вручную импортировать пакет Facade требуется только в режиме плагинов. В режиме предустановок соответствующий пакет Facade уже подключён, поэтому дополнительный импорт не нужен.

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

### Добавление правила проверки данных

Метод [`univerAPI.newDataValidation()`](https://docs.univer.ai/ru-RU/reference/facade/univer.md#newdatavalidation) создаёт новый построитель проверки данных и возвращает экземпляр `FDataValidationBuilder`. С помощью цепочки вызовов можно сформировать правило проверки данных.

Ниже перечислены некоторые методы [`FDataValidationBuilder`](https://docs.univer.ai/ru-RU/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/ru-RU/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`: идентификатор правила, вызвавшего ошибку;
* `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)
})
```

### Обработчики событий

Полные определения типов событий приведены в разделе [Events](https://docs.univer.ai/ru-RU/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,
})
```