Build your own AI office with Univer Office SDK. Bring editing, calculation, collaboration, and file processing into your product for people and AI agents. Built on an extensible open-source core.
TypeScript boardcollaborationdocdocxexceloffce365officepdfpptpptxpresentationsdksheetslidesspreadsheetuniverwordwordprocessorworkspacexlsx
docs: fix facade api jsdoc inconsistencies (#7191)
白熱b8f7f6ff64ee
diff --git a/packages/core/src/facade/f-hooks.ts b/packages/core/src/facade/f-hooks.tsindex cc239c95b1..04416ad4ff 100644--- a/packages/core/src/facade/f-hooks.ts+++ b/packages/core/src/facade/f-hooks.ts@@ -42,6 +42,7 @@ export class FHooks extends FBase {/*** @param callback+ * @returns {IDisposable} A disposable used to remove the listener.* @deprecated use `univerAPI.addEvent(univerAPI.Event.LifeCycleChanged, ({ stage }) => {})` as instead*/onStarting(callback: () => void): IDisposable {@@ -50,6 +51,7 @@ export class FHooks extends FBase {/*** @param callback+ * @returns {IDisposable} A disposable used to remove the listener.* @deprecated use `univerAPI.addEvent(univerAPI.Event.LifeCycleChanged, ({ stage }) => {})` as instead*/onReady(callback: () => void): IDisposable {@@ -58,6 +60,7 @@ export class FHooks extends FBase {/*** @param callback+ * @returns {IDisposable} A disposable used to remove the listener.* @deprecated use `univerAPI.addEvent(univerAPI.Event.LifeCycleChanged, ({ stage }) => {})` as instead*/onRendered(callback: () => void): IDisposable {@@ -66,6 +69,7 @@ export class FHooks extends FBase {/*** @param callback+ * @returns {IDisposable} A disposable used to remove the listener.* @deprecated use `univerAPI.addEvent(univerAPI.Event.LifeCycleChanged, ({ stage }) => {})` as instead*/onSteady(callback: () => void): IDisposable {@@ -74,6 +78,7 @@ export class FHooks extends FBase {/*** @param callback+ * @returns {IDisposable} A disposable used to remove the listener.* @deprecated use `univerAPI.addEvent(univerAPI.Event.BeforeUndo, (event) => {})` as instead*/onBeforeUndo(callback: (action: IUndoRedoItem) => void): IDisposable {@@ -92,6 +97,7 @@ export class FHooks extends FBase {/*** @param callback+ * @returns {IDisposable} A disposable used to remove the listener.* @deprecated use `univerAPI.addEvent(univerAPI.Event.Undo, (event) => {})` as instead*/onUndo(callback: (action: IUndoRedoItem) => void): IDisposable {@@ -110,6 +116,7 @@ export class FHooks extends FBase {/*** @param callback+ * @returns {IDisposable} A disposable used to remove the listener.* @deprecated use `univerAPI.addEvent(univerAPI.Event.BeforeRedo, (event) => {})` as instead*/onBeforeRedo(callback: (action: IUndoRedoItem) => void): IDisposable {@@ -128,6 +135,7 @@ export class FHooks extends FBase {/*** @param callback+ * @returns {IDisposable} A disposable used to remove the listener.* @deprecated use `univerAPI.addEvent(univerAPI.Event.Redo, (event) => {})` as instead*/onRedo(callback: (action: IUndoRedoItem) => void): IDisposable {diff --git a/packages/docs/src/facade/f-document.ts b/packages/docs/src/facade/f-document.tsindex ab0e5e2a5c..08288d8d40 100644--- a/packages/docs/src/facade/f-document.ts+++ b/packages/docs/src/facade/f-document.ts@@ -393,6 +393,7 @@ export class FDocument extends FBaseInitialable {/*** Append a plain-text paragraph at the end of the body.* @param {string} text The paragraph text. Defaults to an empty paragraph.+ * @param {string} segmentId The segment id of the body. Defaults to an empty string for the main body.* @returns {FDocumentParagraph} The appended paragraph wrapper.* @example* ```tsdiff --git a/packages/engine-formula/src/facade/f-formula.ts b/packages/engine-formula/src/facade/f-formula.tsindex fe28e07b8d..50bf244ea2 100644--- a/packages/engine-formula/src/facade/f-formula.ts+++ b/packages/engine-formula/src/facade/f-formula.ts@@ -205,6 +205,8 @@ export class FFormula extends FBase {/*** @deprecated Use `onCalculationResultApplied` instead.+ * @param {number} [timeout] The timeout in milliseconds. Defaults to 30000.+ * @returns {Promise<boolean>} Whether computing completed before timeout.*/whenComputingCompleteAsync(timeout?: number): Promise<boolean> {const gcss = this._injector.get(GlobalComputingStatusService);@@ -218,6 +220,7 @@ export class FFormula extends FBase {/*** @deprecated Use `onCalculationResultApplied` instead.+ * @returns {Promise<void>} A promise that resolves when calculation ends.*/onCalculationEnd(): Promise<void> {return new Promise((resolve, reject) => {@@ -439,11 +442,11 @@ export class FFormula extends FBase {* dependency-calculation command for the given unit, sheet, and cell location,* and returns the computed dependency tree when the calculation is completed.*- * @param param The target cell location:- * - `unitId` The workbook ID.- * - `sheetId` The sheet ID.- * - `row` The zero-based row index.- * - `column` The zero-based column index.+ * @param {object} param The target cell location.+ * @param {string} param.unitId The workbook ID.+ * @param {string} param.sheetId The sheet ID.+ * @param {number} param.row The zero-based row index.+ * @param {number} param.column The zero-based column index.** @param {number} [timeout]* Optional timeout in milliseconds. If no result is received within this@@ -749,6 +752,7 @@ export class FFormula extends FBase {* ```** @param formulaString The formula string to parse (with or without leading `=`)+ * @param unitId The workbook unit id used to resolve defined names and tables.* @returns A formula expression tree describing the hierarchical structure of the formula*/getFormulaExpressTree(formulaString: string, unitId: string): IExprTreeNode | null {diff --git a/packages/sheets-conditional-formatting/src/facade/f-conditional-formatting-builder.ts b/packages/sheets-conditional-formatting/src/facade/f-conditional-formatting-builder.tsindex 94778ba1f5..e19b94b93d 100644--- a/packages/sheets-conditional-formatting/src/facade/f-conditional-formatting-builder.ts+++ b/packages/sheets-conditional-formatting/src/facade/f-conditional-formatting-builder.ts@@ -1108,14 +1108,7 @@ class ConditionalFormatDataBarRuleBuilder extends ConditionalFormatRuleBaseBuild/*** Set data bar rule.- * @param {{- * min: IValueConfig;- * max: IValueConfig;- * isGradient?: boolean;- * positiveColor: string;- * nativeColor: string;- * isShowValue?: boolean;- * }} config - The data bar rule settings.+ * @param {object} config - The data bar rule settings.* @param {IValueConfig} config.min - The minimum value for the data bar.* @param {IValueConfig} config.max - The maximum value for the data bar.* @param {boolean} [config.isGradient] - Whether the data bar is gradient.@@ -1606,14 +1599,7 @@ export class FConditionalFormattingBuilder {/*** Set data bar rule.- * @param {{- * min: IValueConfig;- * max: IValueConfig;- * isGradient?: boolean;- * positiveColor: string;- * nativeColor: string;- * isShowValue?: boolean;- * }} config - The data bar rule settings.+ * @param {object} config - The data bar rule settings.* @param {IValueConfig} config.min - The minimum value for the data bar.* @param {IValueConfig} config.max - The maximum value for the data bar.* @param {boolean} [config.isGradient] - Whether the data bar is gradient.diff --git a/packages/sheets-drawing/src/facade/f-over-grid-image.ts b/packages/sheets-drawing/src/facade/f-over-grid-image.tsindex 93388af853..2589166b0b 100644--- a/packages/sheets-drawing/src/facade/f-over-grid-image.ts+++ b/packages/sheets-drawing/src/facade/f-over-grid-image.ts@@ -67,8 +67,7 @@ function convertSheetImageToFOverGridImage(sheetImage: ISheetImage, skeleton: Sp/*** Convert the FOverGridImage to a ISheetImage* @param {IFOverGridImage} fOverGridImage The FOverGridImage- * @param {ISheetSelectionRenderService} selectionRenderService The selection render service- * @param {SheetSkeletonManagerService} sheetSkeletonManagerService The skeleton manager service+ * @param {SheetSkeletonService} sheetSkeletonService The sheet skeleton service* @returns {ISheetImage} The ISheetImage {@link ISheetImage}*/function convertFOverGridImageToSheetImage(fOverGridImage: IFOverGridImage, sheetSkeletonService: SheetSkeletonService): ISheetImage {@@ -222,6 +221,12 @@ export class FOverGridImageBuilder {return this;}+ /**+ * Set the source of the image. The source type defaults to URL.+ * @param {string} source - The source of the image+ * @returns {FOverGridImageBuilder} The `FOverGridImageBuilder` for chaining+ */+ setSource(source: string): FOverGridImageBuilder;/*** Set the source of the image.* @param {string} source - The source of the image@@ -242,7 +247,6 @@ export class FOverGridImageBuilder {* fWorksheet.insertImages([image]);* ```*/- setSource(source: string): FOverGridImageBuilder;setSource(source: string, sourceType?: ImageSourceType): FOverGridImageBuilder;setSource(source: string, sourceType?: ImageSourceType): FOverGridImageBuilder {const sourceTypeVal = sourceType ?? ImageSourceType.URL;diff --git a/packages/sheets-thread-comment/src/facade/f-thread-comment.ts b/packages/sheets-thread-comment/src/facade/f-thread-comment.tsindex 9e11a1f939..0eeae4f5f7 100644--- a/packages/sheets-thread-comment/src/facade/f-thread-comment.ts+++ b/packages/sheets-thread-comment/src/facade/f-thread-comment.ts@@ -422,7 +422,8 @@ export class FThreadComment {}/**- * @deprecated use `getRichText` as instead+ * @deprecated Use `getRichText` instead.+ * @returns {IDocumentBody} The comment content.*/getContent(): IDocumentBody {return this._thread.text;@@ -474,14 +475,17 @@ export class FThreadComment {}/**- * @deprecated use `deleteAsync` as instead.+ * @deprecated Use `deleteAsync` instead.+ * @returns {Promise<boolean>} Whether the comment is deleted successfully.*/delete(): Promise<boolean> {return this.deleteAsync();}/**- * @deprecated use `updateAsync` as instead+ * @deprecated Use `updateAsync` instead.+ * @param {IDocumentBody} content The new content of the comment.+ * @returns {Promise<boolean>} Whether the comment is updated successfully.*/async update(content: IDocumentBody): Promise<boolean> {return this.updateAsync(content);@@ -535,7 +539,9 @@ export class FThreadComment {}/**- * @deprecated use `resolveAsync` as instead+ * @deprecated Use `resolveAsync` instead.+ * @param {boolean} [resolved] Whether the comment is resolved.+ * @returns {Promise<boolean>} Set the comment to resolved or not operation result.*/resolve(resolved?: boolean): Promise<boolean> {return this.resolveAsync(resolved);diff --git a/packages/sheets-thread-comment/src/facade/f-univer.ts b/packages/sheets-thread-comment/src/facade/f-univer.tsindex 807d073068..c965e0badc 100644--- a/packages/sheets-thread-comment/src/facade/f-univer.ts+++ b/packages/sheets-thread-comment/src/facade/f-univer.ts@@ -310,6 +310,7 @@ export class FUniverSheetsThreadCommentMixin extends FUniver implements IFUniver/*** @ignore+ * @returns {FTheadCommentBuilder} The thread comment builder.*/override newTheadComment(comment?: IThreadComment): FTheadCommentBuilder {return new FTheadCommentBuilder(comment);diff --git a/packages/sheets-thread-comment/src/facade/f-workbook.ts b/packages/sheets-thread-comment/src/facade/f-workbook.tsindex 2b4a2adb82..059bc4d83f 100644--- a/packages/sheets-thread-comment/src/facade/f-workbook.ts+++ b/packages/sheets-thread-comment/src/facade/f-workbook.ts@@ -121,6 +121,7 @@ export class FWorkbookSheetsThreadCommentMixin extends FWorkbook implements IFWo/*** @param callback+ * @returns {IDisposable} A disposable used to remove the listener.* @deprecated*/override onThreadCommentChange(callback: (commentUpdate: CommentUpdate) => void | false): IDisposable {@@ -131,6 +132,7 @@ export class FWorkbookSheetsThreadCommentMixin extends FWorkbook implements IFWo/*** @param callback+ * @returns {IDisposable} A disposable used to remove the listener.* @deprecated*/override onBeforeAddThreadComment(callback: (params: IAddCommentCommandParams, options: IExecutionOptions | undefined) => void | false): IDisposable {@@ -149,6 +151,7 @@ export class FWorkbookSheetsThreadCommentMixin extends FWorkbook implements IFWo/*** @param callback+ * @returns {IDisposable} A disposable used to remove the listener.* @deprecated*/override onBeforeUpdateThreadComment(callback: (params: IUpdateCommentCommandParams, options: IExecutionOptions | undefined) => void | false): IDisposable {@@ -167,6 +170,7 @@ export class FWorkbookSheetsThreadCommentMixin extends FWorkbook implements IFWo/*** @param callback+ * @returns {IDisposable} A disposable used to remove the listener.* @deprecated*/override onBeforeDeleteThreadComment(callback: (params: IDeleteCommentCommandParams, options: IExecutionOptions | undefined) => void | false): IDisposable {diff --git a/packages/sheets-thread-comment/src/facade/f-worksheet.ts b/packages/sheets-thread-comment/src/facade/f-worksheet.tsindex 5f056c86da..4badae5652 100644--- a/packages/sheets-thread-comment/src/facade/f-worksheet.ts+++ b/packages/sheets-thread-comment/src/facade/f-worksheet.ts@@ -108,6 +108,7 @@ export class FWorksheetCommentMixin extends FWorksheet implements IFWorksheetCom/*** Subscribe to comment events.* @param callback Callback function, param contains comment info and target cell.+ * @returns {IDisposable} A disposable used to remove the listener.*/onCommented(callback: (params: IAddCommentCommandParams) => void): IDisposable {const commandService = this._injector.get(ICommandService);diff --git a/packages/sheets/src/facade/f-workbook.ts b/packages/sheets/src/facade/f-workbook.tsindex b6a9cc71d6..ad3df1927f 100644--- a/packages/sheets/src/facade/f-workbook.ts+++ b/packages/sheets/src/facade/f-workbook.ts@@ -146,6 +146,7 @@ export class FWorkbook extends FBaseInitialable {/*** Set the name of the workbook.* @param {string} name The new name of the workbook.+ * @returns {FWorkbook} The current FWorkbook instance for chaining.* @example* ```ts* // The code below sets the name of the workbook@@ -887,7 +888,6 @@ export class FWorkbook extends FBaseInitialable {/*** Insert a defined name by builder param.* @param {ISetDefinedNameMutationParam} param The param to insert the defined name- * @returns {void}* @example* ```ts* // The code below inserts a defined name by builder param@@ -907,7 +907,6 @@ export class FWorkbook extends FBaseInitialable {/*** Update the defined name with the given name.* @param {ISetDefinedNameMutationParam} param The param to insert the defined name- * @returns {void}* @example* ```ts* // The code below updates the defined name with the given name@@ -990,7 +989,6 @@ export class FWorkbook extends FBaseInitialable {/*** Register a custom range theme style.* @param {RangeThemeStyle} rangeThemeStyle The range theme style to register- * @returns {void}* @example* ```ts* const fWorkbook = univerAPI.getActiveWorkbook();@@ -1014,7 +1012,6 @@ export class FWorkbook extends FBaseInitialable {/*** Unregister a custom range theme style.* @param {string} themeName The name of the theme to unregister- * @returns {void}* @example* ```ts* const fWorkbook = univerAPI.getActiveWorkbook();diff --git a/packages/sheets/src/facade/permission/f-range-permission.ts b/packages/sheets/src/facade/permission/f-range-permission.tsindex cbd387a709..93f45e5680 100644--- a/packages/sheets/src/facade/permission/f-range-permission.ts+++ b/packages/sheets/src/facade/permission/f-range-permission.ts@@ -199,6 +199,8 @@ export class FRangePermission extends FBase {/*** List all protection rules that intersect with the current range.+ * @param {object} [options] Options for listing protection rules.+ * @param {boolean} [options.ignoreCollaborators] Whether to skip fetching collaborators for performance.* @returns {Promise<FRangeProtectionRule[]>} Array of protection rules.* @example* ```tsdiff --git a/packages/sheets/src/facade/permission/f-worksheet-permission.ts b/packages/sheets/src/facade/permission/f-worksheet-permission.tsindex 55a4303c92..743becdfc9 100644--- a/packages/sheets/src/facade/permission/f-worksheet-permission.ts+++ b/packages/sheets/src/facade/permission/f-worksheet-permission.ts@@ -768,6 +768,8 @@ export class FWorksheetPermission extends FBase {/*** List all range protection rules for the worksheet.+ * @param {object} [options] Options for listing range protection rules.+ * @param {boolean} [options.ignoreCollaborators] Whether to skip fetching collaborators for performance.* @returns {Promise<FRangeProtectionRule[]>} Array of protection rules.* @example* ```tsdiff --git a/packages/sheets/src/facade/permission/util.ts b/packages/sheets/src/facade/permission/util.tsindex a2aec985cb..3b925e6f79 100644--- a/packages/sheets/src/facade/permission/util.ts+++ b/packages/sheets/src/facade/permission/util.ts@@ -50,6 +50,9 @@ export function determineScope(editState: EditStateEnum, viewState: ViewStateEnu/*** Check if there are no range protection rules for the given unit and subunit when removing a range protection rule.* If there are no rules left, also remove the associated worksheet protection and update the permission points accordingly.+ * @param {Injector} injector The injector used to resolve permission services.+ * @param {string} unitId The workbook unit id.+ * @param {string} subUnitId The worksheet subunit id.*/export function handleWorksheetRangePermissionIsEmpty(injector: Injector, unitId: string, subUnitId: string): void {const rangeProtectionRuleModel = injector.get(RangeProtectionRuleModel);@@ -72,6 +75,14 @@ export function handleWorksheetRangePermissionIsEmpty(injector: Injector, unitId/*** Get the list of range protection rules for a specific worksheet or range, and convert them to FRangeProtectionRule instances.+ * @param {Injector} injector The injector used to resolve permission services.+ * @param {string} unitId The workbook unit id.+ * @param {string} subUnitId The worksheet subunit id.+ * @param {object} options Options for listing range protection rules.+ * @param {FWorksheet} options.worksheet The worksheet facade used to convert ranges.+ * @param {FRange} [options.specificRange] Optional range used to filter rules.+ * @param {boolean} [options.ignoreCollaborators] Whether to skip fetching collaborators for performance.+ * @returns {Promise<FRangeProtectionRule[]>} The range protection rules.*/export async function getListRangeProtectionRules(injector: Injector,diff --git a/packages/ui/src/facade/f-menu-builder.ts b/packages/ui/src/facade/f-menu-builder.tsindex 17cb6164af..670f58c027 100644--- a/packages/ui/src/facade/f-menu-builder.ts+++ b/packages/ui/src/facade/f-menu-builder.ts@@ -192,6 +192,7 @@ export class FMenu extends FMenuBase {/*** @ignore+ * @returns The generated menu schema.*/__getSchema(): { [key: string]: MenuSchemaType } {this._commandToRegister.forEach((command, id) => {@@ -326,6 +327,7 @@ export class FSubmenu extends FMenuBase {/*** @ignore+ * @returns The generated submenu schema.*/__getSchema(): { [key: string]: MenuSchemaType } {const schema: { [key: string]: MenuSchemaType } = {};