Manage formulas of Excel files with Node.js via C++

Introduction

One of Microsoft Excel’s compelling features is its ability to process data with formulas and functions. Microsoft Excel provides a set of built‑in functions and formulas that help users perform complex calculations quickly. Aspose.Cells also provides a huge set of built‑in functions and formulas that help developers compute values easily. Aspose.Cells also supports add‑in functions. Moreover, Aspose.Cells supports array and R1C1 formulas.

How to Use Formulas and Functions

Aspose.Cells provides a class, Workbook, that represents a Microsoft Excel file. The Workbook class contains a getWorksheets() collection that allows access to each worksheet in the Excel file. A worksheet is represented by the Worksheet class. The Worksheet class provides a getCells() collection. Each item in the Cells collection represents an object of the Cell class.

It is possible to apply formulas to cells using properties and methods offered by the Cell class, discussed in more detail below.

  • Using built‑in functions.
  • Using add‑in functions.
  • Working with array formulas.
  • Creating an R1C1 formula.

How to Use Built-in Functions

Built-in functions or formulas are provided as ready‑made utilities to reduce developers' effort and time. See a list of built-in functions supported by Aspose.Cells. The functions are listed in alphabetical order. More functions will be supported in the future.

Aspose.Cells supports most of the formulas or functions offered by Microsoft Excel. Developers can use these formulas through the API or designer spreadsheet. Aspose.Cells supports a huge set of mathematical, string, Boolean, date/time, statistical, database, lookup, and reference formulas.

Use the Cell class’s setFormula() method to add a formula to a cell. Complex formulas, for example

=H7*(1+IF(P7=$L$3,$M$3,(IF(P7=$L$4,$M$4,0))))

are also supported in Aspose.Cells. When applying a formula to a cell, always begin the string with an equal sign (=) as you do when creating a formula in Microsoft Excel and use a comma (,) to delimit function parameters.

In the example below, a complex formula is applied to the first cell of a worksheet’s Cells collection. The formula uses a built‑in IF function provided by Aspose.Cells.

const path = require("path");
const AsposeCells = require("aspose.cells.node");

// The path to the documents directory.
const dataDir = path.join(__dirname, "data");

// Instantiating a Workbook object
const workbook = new AsposeCells.Workbook();

// Adding a new worksheet to the Excel object
const sheetIndex = workbook.getWorksheets().add();

// Obtaining the reference of the newly added worksheet by passing its sheet index
const worksheet = workbook.getWorksheets().get(sheetIndex);

// Adding a value to "A1" cell
worksheet.getCells().get("A1").putValue(1);

// Adding a value to "A2" cell
worksheet.getCells().get("A2").putValue(2);

// Adding a value to "A3" cell
worksheet.getCells().get("A3").putValue(3);

// Adding a SUM formula to "A4" cell
worksheet.getCells().get("A4").setFormula("=SUM(A1:A3)");

// Calculating the results of formulas
workbook.calculateFormula();

// Get the calculated value of the cell
const value = worksheet.getCells().get("A4").getValue().toString();

// Saving the Excel file
workbook.save(path.join(dataDir, "output.xls"));

How to Use Add-in Functions

We can have some user‑defined formulas that we want to include as an Excel add‑in. When setting a cell’s formula, built‑in functions work fine; however, there is a need to set custom functions or formulas using add‑in functions.

Aspose.Cells provides features to register add‑in functions using Worksheets.registerAddInFunction(string, string, boolean). Afterwards, when we set cell.setFormula("=YourAddInFunction()"), the output Excel file contains the calculated value from the add‑in function.

The following XLAM file should be downloaded for registering the add‑in function in the sample code below. Similarly, the output file test_udf.xlsx can be downloaded to verify the result.

TestUDF.xlam
test_udf.xlsx

const path = require("path");
const AsposeCells = require("aspose.cells.node");

// The path to the documents directory.
const dataDir = path.join(__dirname, "data");
const outputDir = path.join(__dirname, "output");

// Create empty workbook
const workbook = new AsposeCells.Workbook();

// Register macro‑enabled add‑in along with the function name
const id = workbook.getWorksheets().registerAddInFunction(
    path.join(dataDir, "TESTUDF.xlam"),
    "TEST_UDF",
    false
);

// Register more functions in the file (if any)
workbook.getWorksheets().registerAddInFunction(id, "TEST_UDF1"); // you can add more functions from the same file

// Access first worksheet
const worksheet = workbook.getWorksheets().get(0);

// Access first cell
const cell = worksheet.getCells().get("A1");

// Set formula name present in the add‑in
cell.setFormula("=TEST_UDF()");

// Save workbook to output XLSX format.
workbook.save(path.join(outputDir, "test_udf.xlsx"), AsposeCells.SaveFormat.Xlsx);

How to Use Array Formula

Array formulas are formulas that take arrays, instead of individual numbers, as arguments to the functions that make up the formula. When an array formula is displayed, it is surrounded by braces ({}).

Some Microsoft Excel functions return arrays of values. To calculate multiple results with an array formula, enter the array into a range of cells with the same number of rows and columns as the array arguments.

It is possible to apply an array formula to a cell by calling the Cell class’s setArrayFormula(string, number, number) method. The method takes the following parameters:

  • Array Formula – the array formula.
  • Number of Rows – the number of rows to populate with the result of the array formula.
  • Number of Columns – the number of columns to populate with the result of the array formula.
const path = require("path");
const AsposeCells = require("aspose.cells.node");

// The path to the documents directory.
const dataDir = path.join(__dirname, "data");

// Instantiating a Workbook object
const workbook = new AsposeCells.Workbook();

// Adding a new worksheet to the Excel object
const sheetIndex = workbook.getWorksheets().add();

// Obtaining the reference of the newly added worksheet by passing its sheet index
const worksheet = workbook.getWorksheets().get(sheetIndex);

// Adding values to cells A1‑C3
worksheet.getCells().get("A1").putValue(1);
worksheet.getCells().get("A2").putValue(2);
worksheet.getCells().get("A3").putValue(3);
worksheet.getCells().get("B1").putValue(4);
worksheet.getCells().get("B2").putValue(5);
worksheet.getCells().get("B3").putValue(6);
worksheet.getCells().get("C1").putValue(7);
worksheet.getCells().get("C2").putValue(8);
worksheet.getCells().get("C3").putValue(9);

// Adding an array formula to "A6" cell
worksheet.getCells().get("A6").setArrayFormula("=LINEST(A1:A3,B1:C3,TRUE,TRUE)", 5, 3);

// Calculating the results of formulas
workbook.calculateFormula();

// Get the calculated value of the cell
const value = worksheet.getCells().get("A6").getValue().toString();

// Saving the Excel file
workbook.save(path.join(dataDir, "output.xls"));

How to Use R1C1 Formula

Add an R1C1 reference‑style formula to a cell with the Cell class’s setR1C1Formula() method.

const path = require("path");
const AsposeCells = require("aspose.cells.node");

// The path to the documents directory.
const dataDir = path.join(__dirname, "data");
const filePath = path.join(dataDir, "Book1.xls");

// Instantiating a Workbook object
const workbook = new AsposeCells.Workbook(filePath);

const worksheet = workbook.getWorksheets().get(0);

// Setting an R1C1 formula on the "A11" cell,
// Row and column indices are relative to the destination cell
worksheet.getCells().get("A11").setR1C1Formula("=SUM(R[-10]C[0]:R[-7]C[0])");

// Saving the Excel file
workbook.save(path.join(dataDir, "output.xls"));

Advanced topics

Format cells with Node.js via C++ Calculate Formulas with Node.js via C++