[]
        
(Showing Draft Content)

워크시트 외부에서 수식 계산

SpreadJS는 수식 평가 및 계산을 워크시트 셀 외부에서도 수행할 수 있도록 강력한 계산 엔진을 제공합니다.

GC.Spread.Sheets.CalcEngine 모듈에는 워크시트에 수식을 직접 설정하지 않고도 수식을 파싱, 평가 및 변환할 수 있는 다양한 유틸리티 메서드가 포함되어 있습니다.

판매 데이터를 포함하는 표를 준비합니다.


1

evaluateFormula: 지정된 수식 문자열을 평가하고 결과를 반환합니다.

사용 사례:

  • 워크시트 렌더링이나 사용자 동작에 의존하지 않고, 코드 내에서 동적으로 수식 결과를 계산해야 할 때 (예: 백엔드에서 데이터 처리 또는 수식 로직 일괄 검증 시)

  • 배열 수식의 다중 출력값을 유지해야 할 때는 preserveArrayResult: true 옵션을 사용하여 전체 배열을 얻을 수 있습니다.

  • 코드에서 R1C1 형식의 수식을 생성하거나 파싱할 때

메서드:

evaluateFormula(context, formula, baseRow?, baseColumn?, useR1C1?, preserveArrayResult?)

매개변수:

  • context (Object): 평가 컨텍스트 (일반적으로 활성 시트 객체)

  • formula (string): 평가할 수식 문자열

  • baseRow (number, 선택): 상대 참조용 기준 행 인덱스

  • baseColumn (number, 선택): 상대 참조용 기준 열 인덱스

  • useR1C1 (boolean, 선택): R1C1 참조 스타일을 사용할지 여부 (기본값: false)

  • preserveArrayResult (boolean, 선택): true일 경우 배열 결과 반환, 아니면 단일 값 반환

예제 1: 계산 결과를 직접 가져오기

var sheet = spread.getActiveSheet();
GC.Spread.Sheets.CalcEngine.evaluateFormula(sheet, '=SUM(Table1[[#Data],[Units]])')
//결과: 84878

예제 2: baseRow와 baseColumn을 사용한 상대 참조

var sheet = spread.getActiveSheet();
GC.Spread.Sheets.CalcEngine.evaluateFormula(sheet, '=Table1[@[Sales Rep]]',2,0);
//결과: Tom
GC.Spread.Sheets.CalcEngine.evaluateFormula(sheet, '=Table1[@[Sales Rep]]',5,0);
//결과: Sal
GC.Spread.Sheets.CalcEngine.evaluateFormula(sheet, '=Table1[@[Sales Rep]]',12,0);
//결과: Amy

예제 3: baseRow/baseColumn과 R1C1 스타일 사용

var sheet = spread.getActiveSheet();
GC.Spread.Sheets.CalcEngine.evaluateFormula(sheet, '=R[3]C[3]',0,0,true);
//결과: Grape
GC.Spread.Sheets.CalcEngine.evaluateFormula(sheet, '=R[3]C[3]',2,1,true);
//결과: 5323

예제 4: 배열 결과 가져오기 (preserveArrayResult 사용)

var sheet = spread.getActiveSheet();
spread.options.allowDynamicArray = true; 
GC.Spread.Sheets.CalcEngine.evaluateFormula(sheet, '=UNIQUE(Table1[[#Data],[Product]])')
//결과: Apple
GC.Spread.Sheets.CalcEngine.evaluateFormula(sheet, '=UNIQUE(Table1[[#Data],[Product]])',null,null,null,true)
//결과: [['Apple'],['Grape'],['Pear'],['Banana']]

expressionToFormula: 식을 수식 문자열로 변환합니다.

사용 사례:

  • 복잡한 수식을 동적으로 생성해야 할 때 (문자열 연결 방식의 위험 회피). formulaToExpression과 함께 자주 사용됨

  • 사용자 정의 이름의 식을 파싱하고 해당 수식을 생성해야 할 때

메서드:

expressionToFormula(context, expression, baseRow?, baseColumn?, useR1C1?)

매개변수:

  • context (Object): 컨텍스트 (일반적으로 활성 시트 객체)

  • expression (Expression): 변환할 수식 트리

  • baseRow, baseColumn, useR1C1: 상대 참조 기준 및 참조 스타일 지정 (선택)

예제: 사용자 정의 이름의 수식을 수식 문자열로 변환

var sheet = spread.getActiveSheet();
sheet.addCustomName('averageUnits', '=AVERAGE(Table1[[#Data],[Units]])');
var cname = sheet.getCustomName("averageUnits");
var expr = cname.getExpression();
GC.Spread.Sheets.CalcEngine.expressionToFormula(sheet,expr);
//결과: AVERAGE(Table1[[#Data],[Units]])

formulaToExpression: 수식 문자열을 식으로 파싱합니다.

사용 사례:

  • 기존 수식을 코드에서 파싱한 뒤 일부 인자나 로직을 수정하고 다시 수식으로 생성해야 할 때

  • 수식이 참조하는 셀, 함수, 의존 관계 등을 분석하거나 데이터 흐름 감사를 수행할 때

  • R1C1 ↔ A1 변환 시 중간에 식 객체로 변환해야 할 때

  • 수식 유효성 검사를 문자열 기반이 아닌 구조 기반(식)으로 수행해야 할 때

메서드:

formulaToExpression(context, formula, baseRow?, baseColumn?, useR1C1?)

예제: 수식을 식 객체로 변환

var sheet = spread.getActiveSheet();
var expr = GC.Spread.Sheets.CalcEngine.formulaToExpression(sheet, '=CONCAT(Table1[@Region],Table1[@[Sales Rep]],Table1[@Product])',4,0)
//결과:
//expr.functionName is CONCAT
//expr.arguments.length is 3

formulaToRanges: 수식 문자열을 참조된 셀 범위 배열로 변환합니다.

사용 사례:

  • 수식이 참조하는 모든 셀 범위를 추출하여 데이터 의존성 그래프나 영향도 분석 수행

  • 수식이 참조하는 셀들을 UI에서 하이라이트 처리하여 수식 로직을 직관적으로 이해하도록 지원

  • 수식의 논리 구조보다 실제 셀 위치(행/열 인덱스)가 필요한 경우에 더 효율적

메서드:

formulaToRanges(sheet, formula, baseRow?, baseCol?)

예제: 수식 내 참조된 모든 범위 가져오기

var sheet = spread.getActiveSheet();
var result = GC.Spread.Sheets.CalcEngine.formulaToRanges(sheet, '=SUM(A1,A2,A5:C8)');
//결과:
//result.sheetName is Sheet1
//result.ranges:[
//  Range {row: 0, rowCount: 1, col: 0, colCount: 1}
//  Range {row: 1, rowCount: 1, col: 0, colCount: 1}
//  Range {row: 4, rowCount: 4, col: 0, colCount: 3}
//  Range {row: 2, rowCount: 16, col: 4, colCount: 1}
//]

rangesToFormula: 셀 범위 배열을 수식 문자열로 변환합니다.

사용 사례:

  • 런타임 데이터에 따라 동적으로 참조 범위 수식을 생성해야 할 때 (예: 사용자 선택에 따라 자동으로 범위 조정)

  • 복잡한 참조 문자열을 수동으로 연결하지 않고, 코드 내에서 워크시트 참조를 처리해야 할 때

  • 절대/상대 참조를 유연하게 전환해야 할 때

메서드:

rangesToFormula(ranges, baseRow?, baseCol?, rangeReferenceRelative?, useR1C1?)

예제: 셀 범위 배열을 수식 문자열로 변환

var ranges = [
    new GC.Spread.Sheets.Range(0,0,1,1),
    new GC.Spread.Sheets.Range(3,3,5,5),
];
GC.Spread.Sheets.CalcEngine.rangesToFormula(ranges,0,0,GC.Spread.Sheets.CalcEngine.RangeReferenceRelative.allRelative);
//결과: 'A1, D4:H8'
GC.Spread.Sheets.CalcEngine.rangesToFormula(ranges,0,0,GC.Spread.Sheets.CalcEngine.RangeReferenceRelative.allAbsolute);
//결과: '$A$1, $D$4:$H$8'
GC.Spread.Sheets.CalcEngine.rangesToFormula(ranges,0,0,GC.Spread.Sheets.CalcEngine.RangeReferenceRelative.colRelative);
//결과: 'A$1, D$4:H$8'
GC.Spread.Sheets.CalcEngine.rangesToFormula(ranges,0,0,GC.Spread.Sheets.CalcEngine.RangeReferenceRelative.allRelative, true);
//결과: 'RC, R[3]C[3]:R[7]C[7]'