Web SDK

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

Проверка данных позволяет задавать для ячеек правила, которые гарантируют соответствие вводимых данных определённым требованиям. Она помогает предотвращать ошибки ввода и повышает точность и согласованность данных.

Сейчас поддерживаются следующие типы проверки данных:

  • Число
  • Целое число
  • Длина текста
  • Дата
  • Флажок
  • Раскрывающийся список (одиночный или множественный выбор)
  • Пользовательская формула

Режим плагинов

Установка

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.

Импорт

Примечание о режиме плагинов

Вручную импортировать пакет 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: идентификатор правила, вызвавшего ошибку;
  • 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.

Модуль проверки данных предоставляет набор событий для отслеживания добавления, обновления и удаления правил, а также изменений состояния проверки. Подписаться на любое событие можно с помощью 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.