Проверка данных
Проверка данных позволяет задавать для ячеек правила, которые гарантируют соответствие вводимых данных определённым требованиям. Она помогает предотвращать ошибки ввода и повышает точность и согласованность данных.
Сейчас поддерживаются следующие типы проверки данных:
- Число
- Целое число
- Длина текста
- Дата
- Флажок
- Раскрывающийся список (одиночный или множественный выбор)
- Пользовательская формула
Режим плагинов
Установка
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.
Импорт
Примечание о режиме плагинов
Вручную импортировать пакет 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: идентификатор правила, вызвавшего ошибку;inputValue: введённое значение, вызвавшее ошибку;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)})Обработчики событий
Полные определения типов событий приведены в разделе Events.
Модуль проверки данных предоставляет набор событий для отслеживания добавления, обновления и удаления правил, а также изменений состояния проверки. Подписаться на любое событие можно с помощью 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,})Насколько полезно это руководство?