@univerjs/sheets-formula 0.6.0 → 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/lib/types/facade/f-formula.d.ts +153 -75
  2. package/package.json +9 -9
package/lib/types/facade/f-formula.d.ts CHANGED
@@ -7,90 +7,144 @@ import { FFormula } from '@univerjs/engine-formula/facade';
7
7
  */
8
8
  export interface IFFormulaSheetsMixin {
9
9
  /**
10
- * Update the calculation mode of the formula.
11
- * @param calculationMode
12
- * @returns
10
+ * Update the calculation mode of the formula. It will take effect the next time the Univer Sheet is constructed.
11
+ * The calculation mode only handles formulas data when the workbook initializes data.
12
+ * @param {CalculationMode} calculationMode - The calculation mode of the formula.
13
+ * @example
14
+ * ```ts
15
+ * const formulaEngine = univerAPI.getFormula();
16
+ * formulaEngine.setInitialFormulaComputing(0);
17
+ * ```
13
18
  */
14
19
  setInitialFormulaComputing(calculationMode: CalculationMode): void;
15
20
  /**
16
21
  * Register a custom synchronous formula function.
17
- * @param name - The name of the function to register. This will be used in formulas (e.g., =MYFUNC())
18
- * @param func - The implementation of the function
19
- * @param description - A string describing the function's purpose and usage
20
- * @returns A disposable object that will unregister the function when disposed
22
+ * @param {string} name - The name of the function to register. This will be used in formulas (e.g., =MYFUNC()).
23
+ * @param {IRegisterFunction} func - The implementation of the function.
24
+ * @param {string} [description] - A string describing the function's purpose and usage.
25
+ * @returns {IDisposable} A disposable object that will unregister the function when disposed.
21
26
  * @example
22
- * ```js
23
- * univerAPI.getFormula().registerFunction('HELLO', (name) => `Hello, ${name}!`, 'A simple greeting function');
27
+ * ```ts
28
+ * // Register a simple greeting function
29
+ * const formulaEngine = univerAPI.getFormula();
30
+ * formulaEngine.registerFunction(
31
+ * 'HELLO',
32
+ * (name) => `Hello, ${name}!`,
33
+ * 'A simple greeting function'
34
+ * );
24
35
  *
25
36
  * // Use the function in a cell
26
- * univerAPI.getActiveWorkbook().getActiveSheet().getRange('A1').setValue('World');
27
- * univerAPI.getActiveWorkbook().getActiveSheet().getRange('A2').setValue({ f: '=HELLO(A1)' });
37
+ * const fWorkbook = univerAPI.getActiveWorkbook();
38
+ * const fSheet = fWorkbook.getActiveSheet();
39
+ * const cellA1 = fSheet.getRange('A1');
40
+ * cellA1.setValue('World');
41
+ * const cellA2 = fSheet.getRange('A2');
42
+ * cellA2.setValue({ f: '=HELLO(A1)' });
43
+ *
28
44
  * // A2 will display: "Hello, World!"
45
+ * formulaEngine.calculationEnd((functionsExecutedState) => {
46
+ * if (functionsExecutedState === 3) {
47
+ * console.log(cellA2.getValue()); // Hello, World!
48
+ * }
49
+ * })
29
50
  * ```
30
51
  * @example
31
- * ```js
32
- * univerAPI.getFormula().registerFunction(
52
+ * ```ts
53
+ * // Register a discount calculation function
54
+ * const formulaEngine = univerAPI.getFormula();
55
+ * formulaEngine.registerFunction(
33
56
  * 'DISCOUNT',
34
57
  * (price, discountPercent) => price * (1 - discountPercent / 100),
35
58
  * 'Calculates final price after discount'
36
59
  * );
37
60
  *
38
- * // Use in cell
39
- * univerAPI.getActiveWorkbook().getActiveSheet().getRange('A1').setValue(100);
40
- * univerAPI.getActiveWorkbook().getActiveSheet().getRange('A2').setValue({ f: '=DISCOUNT(A1, 20)' });
61
+ * // Use the function in a cell
62
+ * const fWorkbook = univerAPI.getActiveWorkbook();
63
+ * const fSheet = fWorkbook.getActiveSheet();
64
+ * const cellA1 = fSheet.getRange('A1');
65
+ * cellA1.setValue(100);
66
+ * const cellA2 = fSheet.getRange('A2');
67
+ * cellA2.setValue({ f: '=DISCOUNT(A1, 20)' });
68
+ *
41
69
  * // A2 will display: 80
70
+ * formulaEngine.calculationEnd((functionsExecutedState) => {
71
+ * if (functionsExecutedState === 3) {
72
+ * console.log(cellA2.getValue()); // 80
73
+ * }
74
+ * })
42
75
  * ```
43
76
  * @example
44
- * ```typescript
77
+ * ```ts
45
78
  * // Registered formulas support lambda functions
46
- * univerAPI.getFormula().registerFunction('CUSTOMSUM', (...variants) => {
47
- * let sum = 0;
79
+ * const formulaEngine = univerAPI.getFormula();
80
+ * formulaEngine.registerFunction(
81
+ * 'CUSTOMSUM',
82
+ * (...variants) => {
83
+ * let sum = 0;
84
+ * const last = variants[variants.length - 1];
48
85
  *
49
- * const last = variants[variants.length - 1];
50
- * if (last.isLambda && last.isLambda()) {
51
- * variants.pop();
86
+ * if (last.isLambda && last.isLambda()) {
87
+ * variants.pop();
88
+ * const variantsList = variants.map((variant) => Array.isArray(variant) ? variant[0][0]: variant);
89
+ * sum += last.executeCustom(...variantsList).getValue();
90
+ * }
52
91
  *
53
- * const variantsList = variants.map((variant) => Array.isArray(variant) ? variant[0][0]: variant);
92
+ * for (const variant of variants) {
93
+ * sum += Number(variant) || 0;
94
+ * }
54
95
  *
55
- * sum += last.executeCustom(...variantsList).getValue();
56
- * }
96
+ * return sum;
97
+ * },
98
+ * 'Adds its arguments'
99
+ * );
57
100
  *
58
- * for (const variant of variants) {
59
- * sum += Number(variant) || 0;
60
- * }
101
+ * // Use the function in a cell
102
+ * const fWorkbook = univerAPI.getActiveWorkbook();
103
+ * const fSheet = fWorkbook.getActiveSheet();
104
+ * const cellA1 = fSheet.getRange('A1');
105
+ * cellA1.setValue(1);
106
+ * const cellA2 = fSheet.getRange('A2');
107
+ * cellA2.setValue(2);
108
+ * const cellA3 = fSheet.getRange('A3');
109
+ * cellA3.setValue({ f: '=CUSTOMSUM(A1,A2,LAMBDA(x,y,x*y))' });
61
110
  *
62
- * return sum;
63
- * }, 'Adds its arguments');
111
+ * // A3 will display: 5
112
+ * formulaEngine.calculationEnd((functionsExecutedState) => {
113
+ * if (functionsExecutedState === 3) {
114
+ * console.log(cellA3.getValue()); // 5
115
+ * }
116
+ * })
64
117
  * ```
65
118
  */
66
119
  registerFunction(name: string, func: IRegisterFunction, description?: string): IDisposable;
67
120
  /**
68
121
  * Register a custom synchronous formula function with localization support.
69
- * @param name - The name of the function to register. This will be used in formulas (e.g., =MYFUNC())
70
- * @param func - The implementation of the function
71
- * @param options - Object containing locales and description
72
- * @param options.locales - Object containing locales
73
- * @param options.description - Object containing description
74
- * @returns A disposable object that will unregister the function when disposed
122
+ * @param {string} name - The name of the function to register. This will be used in formulas (e.g., =MYFUNC()).
123
+ * @param {IRegisterFunction} func - The implementation of the function.
124
+ * @param {{ locales?: ILocales; description?: string | IFunctionInfo }} [options] - Object containing locales and description.
125
+ * @param {ILocales} options.locales - Object containing locales.
126
+ * @param {string | IFunctionInfo} options.description - Object containing description.
127
+ * @returns {IDisposable} A disposable object that will unregister the function when disposed.
75
128
  * @example
76
129
  * ```js
77
- * univerAPI.getFormula().registerFunction('HELLO',
78
- * (name) => {
79
- * return `Hello, ${name}!`;
80
- * },
130
+ * // Register a simple greeting function
131
+ * const formulaEngine = univerAPI.getFormula();
132
+ * formulaEngine.registerFunction(
133
+ * 'HELLO',
134
+ * (name) => `Hello, ${name}!`,
81
135
  * {
82
136
  * description: 'customFunction.HELLO.description',
83
137
  * locales: {
84
138
  * 'zhCN': {
85
- * 'customFunction' : {
86
- * 'HELLO' : {
139
+ * 'customFunction': {
140
+ * 'HELLO': {
87
141
  * 'description': '一个简单的问候函数'
88
142
  * }
89
143
  * }
90
144
  * },
91
145
  * 'enUS': {
92
- * 'customFunction' : {
93
- * 'HELLO' : {
146
+ * 'customFunction': {
147
+ * 'HELLO': {
94
148
  * 'description': 'A simple greeting function'
95
149
  * }
96
150
  * }
@@ -99,9 +153,20 @@ export interface IFFormulaSheetsMixin {
99
153
  * }
100
154
  * );
101
155
  *
102
- * // Use in cell
103
- * univerAPI.getActiveWorkbook().getActiveSheet().getRange('A1').setValue({ f: '=HELLO("John")' });
104
- * // A1 will display: "Hello, John!"
156
+ * // Use the function in a cell
157
+ * const fWorkbook = univerAPI.getActiveWorkbook();
158
+ * const fSheet = fWorkbook.getActiveSheet();
159
+ * const cellA1 = fSheet.getRange('A1');
160
+ * cellA1.setValue('World');
161
+ * const cellA2 = fSheet.getRange('A2');
162
+ * cellA2.setValue({ f: '=HELLO(A1)' });
163
+ *
164
+ * // A2 will display: "Hello, World!"
165
+ * formulaEngine.calculationEnd((functionsExecutedState) => {
166
+ * if (functionsExecutedState === 3) {
167
+ * console.log(cellA2.getValue()); // Hello, World!
168
+ * }
169
+ * })
105
170
  * ```
106
171
  */
107
172
  registerFunction(name: string, func: IRegisterFunction, { locales, description }: {
@@ -110,12 +175,15 @@ export interface IFFormulaSheetsMixin {
110
175
  }): IDisposable;
111
176
  /**
112
177
  * Register a custom asynchronous formula function.
113
- * @param name - The name of the function to register. This will be used in formulas (e.g., =ASYNCFUNC())
114
- * @param func - The async implementation of the function
115
- * @returns A disposable object that will unregister the function when disposed
178
+ * @param {string} name - The name of the function to register. This will be used in formulas (e.g., =ASYNCFUNC()).
179
+ * @param {IRegisterAsyncFunction} func - The async implementation of the function.
180
+ * @param {string} [description] - A string describing the function's purpose and usage.
181
+ * @returns {IDisposable} A disposable object that will unregister the function when disposed.
116
182
  * @example
117
- * ```js
118
- * univerAPI.getFormula().registerAsyncFunction('RANDOM_DELAYED',
183
+ * ```ts
184
+ * const formulaEngine = univerAPI.getFormula();
185
+ * formulaEngine.registerAsyncFunction(
186
+ * 'RANDOM_DELAYED',
119
187
  * async () => {
120
188
  * await new Promise(resolve => setTimeout(resolve, 500));
121
189
  * return Math.random();
@@ -123,52 +191,62 @@ export interface IFFormulaSheetsMixin {
123
191
  * 'Mock a random number generation function'
124
192
  * );
125
193
  *
126
- * // Use in cell
127
- * univerAPI.getActiveWorkbook().getActiveSheet().getRange('A1').setValue({ f: '=RANDOM_DELAYED()' });
194
+ * // Use the function in a cell
195
+ * const fWorkbook = univerAPI.getActiveWorkbook();
196
+ * const fSheet = fWorkbook.getActiveSheet();
197
+ * const cellA1 = fSheet.getRange('A1');
198
+ * cellA1.setValue({ f: '=RANDOM_DELAYED()' });
199
+ *
128
200
  * // After 0.5 second, A1 will display a random number
129
201
  * ```
130
202
  */
131
203
  registerAsyncFunction(name: string, func: IRegisterAsyncFunction, description?: string): IDisposable;
132
204
  /**
133
205
  * Register a custom asynchronous formula function with description.
134
- * @param name - The name of the function to register. This will be used in formulas (e.g., =ASYNCFUNC())
135
- * @param func - The async implementation of the function
136
- * @param options - Object containing locales and description
137
- * @param options.locales - Object containing locales
138
- * @param options.description - Object containing description
139
- * @returns A disposable object that will unregister the function when disposed
206
+ * @param {string} name - The name of the function to register. This will be used in formulas (e.g., =ASYNCFUNC()).
207
+ * @param {IRegisterAsyncFunction} func - The async implementation of the function.
208
+ * @param {{ locales?: ILocales; description?: string | IFunctionInfo }} [options] - Object containing locales and description.
209
+ * @param {ILocales} options.locales - Object containing locales.
210
+ * @param {string | IFunctionInfo} options.description - Object containing description.
211
+ * @returns {IDisposable} A disposable object that will unregister the function when disposed.
140
212
  * @example
141
- * ```js
213
+ * ```ts
142
214
  * // Mock a user score fetching function
143
- * univerAPI.getFormula().registerAsyncFunction('FETCH_USER_SCORE',
215
+ * const formulaEngine = univerAPI.getFormula();
216
+ * formulaEngine.registerAsyncFunction(
217
+ * 'FETCH_USER_SCORE',
144
218
  * async (userId) => {
145
219
  * await new Promise(resolve => setTimeout(resolve, 1000));
146
220
  * // Mock fetching user score from database
147
221
  * return userId * 10 + Math.floor(Math.random() * 20);
148
222
  * },
149
223
  * {
150
- * description: 'customFunction.description.FETCH_USER_SCORE',
224
+ * description: 'customFunction.FETCH_USER_SCORE.description',
151
225
  * locales: {
152
226
  * 'zhCN': {
153
- * 'customFunction': {
154
- * 'description': {
155
- * 'FETCH_USER_SCORE': '从数据库中获取用户分数'
156
- * }
157
- * }
227
+ * 'customFunction': {
228
+ * 'FETCH_USER_SCORE': {
229
+ * 'description': '从数据库中获取用户分数'
230
+ * }
231
+ * }
158
232
  * },
159
233
  * 'enUS': {
160
- * 'customFunction': {
161
- * 'description': {
162
- * 'FETCH_USER_SCORE': 'Mock fetching user score from database'
163
- * }
164
- * }
234
+ * 'customFunction': {
235
+ * 'FETCH_USER_SCORE': {
236
+ * 'description': 'Mock fetching user score from database'
237
+ * }
238
+ * }
165
239
  * }
166
240
  * }
167
241
  * }
168
242
  * );
169
243
  *
170
- * // Use in cell
171
- * univerAPI.getActiveWorkbook().getActiveSheet().getRange('A1').setValue({ f: '=FETCH_USER_SCORE(42)' });
244
+ * // Use the function in a cell
245
+ * const fWorkbook = univerAPI.getActiveWorkbook();
246
+ * const fSheet = fWorkbook.getActiveSheet();
247
+ * const cellA1 = fSheet.getRange('A1');
248
+ * cellA1.setValue({ f: '=FETCH_USER_SCORE(42)' });
249
+ *
172
250
  * // After 1 second, A1 will display a score
173
251
  * ```
174
252
  */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@univerjs/sheets-formula",
3
- "version": "0.6.0",
3
+ "version": "0.6.1",
4
4
  "private": false,
5
5
  "author": "DreamNum <developer@univer.ai>",
6
6
  "license": "Apache-2.0",
@@ -57,18 +57,18 @@
57
57
  "rxjs": ">=7.0.0"
58
58
  },
59
59
  "dependencies": {
60
- "@univerjs/core": "0.6.0",
61
- "@univerjs/engine-formula": "0.6.0",
62
- "@univerjs/sheets": "0.6.0",
63
- "@univerjs/rpc": "0.6.0"
60
+ "@univerjs/core": "0.6.1",
61
+ "@univerjs/sheets": "0.6.1",
62
+ "@univerjs/engine-formula": "0.6.1",
63
+ "@univerjs/rpc": "0.6.1"
64
64
  },
65
65
  "devDependencies": {
66
66
  "rxjs": "^7.8.1",
67
67
  "typescript": "^5.7.3",
68
- "vite": "^6.1.0",
69
- "vitest": "^3.0.5",
70
- "@univerjs-infra/shared": "0.6.0",
71
- "@univerjs/docs": "0.6.0"
68
+ "vite": "^6.1.1",
69
+ "vitest": "^3.0.6",
70
+ "@univerjs-infra/shared": "0.6.1",
71
+ "@univerjs/docs": "0.6.1"
72
72
  },
73
73
  "scripts": {
74
74
  "test": "vitest run",