# Fórmula - Human documentation: [https://docs.univer.ai/es-ES/guides/sheets/features/core/formula](https://docs.univer.ai/es-ES/guides/sheets/features/core/formula) - Agent Markdown: [https://docs.univer.ai/es-ES/guides/sheets/features/core/formula.md](https://docs.univer.ai/es-ES/guides/sheets/features/core/formula.md) - Requested language: `es-ES` - Content language: `es-ES` - Documentation version: `1.2.0` - Source: [sheets/features/core/formula.es-ES.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/sheets/features/core/formula.es-ES.mdx) --- Las fórmulas son una de las capacidades principales proporcionadas por Univer, lo que le permite usar fórmulas en celdas para calcular valores. Las funciones admitidas por las fórmulas son consistentes con Excel, incluidas funciones matemáticas, lógicas, de texto, de fecha y más. Si un libro contiene una gran cantidad de fórmulas, el cálculo de fórmulas puede ocupar el hilo principal y hacer que la página responda menos. Recomendamos ejecutar el cálculo de fórmulas en un proceso de trabajo para reducir su impacto en la representación y la interacción del usuario. Para obtener detalles de configuración, consulte [Web Workers](https://docs.univer.ai/es-ES/guides/sheets/getting-started/worker.md). ## Configuración A continuación se muestran los enlaces a los elementos de configuración relacionados con el complemento de fórmula: | Complemento | Elemento de configuración | | -------------------------- | ------------------------------------------------------------------------------------- | | `@univerjs/engine-formula` | [IUniverEngineFormulaConfig](https://docs.univer.ai/es-ES/reference/packages/plugins/univerjs/engine-formula.md) | | `@univerjs/sheets-formula` | [IUniverSheetsFormulaBaseConfig](https://docs.univer.ai/es-ES/reference/packages/plugins/univerjs/sheets-formula.md) | `initialFormulaComputing` controla el cálculo al cargar el libro. Si los resultados guardados están desactualizados, `CalculationMode.FORCED` los recalcula. En modo preestablecido, coloque la misma opción dentro de `formula`. Elija su modo e incorpore estas opciones a la inicialización existente. Conserve los demás complementos y la configuración de idioma, tema y contenedor; no registre dos veces el mismo complemento. #### Modo de complemento ```typescript import { CalculationMode, UniverSheetsFormulaPlugin } from '@univerjs/sheets-formula' univer.registerPlugin(UniverSheetsFormulaPlugin, { initialFormulaComputing: CalculationMode.FORCED, }) ``` #### Modo preestablecido ```typescript import { CalculationMode, UniverSheetsCorePreset } from '@univerjs/preset-sheets-core' import { createUniver } from '@univerjs/presets' const { univerAPI } = createUniver({ presets: [ UniverSheetsCorePreset({ formula: { initialFormulaComputing: CalculationMode.FORCED, }, }), ], }) ``` * `CalculationMode.FORCED`: Recalcula todas las fórmulas. * `CalculationMode.WHEN_EMPTY`: Valor predeterminado: calcula solo las celdas de fórmula sin un valor `v` guardado. * `CalculationMode.NO_CALCULATION`: Omite el cálculo durante la inicialización. ## Referencias entre libros Una fórmula puede resumir en `Report` las ventas de `Sales.xlsx`. A diferencia de una referencia a otra hoja del mismo libro, también identifica el libro de origen. ### Sintaxis de referencia | Caso | Ejemplo | Destino | | ------------------------- | ------------------------------------- | ----------------------------------------------- | | Otra hoja del mismo libro | `=SUM(Data!A1:A10)` | Hoja Data del libro actual | | Rango de otro libro | `=SUM('[Sales.xlsx]Data'!A1:A10)` | Hoja Data de Sales.xlsx | | Tabla de otro libro | `=SUM(Sales.xlsx!SalesTable[Amount])` | Columna Amount de la tabla SalesTable existente | `Sales.xlsx` es un nombre de libro, no una ruta ni una URL. Escribir una fórmula no lee archivos, descarga Excel ni conecta con un editor en otra página. Crea la [tabla](https://docs.univer.ai/es-ES/guides/sheets/features/table.md) antes de usar una referencia estructurada. ### Referenciar libros cargados en la misma instancia Con el motor básico, carga ambos libros en la misma instancia de Univer y el mismo entorno de cálculo. Ejecuta el ejemplo después de inicializar Sheets. En modo plugin, importa también las extensiones Facade indicadas en esta página. ```typescript const source = univerAPI.createWorkbook({ id: 'sales-workbook', name: 'Sales.xlsx', sheetOrder: ['sales-data'], sheets: { 'sales-data': { id: 'sales-data', name: 'Data', rowCount: 100, columnCount: 20, cellData: { 0: { 0: { v: 100 } }, 1: { 0: { v: 200 } }, }, }, }, }, { makeCurrent: false }) const report = univerAPI.createWorkbook({ id: 'report-workbook', name: 'Report' }) const resultCell = report.getActiveSheet().getRange('A1') resultCell.setFormula("=SUM('[Sales.xlsx]Data'!A1:A2)") const formula = univerAPI.getFormula() formula.executeCalculation() await formula.onCalculationResultApplied() console.log(resultCell.getValue()) // 300 ``` `makeCurrent: false` carga el origen sin cambiar el libro activo. Conserva `source` y `report` para no escribir en el libro equivocado cuando cambie el libro activo. La comparación ignora mayúsculas y prioriza el nombre completo. Si no coincide, ignora extensiones habituales como `.xlsx` y `.xlsm`. Un nombre inexistente o ambiguo devuelve `#REF!`; utiliza nombres únicos. ### Vincular una referencia a un ID de origen estable Para asociar un nombre de fórmula a un ID de documento estable, utiliza la extensión Pro `@univerjs-pro/engine-formula`. Configura una [licencia de cliente](https://docs.univer.ai/es-ES/server/license.md), sustituye `UniverFormulaEnginePlugin` por `UniverProFormulaEnginePlugin` al inicializar e importa la Facade Pro. No registres ambos motores. Importar solo la Facade no registra el plugin. Este ejemplo reutiliza los libros anteriores en un entorno configurado con el motor Pro: ```typescript import '@univerjs-pro/engine-formula/facade' const reference = univerAPI.getFormula().buildReference({ hostUnitId: report.getId(), unit: { unitId: source.getId(), formulaQualifier: 'Sales Source', }, target: { kind: univerAPI.Enum.FormulaReferenceType.SHEET_RANGE, sheetName: 'Data', range: { startRow: 0, endRow: 1, startColumn: 0, endColumn: 0 }, }, }) resultCell.setFormula(`=SUM(${reference})`) ``` `hostUnitId` identifica el libro que contiene la fórmula, `unit.unitId` es el ID estable del origen y `formulaQualifier` su nombre público en la fórmula. Las coordenadas empiezan en cero e incluyen el extremo final. `buildReference()` devuelve un fragmento sin `=` y guarda la vinculación. No carga el origen ni inicia el cálculo. Los datos deben estar disponibles en un libro cargado en el entorno de cálculo o mediante un proveedor configurado. Para fórmulas escritas a mano o generadas por la aplicación, vincula primero: ```typescript const formula = univerAPI.getFormula() const bound = formula.upsertExternalReference({ unitId: report.getId(), qualifier: 'Sales Source', sourceUnitId: source.getId(), sourceUnitType: univerAPI.Enum.UniverInstanceType.UNIVER_SHEET, }) if (!bound) throw new Error('Could not bind Sales Source') resultCell.setFormula("=SUM('[Sales Source]Data'!A1:A2)") ``` Repetir la misma vinculación es idempotente. `qualifier` no lleva corchetes ni comillas. Los enteros positivos como `1` y `2` están reservados para posiciones de enlaces externos de Excel, no para ID de negocio. Conserva los recursos de enlaces al importar: copiar solo la fórmula no basta. ### Actualizar, guardar y descargar de memoria Después de modificar el origen mediante Facade, inicia el cálculo y espera a que se apliquen los resultados antes de leer el destino. No supongas que el cálculo asíncrono ha terminado al regresar de `setFormula()` o `setValue()`. ```typescript const sourceSheet = source.getSheetBySheetId('sales-data') if (!sourceSheet) throw new Error('Source sheet not found') sourceSheet.getRange('A1').setValue(150) formula.executeCalculation() await formula.onCalculationResultApplied() console.log(resultCell.getValue()) // 350 ``` Usa `report.save()` para guardar el snapshot completo, incluidos los recursos de vinculación. Guardar solo las fórmulas pierde la relación entre nombres e ID. Guarda y carga los datos de origen por separado. Al descargar el origen de memoria, las referencias ordinarias a libros cargados ya no pueden leerlo. Las referencias Pro solo pueden seguir calculando si los proveedores o cachés disponibles suministran los datos. Una vinculación no contiene los datos ni garantiza el cálculo sin conexión. Un valor anterior en pantalla no demuestra que el resultado esté actualizado. Elimina una vinculación Pro cuando deje de ser necesaria: ```typescript univerAPI.getFormula().removeExternalReference({ unitId: report.getId(), qualifier: 'Sales Source', }) ``` Eliminarla no borra ni reescribe las fórmulas. El siguiente cálculo vuelve a resolver el nombre: puede encontrar otro libro cargado con ese nombre o devolver `#REF!`. Modifica o borra también las fórmulas si quieres dejar de referenciar el origen. Consulta las [API de referencia de FFormula](https://docs.univer.ai/es-ES/reference/facade/formula.md). ## Referencias 3D Una referencia 3D abarca hojas consecutivas del mismo libro; es distinta de una referencia entre libros. ```text =SUM(Jan:Mar!B2:C3) =SUM('Jan':'Mar'!B2) ``` El rango incluye Jan, Mar y todas las hojas intermedias según el orden del libro, no alfabéticamente. Comprueba el rango de agregación cuando reordenes las hojas. ## Funciones de fórmula admitidas ## API de Facade Para obtener más detalles, consulte la [FFormula Facade API](https://docs.univer.ai/es-ES/reference/facade/formula.md). ### Importación > [!INFO: Plugin mode note] > Solo el modo complemento requiere importar manualmente el paquete Facade. El modo Preestablecido ya incluye el paquete > Fachada correspondiente, por lo que no se necesita ninguna importación adicional. ```typescript import '@univerjs/engine-formula/facade' import '@univerjs/sheets-formula/facade' import '@univerjs/sheets-formula-ui/facade' ``` ### Mostrar cuadro de diálogo de selección de rango `@univerjs/sheets-formula-ui/facade` agrega `univerAPI.showRangeSelectorDialog`. Úselo cuando su interfaz de usuario personalizada necesite que los usuarios elijan uno o más rangos con el mismo selector utilizado por los paneles relacionados con fórmulas. ```typescript const workbook = univerAPI.getActiveWorkbook() const worksheet = workbook?.getActiveSheet() if (workbook && worksheet) { await univerAPI.showRangeSelectorDialog({ unitId: workbook.getId(), subUnitId: worksheet.getSheetId(), initialValue: [ { unitId: workbook.getId(), sheetName: worksheet.getSheetName(), range: worksheet.getRange('A1:B2').getRange(), }, ], maxRangeCount: 2, supportAcrossSheet: true, callback: (ranges, isCancel) => { console.log(ranges, isCancel) }, }) } ``` ### Ejecutar el cálculo de la fórmula ```typescript const formulaEngine = univerAPI.getFormula() formulaEngine.executeCalculation() ``` ### Detener el cálculo de la fórmula ```typescript const formulaEngine = univerAPI.getFormula() formulaEngine.stopCalculation() ``` ### Inicio del cálculo de la fórmula ```typescript // Listening to formula calculation start event const formulaEngine = univerAPI.getFormula() formulaEngine.calculationStart((forceCalculate) => { console.log(forceCalculate) }) ``` ### Procesamiento del cálculo de la fórmula ```typescript // Listening to formula calculation processing event const formulaEngine = univerAPI.getFormula() formulaEngine.calculationProcessing((stageInfo) => { console.log(stageInfo) }) ``` ### Fin del cálculo de la fórmula ```typescript // Listening to formula calculation end event const formulaEngine = univerAPI.getFormula() formulaEngine.calculationEnd((functionsExecutedState) => { console.log(functionsExecutedState) }) ``` ### Resultado del cálculo de la fórmula aplicado ```typescript // Listening to formula calculation result applied event const formulaEngine = univerAPI.getFormula() formulaEngine.calculationResultApplied((result) => { console.log(result) }) // Wait for formula calculation result to be applied await formulaEngine.onCalculationResultApplied() ``` ### Establecer el modo de cálculo de la fórmula al inicializar los datos ```typescript const formulaEngine = univerAPI.getFormula() formulaEngine.setInitialFormulaComputing(CalculationMode.FORCED) ``` Si se llama a esta API después el ciclo de vida `Starting`, entrará en vigor la próxima vez que se cree una hoja Univer. Si desea que entre en vigor durante la inicialización actual de la hoja Univer, puede considerar llamarlo antes del ciclo de vida `Ready`, por ejemplo: ```typescript univerAPI.addEvent(univerAPI.Event.LifeCycleChanged, ({ stage }) => { if (stage === LifecycleStages.Starting) { const formulaEngine = univerAPI.getFormula() formulaEngine.setInitialFormulaComputing(CalculationMode.FORCED) } }) ``` ### Cálculo iterativo El cálculo iterativo se configura por libro y se guarda en el campo `calculationSettings` de su instantánea. Está desactivado de forma predeterminada: las fórmulas circulares conservan su valor almacenado o usan cero si no existe. Actívelo para modelos que utilicen referencias circulares intencionalmente. | Opción | Predeterminado | Comportamiento | | ---------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `iterativeCalculation` | `false` | Activa el cálculo iterativo de referencias circulares. | | `maxIterations` | `100` | Entero entre 1 y 32767. | | `maxChange` | `0.001` | Umbral de convergencia finito y positivo. Se detiene cuando el cambio de cada resultado numérico del grupo circular no supera este valor. | Actualice los tres ajustes juntos mediante la Facade del libro. La operación admite deshacer, rehacer y colaboración; devuelve `false` si el libro no existe o no se puede editar. Los ajustes no válidos se normalizan a sus valores predeterminados. ```ts const workbook = univerAPI.getActiveWorkbook() if (!workbook) throw new Error('No active workbook') const applied = workbook.setCalculationSettings({ iterativeCalculation: true, maxIterations: 100, maxChange: 0.001, }) if (!applied) throw new Error('Could not update calculation settings') console.log(workbook.getCalculationSettings()) ``` También puede pasar `calculationSettings` a `createWorkbook()`. Cada libro mantiene sus propios ajustes. Las opciones de cálculo de la cinta Fórmulas ofrecen los mismos controles. `getCircularReferences()` lee los diagnósticos después de aplicar los resultados, sin iniciar cálculos. Incluyen identificadores de hojas, coordenadas desde cero, grupos circulares, número de iteraciones y la información de convergencia disponible. ```ts const formula = univerAPI.getFormula() formula.executeCalculation() await formula.onCalculationResultApplied() console.table(workbook.getCircularReferences()) ``` ### Obtener resultado de ejecución de cadenas de fórmula Ejecute un lote de fórmulas de forma asincrónica y reciba resultados de cálculo: ```typescript const formulaEngine = univerAPI.getFormula() const formulas = { Book1: { Sheet1: { 2: { 3: [ // Full formula: '=SUM(A1:A10) + SQRT(D7)', // Decomposed sub-formulas (each one can be evaluated independently): 'SUM(A1:A10)', // sub-formula 1 'SQRT(D7)', // sub-formula 2 'A1:A10', // range reference 'D7', // single-cell reference ], }, 4: { 5: ['=A2 + B2 + SQRT(C5)', 'A2', 'B2', 'SQRT(C5)'], }, }, }, } const result = await formulaEngine.executeFormulas(formulas) console.log(result) ``` ## Fórmulas personalizadas Univer admite fórmulas personalizadas. Consulte la sección [Fórmulas personalizadas](/blog/custom-formula) para aprender cómo implementarlas. ## Preguntas frecuentes ### `HYPERLINK` Las celdas de fórmula no pueden operar hipervínculos Debe importar el complemento de hipervínculo para Univer Sheets. Consulte el módulo [Hipervínculo](https://docs.univer.ai/es-ES/guides/sheets/features/hyper-link.md). ## Semántica de los valores de fórmula `ISBLANK(A1)` comprueba el contenido de la celda, no solo el resultado visible. Una celda borrada está vacía aunque conserve formato; una fórmula que devuelve `""` no lo está. El literal `ISBLANK("")` también da `FALSE`. `UNIQUE` compara texto sin distinguir mayúsculas y conserva la primera grafía. `PROPER` reconoce letras Unicode, incluidas latinas acentuadas, griegas y cirílicas. `AVERAGE` agrega toda la matriz devuelta por funciones como `FILTER`. ```text =ISBLANK("") → FALSE =UNIQUE({"Univer";"univer";"Sheets"}) → {"Univer";"Sheets"} =PROPER("élise müller") → Élise Müller =AVERAGE({3;7}) → 5 ```