@univerjs-pro/docs-formula 1.0.0-alpha.8
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.
- package/README.md +27 -0
- package/lib/cjs/facade.js +1 -0
- package/lib/cjs/index.js +1 -0
- package/lib/es/facade.js +1 -0
- package/lib/es/index.js +1 -0
- package/lib/facade.js +1 -0
- package/lib/index.js +1 -0
- package/lib/types/commands/doc-formula.command.d.ts +11 -0
- package/lib/types/commands/doc-formula.mutation.d.ts +34 -0
- package/lib/types/common/actions.d.ts +41 -0
- package/lib/types/common/const.d.ts +4 -0
- package/lib/types/common/resource.d.ts +6 -0
- package/lib/types/common/type.d.ts +86 -0
- package/lib/types/config/config.d.ts +5 -0
- package/lib/types/controllers/doc-formula-lifecycle.controller.d.ts +16 -0
- package/lib/types/controllers/doc-formula-resource.controller.d.ts +7 -0
- package/lib/types/facade/f-document-formula.d.ts +291 -0
- package/lib/types/facade/f-document-paragraph.d.ts +91 -0
- package/lib/types/facade/f-document-text-range.d.ts +44 -0
- package/lib/types/facade/f-document.d.ts +178 -0
- package/lib/types/facade/index.d.ts +8 -0
- package/lib/types/facade/types.d.ts +128 -0
- package/lib/types/index.d.ts +17 -0
- package/lib/types/models/doc-formula-model.d.ts +25 -0
- package/lib/types/plugin.d.ts +14 -0
- package/lib/types/services/doc-formula-display-text.service.d.ts +39 -0
- package/lib/types/services/doc-formula-last-value-persistence.provider.d.ts +12 -0
- package/lib/types/services/doc-formula.service.d.ts +44 -0
- package/lib/umd/facade.js +1 -0
- package/lib/umd/index.js +1 -0
- package/package.json +87 -0
|
@@ -0,0 +1,291 @@
|
|
|
1
|
+
import type { IDocFormulaConfig, IDocFormulaResult } from '@univerjs-pro/docs-formula';
|
|
2
|
+
import type { IDocFormulaInfo, IDocFormulaRange, IDocFormulaUpdateFacadeOptions } from './types';
|
|
3
|
+
import { DocFormulaModel, DocFormulaService } from '@univerjs-pro/docs-formula';
|
|
4
|
+
import { ICommandService, IUniverInstanceService } from '@univerjs/core';
|
|
5
|
+
/**
|
|
6
|
+
* Facade handle for one inline data formula in a Univer document.
|
|
7
|
+
*
|
|
8
|
+
* The handle is identified by `rangeId`. It remains usable across recalculation,
|
|
9
|
+
* but mutating methods return `false` after the underlying custom range is
|
|
10
|
+
* removed. All writes execute public Doc Formula Commands; this class never
|
|
11
|
+
* mutates document or Resource state directly.
|
|
12
|
+
*
|
|
13
|
+
* @example
|
|
14
|
+
* ```ts
|
|
15
|
+
* import type { FUniver } from '@univerjs/core/facade';
|
|
16
|
+
* import '@univerjs-pro/docs-formula/facade';
|
|
17
|
+
*
|
|
18
|
+
* export function inspectFirstDocFormula(univerAPI: FUniver) {
|
|
19
|
+
* const document = univerAPI.getActiveDocument();
|
|
20
|
+
* if (!document) throw new Error('No active document');
|
|
21
|
+
*
|
|
22
|
+
* const formula = document.getFormulas()[0];
|
|
23
|
+
* if (!formula) throw new Error('No Doc Formula');
|
|
24
|
+
*
|
|
25
|
+
* const info = formula.describe();
|
|
26
|
+
* if (!info) throw new Error('The formula was removed');
|
|
27
|
+
* return info;
|
|
28
|
+
* }
|
|
29
|
+
* ```
|
|
30
|
+
*/
|
|
31
|
+
export declare class FDocumentFormula {
|
|
32
|
+
private readonly _unitId;
|
|
33
|
+
private readonly _rangeId;
|
|
34
|
+
private readonly _commandService;
|
|
35
|
+
private readonly _model;
|
|
36
|
+
private readonly _service;
|
|
37
|
+
private readonly _univerInstanceService;
|
|
38
|
+
constructor(_unitId: string, _rangeId: string, _commandService: ICommandService, _model: DocFormulaModel, _service: DocFormulaService, _univerInstanceService: IUniverInstanceService);
|
|
39
|
+
/**
|
|
40
|
+
* Returns the stable identity shared by the custom range, Resource entry,
|
|
41
|
+
* Other Formula registration, and this Facade handle.
|
|
42
|
+
*
|
|
43
|
+
* @returns The formula's stable `rangeId`.
|
|
44
|
+
* @example
|
|
45
|
+
* ```ts
|
|
46
|
+
* import type { FUniver } from '@univerjs/core/facade';
|
|
47
|
+
* import '@univerjs-pro/docs-formula/facade';
|
|
48
|
+
* export function readFormulaId(univerAPI: FUniver) {
|
|
49
|
+
* const formula = univerAPI.getActiveDocument()?.getFormulas()[0];
|
|
50
|
+
* if (!formula) throw new Error('No Doc Formula');
|
|
51
|
+
* return formula.getId();
|
|
52
|
+
* }
|
|
53
|
+
* ```
|
|
54
|
+
*/
|
|
55
|
+
getId(): string;
|
|
56
|
+
/**
|
|
57
|
+
* Returns the current main-body data-stream range.
|
|
58
|
+
*
|
|
59
|
+
* The formula occupies exactly one U+FFFC object token internally, so
|
|
60
|
+
* `endOffset` is exclusive and normally equals `startOffset + 1`.
|
|
61
|
+
*
|
|
62
|
+
* @returns The live range, or `null` after the custom range is removed.
|
|
63
|
+
* @example
|
|
64
|
+
* ```ts
|
|
65
|
+
* import type { FUniver } from '@univerjs/core/facade';
|
|
66
|
+
* import '@univerjs-pro/docs-formula/facade';
|
|
67
|
+
* export function readFormulaRange(univerAPI: FUniver) {
|
|
68
|
+
* const formula = univerAPI.getActiveDocument()?.getFormulas()[0];
|
|
69
|
+
* const range = formula?.getRange();
|
|
70
|
+
* if (!range) throw new Error('Formula range is unavailable');
|
|
71
|
+
* return range;
|
|
72
|
+
* }
|
|
73
|
+
* ```
|
|
74
|
+
*/
|
|
75
|
+
getRange(): IDocFormulaRange | null;
|
|
76
|
+
/**
|
|
77
|
+
* Returns the editable formula text from the unit-scoped Doc Formula
|
|
78
|
+
* Resource.
|
|
79
|
+
*
|
|
80
|
+
* @returns Formula text, or an empty string when the Resource entry is gone.
|
|
81
|
+
* @example
|
|
82
|
+
* ```ts
|
|
83
|
+
* import type { FUniver } from '@univerjs/core/facade';
|
|
84
|
+
* import '@univerjs-pro/docs-formula/facade';
|
|
85
|
+
* export function readFormulaText(univerAPI: FUniver) {
|
|
86
|
+
* const formula = univerAPI.getActiveDocument()?.getFormulas()[0];
|
|
87
|
+
* if (!formula) throw new Error('No Doc Formula');
|
|
88
|
+
* return formula.getFormula();
|
|
89
|
+
* }
|
|
90
|
+
* ```
|
|
91
|
+
*/
|
|
92
|
+
getFormula(): string;
|
|
93
|
+
/**
|
|
94
|
+
* Returns a detached copy of the persisted formula configuration.
|
|
95
|
+
*
|
|
96
|
+
* `lastValue` is the last successful scalar result. It is saved as Host
|
|
97
|
+
* content, inherits the document's read permissions, and may be stale until
|
|
98
|
+
* the current calculation session succeeds.
|
|
99
|
+
*
|
|
100
|
+
* @returns The configuration, or `null` when its Resource entry is gone.
|
|
101
|
+
* @example
|
|
102
|
+
* ```ts
|
|
103
|
+
* import type { FUniver } from '@univerjs/core/facade';
|
|
104
|
+
* import '@univerjs-pro/docs-formula/facade';
|
|
105
|
+
* export function readFormulaConfig(univerAPI: FUniver) {
|
|
106
|
+
* const formula = univerAPI.getActiveDocument()?.getFormulas()[0];
|
|
107
|
+
* const config = formula?.getConfig();
|
|
108
|
+
* if (!config) throw new Error('Formula config is unavailable');
|
|
109
|
+
* return config;
|
|
110
|
+
* }
|
|
111
|
+
* ```
|
|
112
|
+
*/
|
|
113
|
+
getConfig(): IDocFormulaConfig | null;
|
|
114
|
+
/**
|
|
115
|
+
* Returns the latest calculated or persisted presentation.
|
|
116
|
+
*
|
|
117
|
+
* `source: 'calculated'` identifies a live result. During reload or Source
|
|
118
|
+
* unavailability, the API can return the previous successful value with
|
|
119
|
+
* `source: 'persisted'` and `stale: true`. Formula errors and timeouts never
|
|
120
|
+
* overwrite that persisted value.
|
|
121
|
+
*
|
|
122
|
+
* @returns The current result, or `null` when the formula is not registered.
|
|
123
|
+
* @example
|
|
124
|
+
* ```ts
|
|
125
|
+
* import type { FUniver } from '@univerjs/core/facade';
|
|
126
|
+
* import '@univerjs-pro/docs-formula/facade';
|
|
127
|
+
* export function readFormulaResult(univerAPI: FUniver) {
|
|
128
|
+
* const formula = univerAPI.getActiveDocument()?.getFormulas()[0];
|
|
129
|
+
* const result = formula?.getResult();
|
|
130
|
+
* if (!result) throw new Error('Formula result is unavailable');
|
|
131
|
+
* return result;
|
|
132
|
+
* }
|
|
133
|
+
* ```
|
|
134
|
+
* @example Wait through the shared Formula facade, then read this result
|
|
135
|
+
* ```ts
|
|
136
|
+
* import type { FUniver } from '@univerjs/core/facade';
|
|
137
|
+
* import '@univerjs/engine-formula/facade';
|
|
138
|
+
* import '@univerjs-pro/docs-formula/facade';
|
|
139
|
+
*
|
|
140
|
+
* export async function insertAndReadFormula(univerAPI: FUniver) {
|
|
141
|
+
* const document = univerAPI.getActiveDocument();
|
|
142
|
+
* if (!document) throw new Error('No active document');
|
|
143
|
+
* const paragraph = document.getParagraphs()[0];
|
|
144
|
+
* if (!paragraph) throw new Error('No target paragraph');
|
|
145
|
+
*
|
|
146
|
+
* // Start watching before the write so a fast calculation cannot be missed.
|
|
147
|
+
* const applied = univerAPI.getFormula().onCalculationResultApplied(5_000);
|
|
148
|
+
* const formula = paragraph.appendFormula('=SUM(1,2,3)');
|
|
149
|
+
* if (!formula) throw new Error('Doc Formula insertion failed');
|
|
150
|
+
*
|
|
151
|
+
* await applied;
|
|
152
|
+
* const result = formula.getResult();
|
|
153
|
+
* if (!result) throw new Error('Formula result is unavailable');
|
|
154
|
+
* return result;
|
|
155
|
+
* }
|
|
156
|
+
* ```
|
|
157
|
+
*/
|
|
158
|
+
getResult(): IDocFormulaResult | null;
|
|
159
|
+
/**
|
|
160
|
+
* Returns an agent-friendly snapshot of identity, range, persisted config,
|
|
161
|
+
* and current presentation.
|
|
162
|
+
*
|
|
163
|
+
* @returns A detached description, or `null` if either side of the
|
|
164
|
+
* custom-range/Resource pair no longer exists.
|
|
165
|
+
* @example
|
|
166
|
+
* ```ts
|
|
167
|
+
* import type { FUniver } from '@univerjs/core/facade';
|
|
168
|
+
* import '@univerjs-pro/docs-formula/facade';
|
|
169
|
+
* export function describeFormulas(univerAPI: FUniver) {
|
|
170
|
+
* const formulas = univerAPI.getActiveDocument()?.getFormulas() ?? [];
|
|
171
|
+
* return formulas
|
|
172
|
+
* .map((formula) => formula.describe())
|
|
173
|
+
* .filter((value) => value !== null);
|
|
174
|
+
* }
|
|
175
|
+
* ```
|
|
176
|
+
*/
|
|
177
|
+
describe(): IDocFormulaInfo | null;
|
|
178
|
+
/**
|
|
179
|
+
* Replaces the formula binding through `UpdateDocFormulaCommand`.
|
|
180
|
+
*
|
|
181
|
+
* The command validates and persists all external Source bindings, clears
|
|
182
|
+
* the previous `lastValue`, and records one undo item. The caller should
|
|
183
|
+
* provide every newly selected external Source in `externalReferences`.
|
|
184
|
+
*
|
|
185
|
+
* @param options Replacement formula, optional number format, and stable
|
|
186
|
+
* external Source bindings.
|
|
187
|
+
* @returns Whether the command committed successfully.
|
|
188
|
+
* @example
|
|
189
|
+
* ```ts
|
|
190
|
+
* import type { FUniver } from '@univerjs/core/facade';
|
|
191
|
+
* import '@univerjs-pro/docs-formula/facade';
|
|
192
|
+
* export function updateFormula(univerAPI: FUniver) {
|
|
193
|
+
* const formula = univerAPI.getActiveDocument()?.getFormulas()[0];
|
|
194
|
+
* if (!formula) throw new Error('No Doc Formula');
|
|
195
|
+
* const updated = formula.update({
|
|
196
|
+
* formula: '=SUM(1, 2, 3)',
|
|
197
|
+
* numberFormat: { pattern: '0.00' },
|
|
198
|
+
* });
|
|
199
|
+
* if (!updated) throw new Error('Failed to update Doc Formula');
|
|
200
|
+
* }
|
|
201
|
+
* ```
|
|
202
|
+
*/
|
|
203
|
+
update(options: IDocFormulaUpdateFacadeOptions): boolean;
|
|
204
|
+
/**
|
|
205
|
+
* Updates only the explicit number format through a Command.
|
|
206
|
+
*
|
|
207
|
+
* Passing `undefined` removes the explicit format. This operation preserves
|
|
208
|
+
* the raw `lastValue`, immediately re-formats the current presentation, and
|
|
209
|
+
* participates in normal undo/redo and collaboration.
|
|
210
|
+
*
|
|
211
|
+
* @param numberFormat New format, or `undefined` to inherit/default.
|
|
212
|
+
* @param numberFormat.pattern Univer number-format pattern.
|
|
213
|
+
* @returns Whether the command committed successfully.
|
|
214
|
+
* @example
|
|
215
|
+
* ```ts
|
|
216
|
+
* import type { FUniver } from '@univerjs/core/facade';
|
|
217
|
+
* import '@univerjs-pro/docs-formula/facade';
|
|
218
|
+
* export function formatFormula(univerAPI: FUniver) {
|
|
219
|
+
* const formula = univerAPI.getActiveDocument()?.getFormulas()[0];
|
|
220
|
+
* if (!formula) throw new Error('No Doc Formula');
|
|
221
|
+
* if (!formula.setNumberFormat({ pattern: '$#,##0.00' })) {
|
|
222
|
+
* throw new Error('Failed to format Doc Formula');
|
|
223
|
+
* }
|
|
224
|
+
* }
|
|
225
|
+
* ```
|
|
226
|
+
*/
|
|
227
|
+
setNumberFormat(numberFormat?: {
|
|
228
|
+
pattern: string;
|
|
229
|
+
}): boolean;
|
|
230
|
+
/**
|
|
231
|
+
* Removes the formula object and its one-character token.
|
|
232
|
+
*
|
|
233
|
+
* @returns Whether the remove command committed successfully.
|
|
234
|
+
* @example
|
|
235
|
+
* ```ts
|
|
236
|
+
* import type { FUniver } from '@univerjs/core/facade';
|
|
237
|
+
* import '@univerjs-pro/docs-formula/facade';
|
|
238
|
+
* export function removeFormula(univerAPI: FUniver) {
|
|
239
|
+
* const formula = univerAPI.getActiveDocument()?.getFormulas()[0];
|
|
240
|
+
* if (!formula) throw new Error('No Doc Formula');
|
|
241
|
+
* if (!formula.remove()) throw new Error('Failed to remove Doc Formula');
|
|
242
|
+
* }
|
|
243
|
+
* ```
|
|
244
|
+
*/
|
|
245
|
+
remove(): boolean;
|
|
246
|
+
/**
|
|
247
|
+
* Replaces the formula object with caller-provided plain text.
|
|
248
|
+
*
|
|
249
|
+
* Use `convertToText()` when the desired text is the current formatted
|
|
250
|
+
* formula presentation.
|
|
251
|
+
*
|
|
252
|
+
* @param text Plain replacement text.
|
|
253
|
+
* @returns Whether the replace command committed successfully.
|
|
254
|
+
* @example
|
|
255
|
+
* ```ts
|
|
256
|
+
* import type { FUniver } from '@univerjs/core/facade';
|
|
257
|
+
* import '@univerjs-pro/docs-formula/facade';
|
|
258
|
+
* export function replaceFormula(univerAPI: FUniver) {
|
|
259
|
+
* const formula = univerAPI.getActiveDocument()?.getFormulas()[0];
|
|
260
|
+
* if (!formula) throw new Error('No Doc Formula');
|
|
261
|
+
* if (!formula.replaceWithText('Total: 42')) {
|
|
262
|
+
* throw new Error('Failed to replace Doc Formula');
|
|
263
|
+
* }
|
|
264
|
+
* }
|
|
265
|
+
* ```
|
|
266
|
+
*/
|
|
267
|
+
replaceWithText(text: string): boolean;
|
|
268
|
+
/**
|
|
269
|
+
* Converts the formula to its current formatted display text.
|
|
270
|
+
*
|
|
271
|
+
* The Command resolves the presentation; the Facade does not duplicate
|
|
272
|
+
* formatting business logic. A stale persisted presentation is permitted
|
|
273
|
+
* and is converted exactly as displayed. The operation is undoable.
|
|
274
|
+
*
|
|
275
|
+
* @returns Whether conversion committed successfully.
|
|
276
|
+
* @example
|
|
277
|
+
* ```ts
|
|
278
|
+
* import type { FUniver } from '@univerjs/core/facade';
|
|
279
|
+
* import '@univerjs-pro/docs-formula/facade';
|
|
280
|
+
* export function convertFormula(univerAPI: FUniver) {
|
|
281
|
+
* const formula = univerAPI.getActiveDocument()?.getFormulas()[0];
|
|
282
|
+
* if (!formula) throw new Error('No Doc Formula');
|
|
283
|
+
* if (!formula.convertToText()) {
|
|
284
|
+
* throw new Error('No presentation was available to convert');
|
|
285
|
+
* }
|
|
286
|
+
* }
|
|
287
|
+
* ```
|
|
288
|
+
*/
|
|
289
|
+
convertToText(): boolean;
|
|
290
|
+
private _getCustomRange;
|
|
291
|
+
}
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
import type { Injector } from '@univerjs/core';
|
|
2
|
+
import type { IDocFormulaCreateFacadeOptions } from './types';
|
|
3
|
+
import { FDocumentParagraph } from '@univerjs/docs/facade';
|
|
4
|
+
import { FDocumentFormula } from './f-document-formula';
|
|
5
|
+
/** Formula insertion methods added to main-body `FDocumentParagraph` handles. */
|
|
6
|
+
export interface IFDocumentParagraphFormulaMixin {
|
|
7
|
+
/**
|
|
8
|
+
* Inserts one Formula at a paragraph-relative UTF-16 offset.
|
|
9
|
+
*
|
|
10
|
+
* The paragraph handle is backed by its persisted `paragraphId`. The
|
|
11
|
+
* Command resolves that id against the latest document snapshot and only
|
|
12
|
+
* then converts `offset` to a document position. Edits before this paragraph
|
|
13
|
+
* therefore do not invalidate the insertion anchor.
|
|
14
|
+
*
|
|
15
|
+
* Use `0` to insert at the content start. Prefer `appendFormula()` for the
|
|
16
|
+
* current content end because it resolves the semantic `'end'` position
|
|
17
|
+
* without requiring the caller to measure UTF-16 text length.
|
|
18
|
+
*
|
|
19
|
+
* @param offset Zero-based UTF-16 offset relative to this paragraph's text.
|
|
20
|
+
* @param formula Formula text.
|
|
21
|
+
* @param options Optional number format and stable external Source bindings.
|
|
22
|
+
* @returns The inserted formula, or `null` when the paragraph is missing,
|
|
23
|
+
* outside the main body, the offset is invalid, or Command validation fails.
|
|
24
|
+
* @example Insert between a stable label and its suffix
|
|
25
|
+
* ```ts
|
|
26
|
+
* import type { FUniver } from '@univerjs/core/facade';
|
|
27
|
+
* import '@univerjs-pro/docs-formula/facade';
|
|
28
|
+
*
|
|
29
|
+
* export function insertFormulaInsideParagraph(univerAPI: FUniver) {
|
|
30
|
+
* const document = univerAPI.getActiveDocument();
|
|
31
|
+
* if (!document) throw new Error('No active document');
|
|
32
|
+
*
|
|
33
|
+
* const paragraph = document.appendParagraph('Revenue: USD');
|
|
34
|
+
* const paragraphId = paragraph.getId();
|
|
35
|
+
*
|
|
36
|
+
* // This edit changes every following absolute document offset.
|
|
37
|
+
* document.insertParagraph(0, 'Quarterly report');
|
|
38
|
+
*
|
|
39
|
+
* const stableParagraph = document.getParagraph(paragraphId);
|
|
40
|
+
* if (!stableParagraph) throw new Error('Revenue paragraph was removed');
|
|
41
|
+
* const formula = stableParagraph.insertFormula('Revenue: '.length, '=1000/4', {
|
|
42
|
+
* numberFormat: { pattern: '#,##0.00' },
|
|
43
|
+
* });
|
|
44
|
+
* if (!formula) throw new Error('Failed to insert Doc Formula');
|
|
45
|
+
* return formula.describe();
|
|
46
|
+
* }
|
|
47
|
+
* ```
|
|
48
|
+
*/
|
|
49
|
+
insertFormula(offset: number, formula: string, options?: IDocFormulaCreateFacadeOptions): FDocumentFormula | null;
|
|
50
|
+
/**
|
|
51
|
+
* Appends one Formula before this paragraph's trailing paragraph token.
|
|
52
|
+
*
|
|
53
|
+
* The Command resolves the persisted `paragraphId` and the semantic `'end'`
|
|
54
|
+
* position together. It does not capture an absolute document offset or a
|
|
55
|
+
* paragraph length in advance. Header/footer paragraphs are rejected because
|
|
56
|
+
* Doc Formula v1 supports the main body only.
|
|
57
|
+
*
|
|
58
|
+
* @param formula Formula text.
|
|
59
|
+
* @param options Optional number format and stable external Source bindings.
|
|
60
|
+
* @returns The inserted formula, or `null` when the paragraph is missing,
|
|
61
|
+
* outside the main body, or the command validation fails.
|
|
62
|
+
* @example
|
|
63
|
+
* ```ts
|
|
64
|
+
* import type { FUniver } from '@univerjs/core/facade';
|
|
65
|
+
* import '@univerjs-pro/docs-formula/facade';
|
|
66
|
+
*
|
|
67
|
+
* export function appendParagraphFormula(univerAPI: FUniver) {
|
|
68
|
+
* const document = univerAPI.getActiveDocument();
|
|
69
|
+
* if (!document) throw new Error('No active document');
|
|
70
|
+
* const paragraph = document.appendParagraph('Revenue: ');
|
|
71
|
+
* const formula = paragraph.appendFormula('=1000/4', {
|
|
72
|
+
* numberFormat: { pattern: '$#,##0.00' },
|
|
73
|
+
* });
|
|
74
|
+
* if (!formula) throw new Error('Failed to append Doc Formula');
|
|
75
|
+
* return formula.describe();
|
|
76
|
+
* }
|
|
77
|
+
* ```
|
|
78
|
+
*/
|
|
79
|
+
appendFormula(formula: string, options?: IDocFormulaCreateFacadeOptions): FDocumentFormula | null;
|
|
80
|
+
}
|
|
81
|
+
export declare class FDocumentParagraphFormulaMixin extends FDocumentParagraph implements IFDocumentParagraphFormulaMixin {
|
|
82
|
+
private _docsFormulaCommandService;
|
|
83
|
+
_initialize(injector: Injector): void;
|
|
84
|
+
insertFormula(offset: number, formula: string, options?: IDocFormulaCreateFacadeOptions): FDocumentFormula | null;
|
|
85
|
+
appendFormula(formula: string, options?: IDocFormulaCreateFacadeOptions): FDocumentFormula | null;
|
|
86
|
+
private _insert;
|
|
87
|
+
}
|
|
88
|
+
declare module '@univerjs/docs/facade' {
|
|
89
|
+
interface FDocumentParagraph extends IFDocumentParagraphFormulaMixin {
|
|
90
|
+
}
|
|
91
|
+
}
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
import type { Injector } from '@univerjs/core';
|
|
2
|
+
import type { IDocFormulaCreateFacadeOptions } from './types';
|
|
3
|
+
import { FDocumentTextRange } from '@univerjs/docs/facade';
|
|
4
|
+
import { FDocumentFormula } from './f-document-formula';
|
|
5
|
+
/** Formula insertion methods added to fixed `FDocumentTextRange` handles. */
|
|
6
|
+
export interface IFDocumentTextRangeFormulaMixin {
|
|
7
|
+
/**
|
|
8
|
+
* Replaces this complete text range with one whole-entity Doc Formula.
|
|
9
|
+
*
|
|
10
|
+
* The fixed range must be in the main body and must not cross paragraph,
|
|
11
|
+
* table-cell, section, column, or protected structural boundaries.
|
|
12
|
+
*
|
|
13
|
+
* @param formula Formula text.
|
|
14
|
+
* @param options Optional number format and complete external Source bindings.
|
|
15
|
+
* @returns The inserted formula, or `null` when range/binding validation fails.
|
|
16
|
+
* @example
|
|
17
|
+
* ```ts
|
|
18
|
+
* import type { FUniver } from '@univerjs/core/facade';
|
|
19
|
+
* import '@univerjs-pro/docs-formula/facade';
|
|
20
|
+
*
|
|
21
|
+
* export function replacePlaceholderWithFormula(univerAPI: FUniver) {
|
|
22
|
+
* const document = univerAPI.getActiveDocument();
|
|
23
|
+
* if (!document) throw new Error('No active document');
|
|
24
|
+
* const paragraph = document.findParagraphByText('FORMULA_PLACEHOLDER');
|
|
25
|
+
* const range = paragraph?.findText('FORMULA_PLACEHOLDER');
|
|
26
|
+
* if (!range) throw new Error('Formula placeholder not found');
|
|
27
|
+
* const formula = range.replaceWithFormula('=SUM(10,20)');
|
|
28
|
+
* if (!formula) throw new Error('Failed to replace the range');
|
|
29
|
+
* return formula.describe();
|
|
30
|
+
* }
|
|
31
|
+
* ```
|
|
32
|
+
*/
|
|
33
|
+
replaceWithFormula(formula: string, options?: IDocFormulaCreateFacadeOptions): FDocumentFormula | null;
|
|
34
|
+
}
|
|
35
|
+
export declare class FDocumentTextRangeFormulaMixin extends FDocumentTextRange implements IFDocumentTextRangeFormulaMixin {
|
|
36
|
+
private _docsFormulaCommandService;
|
|
37
|
+
_initialize(injector: Injector): void;
|
|
38
|
+
replaceWithFormula(formula: string, options?: IDocFormulaCreateFacadeOptions): FDocumentFormula | null;
|
|
39
|
+
private _insert;
|
|
40
|
+
}
|
|
41
|
+
declare module '@univerjs/docs/facade' {
|
|
42
|
+
interface FDocumentTextRange extends IFDocumentTextRangeFormulaMixin {
|
|
43
|
+
}
|
|
44
|
+
}
|
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
import type { IDocumentData, Injector } from '@univerjs/core';
|
|
2
|
+
import type { IDocFormulaInsertFacadeOptions } from './types';
|
|
3
|
+
import { FDocument } from '@univerjs/docs/facade';
|
|
4
|
+
import { FDocumentFormula } from './f-document-formula';
|
|
5
|
+
/**
|
|
6
|
+
* Doc Formula methods added to `FDocument` after importing
|
|
7
|
+
* `@univerjs-pro/docs-formula/facade`.
|
|
8
|
+
*/
|
|
9
|
+
export interface IFDocumentFormulaMixin {
|
|
10
|
+
/**
|
|
11
|
+
* Lists complete Formula custom-range/Resource pairs in the main body.
|
|
12
|
+
*
|
|
13
|
+
* Incomplete or unsupported persisted data remains preserved by the core
|
|
14
|
+
* plugin but is intentionally omitted from calculation and this list.
|
|
15
|
+
*
|
|
16
|
+
* @returns Formula handles in document order, or an empty array.
|
|
17
|
+
* @example
|
|
18
|
+
* ```ts
|
|
19
|
+
* import type { FUniver } from '@univerjs/core/facade';
|
|
20
|
+
* import '@univerjs-pro/docs-formula/facade';
|
|
21
|
+
*
|
|
22
|
+
* export function listDocFormulas(univerAPI: FUniver) {
|
|
23
|
+
* const document = univerAPI.getActiveDocument();
|
|
24
|
+
* if (!document) throw new Error('No active document');
|
|
25
|
+
* return document.getFormulas().map((formula) => formula.describe());
|
|
26
|
+
* }
|
|
27
|
+
* ```
|
|
28
|
+
*/
|
|
29
|
+
getFormulas(): FDocumentFormula[];
|
|
30
|
+
/**
|
|
31
|
+
* Resolves one complete Doc Formula by stable `rangeId`.
|
|
32
|
+
*
|
|
33
|
+
* @param rangeId Identity returned by insertion or `FDocumentFormula.getId`.
|
|
34
|
+
* @returns A handle, or `null` when either the range or Resource entry is absent.
|
|
35
|
+
* @example
|
|
36
|
+
* ```ts
|
|
37
|
+
* import type { FUniver } from '@univerjs/core/facade';
|
|
38
|
+
* import '@univerjs-pro/docs-formula/facade';
|
|
39
|
+
*
|
|
40
|
+
* export function getDocFormula(univerAPI: FUniver, rangeId: string) {
|
|
41
|
+
* const document = univerAPI.getActiveDocument();
|
|
42
|
+
* if (!document) throw new Error('No active document');
|
|
43
|
+
* const formula = document.getFormula(rangeId);
|
|
44
|
+
* if (!formula) throw new Error(`Doc Formula ${rangeId} was not found`);
|
|
45
|
+
* return formula;
|
|
46
|
+
* }
|
|
47
|
+
* ```
|
|
48
|
+
*/
|
|
49
|
+
getFormula(rangeId: string): FDocumentFormula | null;
|
|
50
|
+
/**
|
|
51
|
+
* Resolves the whole-entity Doc Formula containing a main-body offset.
|
|
52
|
+
*
|
|
53
|
+
* @param offset Document data-stream offset.
|
|
54
|
+
* @returns A handle, or `null` when the offset is not a complete Doc Formula.
|
|
55
|
+
* @example
|
|
56
|
+
* ```ts
|
|
57
|
+
* import type { FUniver } from '@univerjs/core/facade';
|
|
58
|
+
* import '@univerjs-pro/docs-formula/facade';
|
|
59
|
+
*
|
|
60
|
+
* export function getDocFormulaAt(univerAPI: FUniver, offset: number) {
|
|
61
|
+
* const document = univerAPI.getActiveDocument();
|
|
62
|
+
* if (!document) throw new Error('No active document');
|
|
63
|
+
* return document.getFormulaAt(offset);
|
|
64
|
+
* }
|
|
65
|
+
* ```
|
|
66
|
+
*/
|
|
67
|
+
getFormulaAt(offset: number): FDocumentFormula | null;
|
|
68
|
+
/**
|
|
69
|
+
* Saves a detached external-format projection of this document.
|
|
70
|
+
*
|
|
71
|
+
* Native `save()` preserves Formula custom ranges and Resource entries.
|
|
72
|
+
* This method instead replaces every main-body Doc Formula object with its
|
|
73
|
+
* persisted `lastValue` display text and removes the Doc Formula Resource from
|
|
74
|
+
* the returned snapshot. It never mutates the live document and is intended
|
|
75
|
+
* for Markdown, HTML, TXT, DOCX, and other non-native exporters.
|
|
76
|
+
*
|
|
77
|
+
* Export never triggers calculation, waits for a result, or reads the
|
|
78
|
+
* current in-memory presentation. The last successful persisted value is
|
|
79
|
+
* emitted with its inherited or explicit number format. A missing or empty
|
|
80
|
+
* `lastValue` becomes an empty string; U+FFFC is never returned.
|
|
81
|
+
*
|
|
82
|
+
* @returns A detached `IDocumentData` projection safe for external export.
|
|
83
|
+
* @example
|
|
84
|
+
* ```ts
|
|
85
|
+
* import type { FUniver } from '@univerjs/core/facade';
|
|
86
|
+
* import '@univerjs-pro/docs-formula/facade';
|
|
87
|
+
*
|
|
88
|
+
* export function saveForExternalExporter(univerAPI: FUniver) {
|
|
89
|
+
* const document = univerAPI.getActiveDocument();
|
|
90
|
+
* if (!document) throw new Error('No active document');
|
|
91
|
+
* const snapshot = document.saveFormulaDisplayTextSnapshot();
|
|
92
|
+
* if (snapshot.body?.dataStream.includes('\uFFFC')) {
|
|
93
|
+
* throw new Error('External snapshot contains an object token');
|
|
94
|
+
* }
|
|
95
|
+
* return snapshot;
|
|
96
|
+
* }
|
|
97
|
+
* ```
|
|
98
|
+
*/
|
|
99
|
+
saveFormulaDisplayTextSnapshot(): IDocumentData;
|
|
100
|
+
/**
|
|
101
|
+
* Replaces an explicit main-body range with one inline Doc Formula.
|
|
102
|
+
*
|
|
103
|
+
* The offsets are snapshot-relative and resolved immediately. This API is
|
|
104
|
+
* suitable when the caller already owns a current range in the same
|
|
105
|
+
* synchronous workflow. Agent and delayed headless workflows should prefer
|
|
106
|
+
* a stable `FDocumentParagraph` handle with `insertFormula()` or
|
|
107
|
+
* `appendFormula()`.
|
|
108
|
+
*
|
|
109
|
+
* The Command validates the range, formula syntax, and complete external
|
|
110
|
+
* Source bindings before it commits TextX, Host External Reference, and Doc
|
|
111
|
+
* Formula Resource mutations as one undoable user action.
|
|
112
|
+
*
|
|
113
|
+
* @param options Formula, half-open replacement range, number format, and
|
|
114
|
+
* any stable external Source bindings.
|
|
115
|
+
* @returns The inserted handle, or `null` if validation or a mutation fails.
|
|
116
|
+
* @example
|
|
117
|
+
* ```ts
|
|
118
|
+
* import type { FUniver } from '@univerjs/core/facade';
|
|
119
|
+
* import '@univerjs-pro/docs-formula/facade';
|
|
120
|
+
*
|
|
121
|
+
* export function insertConstantFormula(univerAPI: FUniver) {
|
|
122
|
+
* const document = univerAPI.getActiveDocument();
|
|
123
|
+
* if (!document) throw new Error('No active document');
|
|
124
|
+
* const formula = document.insertFormula({
|
|
125
|
+
* formula: '=1+2',
|
|
126
|
+
* startOffset: 0,
|
|
127
|
+
* endOffset: 0,
|
|
128
|
+
* numberFormat: { pattern: '0.00' },
|
|
129
|
+
* });
|
|
130
|
+
* if (!formula) throw new Error('Doc Formula insertion failed');
|
|
131
|
+
* return formula.getId();
|
|
132
|
+
* }
|
|
133
|
+
* ```
|
|
134
|
+
* @example
|
|
135
|
+
* ```ts
|
|
136
|
+
* import { UniverInstanceType } from '@univerjs/core';
|
|
137
|
+
* import type { FUniver } from '@univerjs/core/facade';
|
|
138
|
+
* import '@univerjs-pro/docs-formula/facade';
|
|
139
|
+
*
|
|
140
|
+
* export function insertBoundFormula(univerAPI: FUniver) {
|
|
141
|
+
* const document = univerAPI.getActiveDocument();
|
|
142
|
+
* if (!document) throw new Error('No active document');
|
|
143
|
+
* const formula = document.insertFormula({
|
|
144
|
+
* formula: "='[Sales Source]Data'!A1",
|
|
145
|
+
* startOffset: 0,
|
|
146
|
+
* endOffset: 0,
|
|
147
|
+
* externalReferences: [{
|
|
148
|
+
* qualifier: 'Sales Source',
|
|
149
|
+
* sourceUnitId: 'sales-source-v1',
|
|
150
|
+
* sourceUnitType: UniverInstanceType.UNIVER_SHEET,
|
|
151
|
+
* }],
|
|
152
|
+
* });
|
|
153
|
+
* if (!formula) throw new Error('Source binding or range was invalid');
|
|
154
|
+
* return formula.getId();
|
|
155
|
+
* }
|
|
156
|
+
* ```
|
|
157
|
+
*/
|
|
158
|
+
insertFormula(options: IDocFormulaInsertFacadeOptions): FDocumentFormula | null;
|
|
159
|
+
}
|
|
160
|
+
export declare class FDocumentFormulaMixin extends FDocument implements IFDocumentFormulaMixin {
|
|
161
|
+
private _docsFormulaCommandService;
|
|
162
|
+
private _docsFormulaDisplayTextService;
|
|
163
|
+
private _docsFormulaModel;
|
|
164
|
+
private _docsFormulaResourceLoaderService;
|
|
165
|
+
_initialize(injector: Injector): void;
|
|
166
|
+
getFormulas(): FDocumentFormula[];
|
|
167
|
+
getFormula(rangeId: string): FDocumentFormula | null;
|
|
168
|
+
getFormulaAt(offset: number): FDocumentFormula | null;
|
|
169
|
+
saveFormulaDisplayTextSnapshot(): IDocumentData;
|
|
170
|
+
insertFormula(options: IDocFormulaInsertFacadeOptions): FDocumentFormula | null;
|
|
171
|
+
private _insert;
|
|
172
|
+
private _getCompleteRanges;
|
|
173
|
+
private _createFormula;
|
|
174
|
+
}
|
|
175
|
+
declare module '@univerjs/docs/facade' {
|
|
176
|
+
interface FDocument extends IFDocumentFormulaMixin {
|
|
177
|
+
}
|
|
178
|
+
}
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import './f-document';
|
|
2
|
+
import './f-document-paragraph';
|
|
3
|
+
import './f-document-text-range';
|
|
4
|
+
export type { IFDocumentFormulaMixin } from './f-document';
|
|
5
|
+
export { FDocumentFormula } from './f-document-formula';
|
|
6
|
+
export type { IFDocumentParagraphFormulaMixin } from './f-document-paragraph';
|
|
7
|
+
export type { IFDocumentTextRangeFormulaMixin } from './f-document-text-range';
|
|
8
|
+
export type { IDocFormulaCreateFacadeOptions, IDocFormulaInfo, IDocFormulaInsertFacadeOptions, IDocFormulaRange, IDocFormulaUpdateFacadeOptions, } from './types';
|