diff --git a/content/guides/sheets/features/core/formula.ja-JP.mdx b/content/guides/sheets/features/core/formula.ja-JP.mdx index d39370e..1a0e027 100644 --- a/content/guides/sheets/features/core/formula.ja-JP.mdx +++ b/content/guides/sheets/features/core/formula.ja-JP.mdx @@ -70,7 +70,7 @@ enum CalculationMode { } ``` -> 数式セルが予期しない値を保持している場合、`initialFormulaComputing` を `FORCED` に設定して全数式を強制再計算するか、初期化前にセル値をクリアしてください。 +> 数式セルが予期しない値を保持している場合、`initialFormulaComputing` を `FORCED` に設定して全数式を強制再計算するか、初期化前にセルの `v` 値をクリアしてください。 ## サポートされる数式関数 @@ -78,6 +78,8 @@ enum CalculationMode { ## Facade API +完全な Facade API については、[FFormula](https://reference.univer.ai/classes/FFormula) を参照してください。 + ### インポート @@ -89,52 +91,71 @@ import '@univerjs/engine-formula/facade' import '@univerjs/sheets-formula/facade' ``` -### 計算の実行 +### 数式計算の実行 ```typescript -const formula = univerAPI.getFormula() -formula.executeCalculation() +const formulaEngine = univerAPI.getFormula() +formulaEngine.executeCalculation() ``` -### 計算の停止 +### 数式計算の停止 ```typescript -const formula = univerAPI.getFormula() -formula.stopCalculation() +const formulaEngine = univerAPI.getFormula() +formulaEngine.stopCalculation() ``` -### 計算開始イベント +### 数式計算の開始 ```typescript -const formula = univerAPI.getFormula() -formula.calculationStart((forceCalculate) => { +// 数式計算の開始イベントをリッスン +const formulaEngine = univerAPI.getFormula() +formulaEngine.calculationStart((forceCalculate) => { console.log(forceCalculate) }) ``` -### 計算進行イベント +### 数式計算の進行 ```typescript -const formula = univerAPI.getFormula() -formula.calculationProcessing((stageInfo) => { +// 数式計算の進行イベントをリッスン +const formulaEngine = univerAPI.getFormula() +formulaEngine.calculationProcessing((stageInfo) => { console.log(stageInfo) }) ``` -### 計算終了イベント +### 数式計算の終了 ```typescript -const formula = univerAPI.getFormula() -formula.calculationEnd((functionsExecutedState) => { +// 数式計算の終了イベントをリッスン +const formulaEngine = univerAPI.getFormula() +formulaEngine.calculationEnd((functionsExecutedState) => { console.log(functionsExecutedState) }) + +// 数式計算の終了を待機 +await formulaEngine.onCalculationEnd() +``` + +### 数式計算結果の適用 + +```typescript +// 数式計算結果の適用イベントをリッスン +const formulaEngine = univerAPI.getFormula() +formulaEngine.calculationResultApplied((result) => { + console.log(result) +}) + +// 数式計算結果の適用完了を待機 +await formulaEngine.onCalculationResultApplied() ``` -### 初期計算モードの設定 +### 初期化データ時の数式計算モードの設定 ```typescript -const formula = univerAPI.getFormula() -formula.setInitialFormulaComputing(CalculationMode.FORCED) +const formulaEngine = univerAPI.getFormula() +formulaEngine.setInitialFormulaComputing(CalculationMode.FORCED) ``` この API が `Starting` ライフサイクル以降に呼ばれた場合、次に Univer Sheet が生成されるタイミングで反映されます。 @@ -144,12 +165,57 @@ formula.setInitialFormulaComputing(CalculationMode.FORCED) ```typescript univerAPI.addEvent(univerAPI.Event.LifeCycleChanged, ({ stage }) => { if (stage === LifecycleStages.Starting) { - const formula = univerAPI.getFormula() - formula.setInitialFormulaComputing(CalculationMode.FORCED) + const formulaEngine = univerAPI.getFormula() + formulaEngine.setInitialFormulaComputing(CalculationMode.FORCED) } }) ``` +### 反復回数の設定 + +数式に循環参照が存在する場合、この API を使用して数式計算時の最大反復回数を設定できます。デフォルト値は 1 です。 + +```typescript +const formulaEngine = univerAPI.getFormula() +formulaEngine.setMaxIteration(10) +``` + +### 数式文字列の計算結果の取得 + +数式文字列の一括非同期実行と計算結果の取得: + +```typescript +const formulaEngine = univerAPI.getFormula() +const formulas = { + Book1: { + Sheet1: { + 2: { + 3: [ + // 完全な数式: + '=SUM(A1:A10) + SQRT(D7)', + + // 分解されたサブ数式(それぞれ独立して評価可能): + 'SUM(A1:A10)', // サブ数式1 + 'SQRT(D7)', // サブ数式2 + 'A1:A10', // 範囲参照 + 'D7', // 単一セル参照 + ], + }, + 4: { + 5: [ + '=A2 + B2 + SQRT(C5)', + 'A2', + 'B2', + 'SQRT(C5)', + ], + }, + }, + }, +} +const result = await formulaEngine.executeFormulas(formulas) +console.log(result) +``` + ## カスタム数式 Univer はカスタム数式をサポートしています。実装方法は [Custom Formulas](/guides/recipes/tutorials/custom-formula) を参照してください。 diff --git a/content/guides/sheets/features/core/formula.mdx b/content/guides/sheets/features/core/formula.mdx index af560d6..b33bc43 100644 --- a/content/guides/sheets/features/core/formula.mdx +++ b/content/guides/sheets/features/core/formula.mdx @@ -70,7 +70,7 @@ enum CalculationMode { } ``` -> If the cell containing the formula has an unexpected value, you can set `initialFormulaComputing` to `FORCED` to force the calculation of all formulas. Alternatively, you can clear the cell's value before initialization. +> If the cell containing the formula has an unexpected value, you can set `initialFormulaComputing` to `FORCED` to force the calculation of all formulas. Alternatively, you can clear the cell's `v` value before initialization. ## Supported Formula Functions @@ -78,6 +78,8 @@ enum CalculationMode { ## Facade API +For more details, please refer to the [FFormula Facade API](https://reference.univer.ai/classes/FFormula). + ### Importing @@ -89,52 +91,71 @@ import '@univerjs/engine-formula/facade' import '@univerjs/sheets-formula/facade' ``` -### Execute Calculation +### Execute Formula Calculation ```typescript -const formula = univerAPI.getFormula() -formula.executeCalculation() +const formulaEngine = univerAPI.getFormula() +formulaEngine.executeCalculation() ``` -### Stop Calculation +### Stop Formula Calculation ```typescript -const formula = univerAPI.getFormula() -formula.stopCalculation() +const formulaEngine = univerAPI.getFormula() +formulaEngine.stopCalculation() ``` -### Calculation Start Event +### Formula Calculation Start ```typescript -const formula = univerAPI.getFormula() -formula.calculationStart((forceCalculate) => { +// Listening to formula calculation start event +const formulaEngine = univerAPI.getFormula() +formulaEngine.calculationStart((forceCalculate) => { console.log(forceCalculate) }) ``` -### Calculation Processing Event +### Formula Calculation Processing ```typescript -const formula = univerAPI.getFormula() -formula.calculationProcessing((stageInfo) => { +// Listening to formula calculation processing event +const formulaEngine = univerAPI.getFormula() +formulaEngine.calculationProcessing((stageInfo) => { console.log(stageInfo) }) ``` -### Calculation End Event +### Formula Calculation End ```typescript -const formula = univerAPI.getFormula() -formula.calculationEnd((functionsExecutedState) => { +// Listening to formula calculation end event +const formulaEngine = univerAPI.getFormula() +formulaEngine.calculationEnd((functionsExecutedState) => { console.log(functionsExecutedState) }) + +// Wait for formula calculation to end +await formulaEngine.onCalculationEnd() +``` + +### Formula Calculation Result Applied + +```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() ``` -### Set Initial Calculation Mode +### Set Formula Calculation Mode When Initializing Data ```typescript -const formula = univerAPI.getFormula() -formula.setInitialFormulaComputing(CalculationMode.FORCED) +const formulaEngine = univerAPI.getFormula() +formulaEngine.setInitialFormulaComputing(CalculationMode.FORCED) ``` If this API is called after the `Starting` lifecycle, it will take effect the next time a Univer Sheet is created. @@ -144,12 +165,57 @@ If you want it to take effect during the current initialization of the Univer Sh ```typescript univerAPI.addEvent(univerAPI.Event.LifeCycleChanged, ({ stage }) => { if (stage === LifecycleStages.Starting) { - const formula = univerAPI.getFormula() - formula.setInitialFormulaComputing(CalculationMode.FORCED) + const formulaEngine = univerAPI.getFormula() + formulaEngine.setInitialFormulaComputing(CalculationMode.FORCED) } }) ``` +### Set Max Iteration + +When there are circular references in formulas, you can use this API to set the maximum number of iterations for formula calculations. The default value is 1. + +```typescript +const formulaEngine = univerAPI.getFormula() +formulaEngine.setMaxIteration(10) +``` + +### Get Formula Strings Execution Result + +Execute a batch of formulas asynchronously and receive calculation results: + +```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) +``` + ## Custom Formulas Univer supports custom formulas. Please refer to the [Custom Formulas](/guides/recipes/tutorials/custom-formula) section to learn how to implement them. diff --git a/content/guides/sheets/features/core/formula.zh-CN.mdx b/content/guides/sheets/features/core/formula.zh-CN.mdx index 844bf79..5a83ea4 100644 --- a/content/guides/sheets/features/core/formula.zh-CN.mdx +++ b/content/guides/sheets/features/core/formula.zh-CN.mdx @@ -70,7 +70,7 @@ enum CalculationMode { } ``` -> 如果公式所在单元格有非预期值,可以通过 `initialFormulaComputing` 设置为 `FORCED` 强制计算所有公式。或者初始化之前清空单元格的值。 +> 如果公式所在单元格有非预期值,可以通过 `initialFormulaComputing` 设置为 `FORCED` 强制计算所有公式。或者初始化之前清空单元格的 `v` 值。 ## 已经支持的公式函数 @@ -78,6 +78,8 @@ enum CalculationMode { ## Facade API +完整 Facade API 见 [FFormula](https://reference.univer.ai/classes/FFormula)。 + ### 引入 @@ -89,52 +91,71 @@ import '@univerjs/engine-formula/facade' import '@univerjs/sheets-formula/facade' ``` -### 执行计算 +### 执行公式计算 ```typescript -const formula = univerAPI.getFormula() -formula.executeCalculation() +const formulaEngine = univerAPI.getFormula() +formulaEngine.executeCalculation() ``` -### 停止计算 +### 停止公式计算 ```typescript -const formula = univerAPI.getFormula() -formula.stopCalculation() +const formulaEngine = univerAPI.getFormula() +formulaEngine.stopCalculation() ``` -### 计算开始事件 +### 公式开始计算 ```typescript -const formula = univerAPI.getFormula() -formula.calculationStart((forceCalculate) => { +// 监听公式计算开始事件 +const formulaEngine = univerAPI.getFormula() +formulaEngine.calculationStart((forceCalculate) => { console.log(forceCalculate) }) ``` -### 计算中事件 +### 公式计算中 ```typescript -const formula = univerAPI.getFormula() -formula.calculationProcessing((stageInfo) => { +// 监听公式计算中事件 +const formulaEngine = univerAPI.getFormula() +formulaEngine.calculationProcessing((stageInfo) => { console.log(stageInfo) }) ``` -### 计算结束事件 +### 公式计算结束 ```typescript -const formula = univerAPI.getFormula() -formula.calculationEnd((functionsExecutedState) => { +// 监听公式计算结束事件 +const formulaEngine = univerAPI.getFormula() +formulaEngine.calculationEnd((functionsExecutedState) => { console.log(functionsExecutedState) }) + +// 等待公式计算结束 +await formulaEngine.onCalculationEnd() +``` + +### 公式计算结果应用 + +```typescript +// 监听公式计算结果应用事件 +const formulaEngine = univerAPI.getFormula() +formulaEngine.calculationResultApplied((result) => { + console.log(result) +}) + +// 等待公式计算结果应用完成 +await formulaEngine.onCalculationResultApplied() ``` -### 设置初始化计算模式 +### 设置初始化数据时公式的计算模式 ```typescript -const formula = univerAPI.getFormula() -formula.setInitialFormulaComputing(CalculationMode.FORCED) +const formulaEngine = univerAPI.getFormula() +formulaEngine.setInitialFormulaComputing(CalculationMode.FORCED) ``` 如果这个 API 在 `Starting` 生命周期之后调用,会在下次创建 Univer Sheet 时生效。 @@ -144,12 +165,57 @@ formula.setInitialFormulaComputing(CalculationMode.FORCED) ```typescript univerAPI.addEvent(univerAPI.Event.LifeCycleChanged, ({ stage }) => { if (stage === LifecycleStages.Starting) { - const formula = univerAPI.getFormula() - formula.setInitialFormulaComputing(CalculationMode.FORCED) + const formulaEngine = univerAPI.getFormula() + formulaEngine.setInitialFormulaComputing(CalculationMode.FORCED) } }) ``` +### 设置迭代次数 + +当公式中存在循环引用时,可以通过该 API 设置公式计算时的最大迭代次数。默认值为 1。 + +```typescript +const formulaEngine = univerAPI.getFormula() +formulaEngine.setMaxIteration(10) +``` + +### 获取公式字符串的计算结果 + +异步执行一批公式字符串并返回计算结果: + +```typescript +const formulaEngine = univerAPI.getFormula() +const formulas = { + Book1: { + Sheet1: { + 2: { + 3: [ + // 完整公式: + '=SUM(A1:A10) + SQRT(D7)', + + // 分解后的子公式(每个都可以独立计算): + 'SUM(A1:A10)', // 子公式 1 + 'SQRT(D7)', // 子公式 2 + 'A1:A10', // 范围引用 + 'D7', // 单个单元格引用 + ], + }, + 4: { + 5: [ + '=A2 + B2 + SQRT(C5)', + 'A2', + 'B2', + 'SQRT(C5)', + ], + }, + }, + }, +} +const result = await formulaEngine.executeFormulas(formulas) +console.log(result) +``` + ## 自定义公式 Univer 支持自定义公式,请参考[自定义公式](/guides/recipes/tutorials/custom-formula) 章节了解如何实现。 diff --git a/content/guides/sheets/features/core/formula.zh-TW.mdx b/content/guides/sheets/features/core/formula.zh-TW.mdx index f758f23..d666f31 100644 --- a/content/guides/sheets/features/core/formula.zh-TW.mdx +++ b/content/guides/sheets/features/core/formula.zh-TW.mdx @@ -70,7 +70,7 @@ enum CalculationMode { } ``` -> 如果公式所在儲存格有非預期值,可以透過 `initialFormulaComputing` 設定為 `FORCED` 強制計算所有公式。或者初始化之前清空儲存格的值。 +> 如果公式所在儲存格有非預期值,可以透過 `initialFormulaComputing` 設定為 `FORCED` 強制計算所有公式。或者初始化之前清空儲存格的 `v` 值。 ## 已經支援的公式函數 @@ -78,6 +78,8 @@ enum CalculationMode { ## Facade API +完整 Facade API 請參閱 [FFormula](https://reference.univer.ai/classes/FFormula)。 + ### 導入 @@ -89,52 +91,71 @@ import '@univerjs/engine-formula/facade' import '@univerjs/sheets-formula/facade' ``` -### 執行計算 +### 執行公式計算 ```typescript -const formula = univerAPI.getFormula() -formula.executeCalculation() +const formulaEngine = univerAPI.getFormula() +formulaEngine.executeCalculation() ``` -### 停止計算 +### 停止公式計算 ```typescript -const formula = univerAPI.getFormula() -formula.stopCalculation() +const formulaEngine = univerAPI.getFormula() +formulaEngine.stopCalculation() ``` -### 計算開始事件 +### 公式開始計算 ```typescript -const formula = univerAPI.getFormula() -formula.calculationStart((forceCalculate) => { +// 監聽公式計算開始事件 +const formulaEngine = univerAPI.getFormula() +formulaEngine.calculationStart((forceCalculate) => { console.log(forceCalculate) }) ``` -### 計算中事件 +### 公式計算中 ```typescript -const formula = univerAPI.getFormula() -formula.calculationProcessing((stageInfo) => { +// 監聽公式計算中事件 +const formulaEngine = univerAPI.getFormula() +formulaEngine.calculationProcessing((stageInfo) => { console.log(stageInfo) }) ``` -### 計算結束事件 +### 公式計算結束 ```typescript -const formula = univerAPI.getFormula() -formula.calculationEnd((functionsExecutedState) => { +// 監聽公式計算結束事件 +const formulaEngine = univerAPI.getFormula() +formulaEngine.calculationEnd((functionsExecutedState) => { console.log(functionsExecutedState) }) + +// 等待公式計算結束 +await formulaEngine.onCalculationEnd() +``` + +### 公式計算結果應用 + +```typescript +// 監聽公式計算結果應用事件 +const formulaEngine = univerAPI.getFormula() +formulaEngine.calculationResultApplied((result) => { + console.log(result) +}) + +// 等待公式計算結果應用完成 +await formulaEngine.onCalculationResultApplied() ``` -### 設定初始化計算模式 +### 設定初始化資料時公式的計算模式 ```typescript -const formula = univerAPI.getFormula() -formula.setInitialFormulaComputing(CalculationMode.FORCED) +const formulaEngine = univerAPI.getFormula() +formulaEngine.setInitialFormulaComputing(CalculationMode.FORCED) ``` 如果這個 API 在 `Starting` 生命週期之後呼叫,會在下次建立 Univer Sheet 時生效。 @@ -144,12 +165,57 @@ formula.setInitialFormulaComputing(CalculationMode.FORCED) ```typescript univerAPI.addEvent(univerAPI.Event.LifeCycleChanged, ({ stage }) => { if (stage === LifecycleStages.Starting) { - const formula = univerAPI.getFormula() - formula.setInitialFormulaComputing(CalculationMode.FORCED) + const formulaEngine = univerAPI.getFormula() + formulaEngine.setInitialFormulaComputing(CalculationMode.FORCED) } }) ``` +### 設定迭代次數 + +當公式中存在循環引用時,可以透過該 API 設定公式計算時的最大迭代次數。預設值為 1。 + +```typescript +const formulaEngine = univerAPI.getFormula() +formulaEngine.setMaxIteration(10) +``` + +### 取得公式字串的計算結果 + +非同步執行一批公式字串並返回計算結果: + +```typescript +const formulaEngine = univerAPI.getFormula() +const formulas = { + Book1: { + Sheet1: { + 2: { + 3: [ + // 完整公式: + '=SUM(A1:A10) + SQRT(D7)', + + // 分解後的子公式(每個都可以獨立計算): + 'SUM(A1:A10)', // 子公式1 + 'SQRT(D7)', // 子公式2 + 'A1:A10', // 範圍參考 + 'D7', // 單元格參考 + ], + }, + 4: { + 5: [ + '=A2 + B2 + SQRT(C5)', + 'A2', + 'B2', + 'SQRT(C5)', + ], + }, + }, + }, +} +const result = await formulaEngine.executeFormulas(formulas) +console.log(result) +``` + ## 自訂公式 Univer 支援自訂公式,請參考[自訂公式](/guides/recipes/tutorials/custom-formula) 章節了解如何實作。