Class: FFormula

get lexerTreeBuilder(): LexerTreeBuilder

calculationEnd(callback): IDisposable

const formulaEngine = univerAPI.getFormula();
formulaEngine.calculationEnd((functionsExecutedState) => {
  console.log('Calculation end', functionsExecutedState);
});

calculationProcessing(callback): IDisposable

const formulaEngine = univerAPI.getFormula();
formulaEngine.calculationProcessing((stageInfo) => {
  console.log('Calculation processing', stageInfo);
});

calculationStart(callback): IDisposable

const formulaEngine = univerAPI.getFormula();
formulaEngine.calculationStart((forceCalculation) => {
  console.log('Calculation start', forceCalculation);
});

executeCalculation(): void

const formulaEngine = univerAPI.getFormula();
formulaEngine.executeCalculation();

moveFormulaRefOffset(
   formulaString, 
   refOffsetX, 
   refOffsetY, 
   ignoreAbsolute?): string

const formulaEngine = univerAPI.getFormula();
const result = formulaEngine.moveFormulaRefOffset('=SUM(A1,B2)', 1, 1);
console.log(result);

onCalculationEnd(): Promise<void>

registerAsyncFunction(
   name, 
   func, 
   description?): IDisposable

const formulaEngine = univerAPI.getFormula();
formulaEngine.registerAsyncFunction(
  'RANDOM_DELAYED',
  async () => {
    await new Promise(resolve => setTimeout(resolve, 500));
    return Math.random();
  },
  'Mock a random number generation function'
);
 
// Use the function in a cell
const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
const cellA1 = fWorksheet.getRange('A1');
cellA1.setValue({ f: '=RANDOM_DELAYED()' });
 
// After 0.5 second, A1 will display a random number

registerAsyncFunction(
   name, 
   func, 
   options?): IDisposable

// Mock a user score fetching function
const formulaEngine = univerAPI.getFormula();
formulaEngine.registerAsyncFunction(
  'FETCH_USER_SCORE',
  async (userId) => {
    await new Promise(resolve => setTimeout(resolve, 1000));
    // Mock fetching user score from database
    return userId * 10 + Math.floor(Math.random() * 20);
  },
  {
    description: 'customFunction.FETCH_USER_SCORE.description',
    locales: {
      'zhCN': {
        'customFunction': {
          'FETCH_USER_SCORE': {
            'description': '从数据库中获取用户分数'
          }
        }
      },
      'enUS': {
        'customFunction': {
          'FETCH_USER_SCORE': {
            'description': 'Mock fetching user score from database'
          }
        }
      }
    }
  }
);
 
// Use the function in a cell
const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
const cellA1 = fWorksheet.getRange('A1');
cellA1.setValue({ f: '=FETCH_USER_SCORE(42)' });
 
// After 1 second, A1 will display a score

registerFunction(
   name, 
   func, 
   description?): IDisposable

// Register a simple greeting function
const formulaEngine = univerAPI.getFormula();
formulaEngine.registerFunction(
  'HELLO',
  (name) => `Hello, ${name}!`,
  'A simple greeting function'
);
 
// Use the function in a cell
const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
const cellA1 = fWorksheet.getRange('A1');
cellA1.setValue('World');
const cellA2 = fWorksheet.getRange('A2');
cellA2.setValue({ f: '=HELLO(A1)' });
 
// A2 will display: "Hello, World!"
formulaEngine.calculationEnd((functionsExecutedState) => {
  if (functionsExecutedState === 3) {
    console.log(cellA2.getValue()); // Hello, World!
  }
})

// Register a discount calculation function
const formulaEngine = univerAPI.getFormula();
formulaEngine.registerFunction(
  'DISCOUNT',
  (price, discountPercent) => price * (1 - discountPercent / 100),
  'Calculates final price after discount'
);
 
// Use the function in a cell
const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
const cellA1 = fWorksheet.getRange('A1');
cellA1.setValue(100);
const cellA2 = fWorksheet.getRange('A2');
cellA2.setValue({ f: '=DISCOUNT(A1, 20)' });
 
// A2 will display: 80
formulaEngine.calculationEnd((functionsExecutedState) => {
  if (functionsExecutedState === 3) {
    console.log(cellA2.getValue()); // 80
  }
})

// Registered formulas support lambda functions
const formulaEngine = univerAPI.getFormula();
formulaEngine.registerFunction(
  'CUSTOMSUM',
  (...variants) => {
    let sum = 0;
    const last = variants[variants.length - 1];
 
    if (last.isLambda && last.isLambda()) {
      variants.pop();
      const variantsList = variants.map((variant) => Array.isArray(variant) ? variant[0][0]: variant);
      sum += last.executeCustom(...variantsList).getValue();
    }
 
    for (const variant of variants) {
      sum += Number(variant) || 0;
    }
 
    return sum;
  },
  'Adds its arguments'
);
 
// Use the function in a cell
const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
const cellA1 = fWorksheet.getRange('A1');
cellA1.setValue(1);
const cellA2 = fWorksheet.getRange('A2');
cellA2.setValue(2);
const cellA3 = fWorksheet.getRange('A3');
cellA3.setValue({ f: '=CUSTOMSUM(A1,A2,LAMBDA(x,y,x*y))' });
 
// A3 will display: 5
formulaEngine.calculationEnd((functionsExecutedState) => {
  if (functionsExecutedState === 3) {
    console.log(cellA3.getValue()); // 5
  }
})

registerFunction(
   name, 
   func, 
   options?): IDisposable

// Register a simple greeting function
const formulaEngine = univerAPI.getFormula();
formulaEngine.registerFunction(
  'HELLO',
  (name) => `Hello, ${name}!`,
  {
    description: 'customFunction.HELLO.description',
    locales: {
      'zhCN': {
        'customFunction': {
          'HELLO': {
            'description': '一个简单的问候函数'
          }
        }
      },
      'enUS': {
        'customFunction': {
          'HELLO': {
            'description': 'A simple greeting function'
          }
        }
      }
    }
  }
);
 
// Use the function in a cell
const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
const cellA1 = fWorksheet.getRange('A1');
cellA1.setValue('World');
const cellA2 = fWorksheet.getRange('A2');
cellA2.setValue({ f: '=HELLO(A1)' });
 
// A2 will display: "Hello, World!"
formulaEngine.calculationEnd((functionsExecutedState) => {
  if (functionsExecutedState === 3) {
    console.log(cellA2.getValue()); // Hello, World!
  }
})

sequenceNodesBuilder(formulaString): any[]

const formulaEngine = univerAPI.getFormula();
const nodes = formulaEngine.sequenceNodesBuilder('=SUM(A1,B2)');
console.log(nodes);

setInitialFormulaComputing(calculationMode): void

const formulaEngine = univerAPI.getFormula();
formulaEngine.setInitialFormulaComputing(0);

setMaxIteration(maxIteration): void

// Set the maximum number of iterations for the formula calculation to 5.
// The default value is 1.
const formulaEngine = univerAPI.getFormula();
formulaEngine.setMaxIteration(5);

stopCalculation(): void

const formulaEngine = univerAPI.getFormula();
formulaEngine.stopCalculation();

whenComputingCompleteAsync(timeout?): Promise<boolean>

const formulaEngine = univerAPI.getFormula();
formulaEngine.whenComputingCompleteAsync(3000).then((isComplete) => {
  console.log('Computing complete:', isComplete);
});