# Validación de datos - Human documentation: [https://docs.univer.ai/es-ES/guides/sheets/features/data-validation](https://docs.univer.ai/es-ES/guides/sheets/features/data-validation) - Agent Markdown: [https://docs.univer.ai/es-ES/guides/sheets/features/data-validation.md](https://docs.univer.ai/es-ES/guides/sheets/features/data-validation.md) - Requested language: `es-ES` - Content language: `es-ES` - Documentation version: `1.2.0` - Source: [sheets/features/data-validation.es-ES.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/sheets/features/data-validation.es-ES.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 } ``` 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 #### 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 ``` ### Uso ```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 ++] ``` ### 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`](https://github.com/dream-num/univer/blob/dev/packages/sheets-data-validation-ui/src/config/config.ts). ## Compatibilidad móvil Configure primero el [editor móvil](https://docs.univer.ai/es-ES/guides/sheets/getting-started/installation.md#mobile-support). 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 #### 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 ``` ### 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' // [!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 ++] ], }) ``` ### 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`](https://github.com/dream-num/univer/tree/dev/presets/packages/preset-sheets-data-validation). ## API de Facade Las definiciones completas del tipo de API de Facade se pueden encontrar en [FacadeAPI](https://docs.univer.ai/es-ES/reference/facade.md). ### Importación > [!INFO: 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()`](https://docs.univer.ai/es-ES/reference/facade/univer.md#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`](https://docs.univer.ai/es-ES/reference/facade/data-validation-builder.md): | 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: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) ``` ### Borrar validaciones de datos de rango ```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) ``` ### 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`](https://docs.univer.ai/es-ES/reference/facade/data-validation.md): | 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: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) ``` ### 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](https://docs.univer.ai/es-ES/reference/facade/events.md). 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, }) ```