Validación de datos

La validación de datos es una función que le permite establecer reglas en las celdas para garantizar que los datos ingresados cumplan con requisitos específicos. Ayuda a los usuarios a evitar errores de entrada y mejora la precisión y coherencia de los datos.

Actualmente, se admiten los siguientes tipos de validación de datos:

Número
Entero
Longitud del texto
Fecha
Casilla de verificación
Lista desplegable (selección única/múltiple)
Fórmula personalizada

Modo de complemento

Instalación

Shell

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

Shell

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

Shell

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

Shell

bun add @univerjs/data-validation @univerjs/sheets-data-validation @univerjs/sheets-data-validation-ui

Uso

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)

Complementos y configuración

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,})

Las opciones de configuración completas se pueden encontrar en IUniverSheetsDataValidationUIConfig.

Compatibilidad móvil

Configure primero el editor móvil. En la inicialización en modo plugin de esta página, sustituya los registros de escritorio siguientes por las exportaciones móviles de los mismos paquetes antes de abrir un documento. Conserve modelos, estilos, traducciones e importaciones Facade; no registre ambas variantes.

Paquete	Registro de escritorio	Registro móvil
`@univerjs/sheets-data-validation-ui`	`UniverSheetsDataValidationUIPlugin`	`UniverSheetsDataValidationMobileUIPlugin`

Preestablecido Modo

Instalación

Shell

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

Shell

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

Shell

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

Shell

bun add @univerjs/preset-sheets-data-validation

Uso

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(),   ],})

Preajustes y Configuración

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,})

Las opciones de configuración completas se pueden encontrar en IUniverSheetsDataValidationPresetConfig.

API de Facade

Las definiciones completas del tipo de API de Facade se pueden encontrar en FacadeAPI.

Importación

Plugin mode note

Solo el modo complemento requiere importar manualmente el paquete Facade. El modo preestablecido ya incluye el paquete Facade correspondiente, por lo que no se necesita ninguna importación adicional.

TypeScript

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

Agregar una regla de validación de datos

univerAPI.newDataValidation() puede crear un nuevo generador de validación de datos, que devuelve una instancia FDataValidationBuilder que puede generar reglas de validación de datos a través de llamadas encadenadas.

Aquí hay algunos métodos de miembros en FDataValidationBuilder:

Método	Descripción
build	Construye la regla de validación de datos.
requireCheckbox	Establece la regla de validación de datos para requerir que la entrada sea un valor booleano; este valor se representa como una casilla de verificación
requireDateAfter	Establezca el tipo de validación de datos en FECHA y configure las reglas de validación para que sean posteriores a una fecha específica
requireDateBefore	Establezca el tipo de validación de datos en FECHA y configure las reglas de validación para que sean anteriores a una fecha específica
requireDateBetween	Establezca el tipo de validación de datos en FECHA y configure las reglas de validación para que estén dentro de un rango de fechas específico
requireDateEqualTo	Establezca el tipo de validación de datos en FECHA y configure las reglas de validación para que sean iguales a una fecha específica
requireDateNotBetween	Establezca el tipo de validación de datos en FECHA y configure las reglas de validación para que no estén dentro de un rango de fechas específico
requireDateOnOrAfter	Establezca el tipo de validación de datos en FECHA y configure las reglas de validación para que sean en o después de una fecha específica
requireDateOnOrBefore	Establezca el tipo de validación de datos en FECHA y configure las reglas de validación para que sean en o antes de una fecha específica
requireFormulaSatisfied	Establece el regla de validación de datos para requerir que la fórmula dada se evalúe como `true`
requireNumberBetween	Establece la regla de validación de datos para requerir un número que se encuentre entre, o sea cualquiera de, dos números especificados
requireNumberEqualTo	Establece la regla de validación de datos para requerir un número igual al valor dado
requireNumberGreaterThan	Establece la regla de validación de datos para requerir un número mayor que el valor dado
requireNumberGreaterThanOrEqualTo	Establece la regla de validación de datos para requerir un número mayor que o igual al valor dado
requireNumberLessThan	Establece la regla de validación de datos para que requiera un número menor que el valor dado
requireNumberLessThanOrEqualTo	Establece la regla de validación de datos para que requiera un número menor o igual al valor dado
requireNumberNotBetween	Establece la regla de validación de datos para que requiera un número que no se encuentre entre dos números especificados ni sea ninguno de ellos
requireNumberNotEqualTo	Establece la regla de validación de datos para que requiera un número no igual al valor dado
requireValueInList	Establece una regla de validación de datos que requiere que el usuario para ingresar un valor de una lista de valores específicos. Admite selección única/múltiple y mostrar/ocultar menú desplegable
requireValueInRange	Establece una regla de validación de datos que requiere que el usuario ingrese un valor dentro de un rango específico. Admite selección única/múltiple y muestra/oculta menú desplegable
setOptions	Establece las opciones para la regla de validación de datos

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)

Borrar validaciones de datos de rango

TypeScript

const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// Clear data validation of range A1:B10const fRange = fWorksheet.getRange('A1:B10')fRange.setDataValidation(null)

Obtener validaciones de datos de rango/hoja de trabajo

El objeto de regla de validación de datos devuelto es una instancia FDataValidation, que se puede usar para obtener las condiciones, opciones, etc. de la regla de validación.

Aquí hay algunos métodos de miembros en FDataValidation:

Método	Descripción
copy	Crea una nueva instancia de FDataValidationBuilder utilizando el objeto de regla actual
getCriteriaType	Obtiene el tipo de validación de datos de la regla
getCriteriaValues	Obtiene los valores utilizados para la evaluación de criterios
getHelpText	Obtiene la información del texto de ayuda, que se utiliza para proporcionar a los usuarios orientación y soporte
getRanges	Obtiene los rangos a los que se aplica la regla de validación de datos
setCriteria	Establecer criterios para la regla de validación de datos
setOptions	Establecer las opciones para la regla de validación de datos
setRanges	Establecer los rangos para la regla de validación de datos
delete	Eliminar la regla de validación de datos de la hoja de cálculo

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()

Actualizar/Eliminar validación de datos

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)

Obtener errores de validación

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)

Cada objeto de error contiene los siguientes campos:

sheetName: El nombre de la hoja de cálculo donde ocurrió el error
row: El índice de fila de la celda que desencadenó el error
column: índice de columna de la celda que desencadenó el error
ruleId: ID de la regla que desencadenó el error
inputValue: valor de entrada que desencadenó el error
rule: instantánea del contenido de la regla

Obtener validador status

El estado del validador es un valor de enumeración de DataValidationStatus, que incluye:

valid: el valor de la celda pasa la validación
invalid: el valor de la celda no supera la validación
validating: la celda se está validando

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)})

Evento Oyentes

Para las definiciones completas de los tipos de eventos, consulte Eventos.

El módulo de validación de datos proporciona una serie de eventos para monitorear las adiciones, actualizaciones, eliminaciones y cambios de estado de validación de reglas de validación. Todos los eventos se pueden escuchar usando univerAPI.addEvent().

Eventos de cambio de regla de validación

univerAPI.Event.SheetDataValidationChanged: se activa después de que cambia una regla de validación

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: se activa antes de agregar una regla de validación

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: se activa antes de eliminar una regla de validación

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: Activado antes de eliminar todas las reglas de validación

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()`

Eventos de actualización de reglas de validación

univerAPI.Event.BeforeSheetDataValidationCriteriaUpdate: Activado antes de actualizar los criterios de la regla de validación

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: Activado antes de actualizar la regla de validación rangos

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: Activado antes de actualizar las opciones de la regla de validación

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()`

Eventos de estado de validación

univerAPI.Event.SheetDataValidatorStatusChanged: Se activa cuando cambia el estado de validación de una celda

TypeScript

const disposable = univerAPI.addEvent(univerAPI.Event.SheetDataValidatorStatusChanged, (params) => {  const { worksheet, workbook, row, column, status, rule } = params})// Remove the event listener, use `disposable.dispose()`

Cada evento incluye los siguientes parámetros comunes:

workbook: Instancia de libro de trabajo actual
worksheet: Instancia de hoja de trabajo actual

Parámetros especiales:

rule: El objeto de regla de validación relacionado
ruleId: Identificador único de la regla de validación
status: Estado de validación (solo en el evento SheetDataValidatorStatusChanged)
newCriteria: Nuevo criterio de validación (solo en BeforeSheetDataValidationCriteriaUpdate event)
newRanges: nuevos rangos de validación (solo en el evento BeforeSheetDataValidationRangeUpdate)
newOptions: nuevas opciones de validación (solo en el evento BeforeSheetDataValidationOptionsUpdate)

Todas las devoluciones de llamada de eventos con el prefijo Before pueden usar params.cancel = true para evitar la operación correspondiente.

Estilo de error

La opción errorStyle controla el comportamiento cuando se ingresan datos no válidos. Es un valor de enumeración de DataValidationErrorStyle, que incluye:

STOP: evita que el usuario ingrese datos no válidos
WARNING: permite al usuario ingresar datos no válidos, pero muestra una advertencia
INFO: permite al usuario ingresar datos no válidos, pero muestra una información mensaje

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)

Cambiar modo de renderizado de lista

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,})

¿Cómo es esta guía?