Skip to content

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.

fix(facade): clarify API contracts (#7675)

白熱a014cdff4fd8
diff --git a/packages/core/src/facade/f-blob.ts b/packages/core/src/facade/f-blob.ts
index 1af1a00693..85df358233 100644
--- a/packages/core/src/facade/f-blob.ts
+++ b/packages/core/src/facade/f-blob.ts
@@ -25,7 +25,7 @@ export interface IFBlobSource {
getBlob(): FBlob;
/**
- * Return the data inside this object as a blob converted to the specified content type.
+ * Returns a copy labeled with the specified MIME type. The data bytes are not converted or re-encoded.
* @param contentType the content type refer to https://developer.mozilla.org/en-US/docs/Web/HTTP/MIME_types/Common_types
*/
getAs(contentType: string): FBlob;
@@ -57,9 +57,9 @@ export class FBlob extends FBase {
}
/**
- * Return the data inside this object as a blob converted to the specified content type.
+ * Returns a copy labeled with the specified MIME type. The data bytes are not converted or re-encoded.
* @param contentType the content type refer to https://developer.mozilla.org/en-US/docs/Web/HTTP/MIME_types/Common_types
- * @returns a new blob by converting the current blob to the specified content type
+ * @returns {FBlob} A new facade containing the same data with the specified MIME type.
* @example
* ```ts
* const blob = univerAPI.newBlob();
@@ -75,7 +75,7 @@ export class FBlob extends FBase {
/**
* Get the blob as a string.
- * @returns
+ * @returns {Promise<string>} A promise resolving to decoded text; an unset blob returns an empty string.
* @example
* ```ts
* const blob = univerAPI.newBlob();
@@ -86,8 +86,8 @@ export class FBlob extends FBase {
getDataAsString(): Promise<string>;
/**
* Get the blob as a string.
- * @param charset the charset
- * @returns the blob content as a string
+ * @param {string} [charset] TextDecoder encoding label. Defaults to UTF-8.
+ * @returns {Promise<string>} A promise resolving to decoded text; an unset blob returns an empty string.
* @example
* ```ts
* const blob = univerAPI.newBlob();
@@ -116,10 +116,10 @@ export class FBlob extends FBase {
/**
* Gets the data stored in this blob.
- * @returns the blob content as a byte array
+ * @returns {Promise<Uint8Array>} A promise resolving to the bytes; rejects if no blob data is set.
* @example
* ```ts
- * const blob = univerAPI.newBlob();
+ * const blob = univerAPI.newBlob().setDataFromString('Hello, World!');
* const bytes = await blob.getBytes();
* console.log(bytes);
* ```
@@ -161,7 +161,7 @@ export class FBlob extends FBase {
/**
* Sets the data stored in this blob.
* @param data a string
- * @param contentType the content type refer to https://developer.mozilla.org/en-US/docs/Web/HTTP/MIME_types/Common_types
+ * @param [contentType] the content type refer to https://developer.mozilla.org/en-US/docs/Web/HTTP/MIME_types/Common_types
* @returns the blob object
* @example
* ```ts
@@ -179,7 +179,7 @@ export class FBlob extends FBase {
/**
* Gets the content type of the data stored in this blob.
- * @returns the content type
+ * @returns {string | undefined} The MIME type, or `undefined` if no blob data is set.
* @example
* ```ts
* const blob = univerAPI.newBlob();
@@ -192,7 +192,7 @@ export class FBlob extends FBase {
}
/**
- * Sets the content type of the data stored in this blob.
+ * Sets the MIME type without converting or re-encoding the data bytes. Has no effect when no blob data is set.
* @param contentType the content type refer to https://developer.mozilla.org/en-US/docs/Web/HTTP/MIME_types/Common_types
* @returns the blob object
* @example
diff --git a/packages/core/src/facade/f-enum.ts b/packages/core/src/facade/f-enum.ts
index cbb476f1cf..364ed514b0 100644
--- a/packages/core/src/facade/f-enum.ts
+++ b/packages/core/src/facade/f-enum.ts
@@ -64,6 +64,10 @@ export class FEnum {
*/
static _instance: FEnum | null;
+ /**
+ * Returns the shared registry of Facade enum values.
+ * @returns {FEnum} The registry also exposed by `univerAPI.Enum`.
+ */
static get(): FEnum {
if (this._instance) {
return this._instance;
diff --git a/packages/core/src/facade/f-event-registry.ts b/packages/core/src/facade/f-event-registry.ts
index d8f3212bee..168f9e4756 100644
--- a/packages/core/src/facade/f-event-registry.ts
+++ b/packages/core/src/facade/f-event-registry.ts
@@ -32,6 +32,13 @@ export class FEventRegistry {
return this._eventRegistry.get(event)!;
}
+ /**
+ * Registers a factory for the underlying subscription that produces an event.
+ * The factory starts when the event has listeners; its subscription is disposed when the last listener is removed.
+ * @param {string} event The event name.
+ * @param {() => IDisposable | Subscription} handler Creates the underlying event subscription.
+ * @returns {IDisposable} Unregisters the factory and disposes its active subscription.
+ */
registerEventHandler(event: string, handler: () => IDisposable | Subscription): IDisposable {
const current = this._eventHandlerMap.get(event);
if (current) {
@@ -51,6 +58,11 @@ export class FEventRegistry {
});
}
+ /**
+ * Removes one event listener and stops underlying subscriptions when no listeners remain.
+ * @param {T} event The event name.
+ * @param {(params: IEventParamConfig[T]) => void} callback The previously registered callback.
+ */
removeEvent<T extends keyof IEventParamConfig>(event: T, callback: (params: IEventParamConfig[T]) => void): void {
const map = this._ensureEventRegistry(event);
map.delete(callback);
@@ -78,9 +90,9 @@ export class FEventRegistry {
/**
* Add an event listener
- * @param {string} event key of event
- * @param {(params: IEventParamConfig[typeof event]) => void} callback callback when event triggered
- * @returns {Disposable} The Disposable instance, for remove the listener
+ * @param {T} event key of event
+ * @param {(params: IEventParamConfig[T]) => void} callback callback when event triggered
+ * @returns {IDisposable} A disposable that removes the event listener.
* @example
* ```ts
* univerAPI.addEvent(univerAPI.Event.LifeCycleChanged, (params) => {
@@ -97,9 +109,9 @@ export class FEventRegistry {
/**
* Fire an event, used in internal only.
- * @param {string} event key of event
- * @param {any} params params of event
- * @returns {boolean} should cancel
+ * @param {T} event key of event
+ * @param {IEventParamConfig[T]} params params of event
+ * @returns {boolean | undefined} The event's `cancel` value after listeners run; `undefined` if it was not set.
* @example
* ```ts
* this.fireEvent(univerAPI.Event.LifeCycleChanged, params);
diff --git a/packages/core/src/facade/f-event.ts b/packages/core/src/facade/f-event.ts
index 134e8c4bab..ec118be26c 100644
--- a/packages/core/src/facade/f-event.ts
+++ b/packages/core/src/facade/f-event.ts
@@ -98,6 +98,10 @@ export class FEventName {
*/
static _instance: FEventName | null;
+ /**
+ * Returns the shared registry of Facade event names.
+ * @returns {FEventName} The registry also exposed by `univerAPI.Event`.
+ */
static get(): FEventName {
if (this._instance) {
return this._instance;
diff --git a/packages/core/src/facade/f-univer.ts b/packages/core/src/facade/f-univer.ts
index d972c86bd9..643d9058b0 100644
--- a/packages/core/src/facade/f-univer.ts
+++ b/packages/core/src/facade/f-univer.ts
@@ -73,7 +73,7 @@ type Initializers = Array<(injector: Injector) => void>;
*/
export class FUniver extends Disposable {
/**
- * Create an FUniver instance, if the injector is not provided, it will create a new Univer instance.
+ * Creates a Facade API instance for an existing Univer instance or its injector.
* @static
* @param {Univer | Injector} wrapped - The Univer instance or injector instance.
* @returns {FUniver} - The FUniver instance.
@@ -304,8 +304,8 @@ export class FUniver extends Disposable {
}
/**
- * Dispose the UniverSheet by the `unitId`. The UniverSheet would be unload from the application.
- * @param unitId The unit id of the UniverSheet.
+ * Disposes the document, workbook, or other Univer unit identified by `unitId`, unloading it from the application.
+ * @param unitId The ID of the unit to dispose.
* @returns Whether the Univer instance is disposed successfully.
*
* @example
@@ -525,9 +525,9 @@ export class FUniver extends Disposable {
/**
* Execute a command with the given id and parameters.
* @param id Identifier of the command.
- * @param params Parameters of this execution.
- * @param options Options of this execution.
- * @returns The result of the execution. It is a boolean value by default which indicates the command is executed.
+ * @param [params] Parameters of this execution.
+ * @param [options] Options of this execution.
+ * @returns {Promise<R>} The result of the execution. It is a boolean value by default which indicates the command is executed.
*
* @example
* ```ts
@@ -548,8 +548,8 @@ export class FUniver extends Disposable {
/**
* Execute a command with the given id and parameters synchronously.
* @param id Identifier of the command.
- * @param params Parameters of this execution.
- * @param options Options of this execution.
+ * @param [params] Parameters of this execution.
+ * @param [options] Options of this execution.
* @returns The result of the execution. It is a boolean value by default which indicates the command is executed.
*
* @example
@@ -568,23 +568,32 @@ export class FUniver extends Disposable {
return this._commandService.syncExecuteCommand(id, params, options);
}
+ /**
+ * Enums exposed by the registered Facade extensions.
+ */
get Enum(): FEnum {
return FEnum.get();
}
+ /**
+ * Event names to use with `addEvent`.
+ */
get Event(): FEventName {
return FEventName.get();
}
+ /**
+ * Utility functions exposed by the registered Facade extensions.
+ */
get Util(): FUtil {
return FUtil.get();
}
/**
* Add an event listener
- * @param {string} event key of event
- * @param {(params: IEventParamConfig[typeof event]) => void} callback callback when event triggered
- * @returns {Disposable} The Disposable instance, for remove the listener
+ * @param {T} event key of event
+ * @param {(params: IEventParamConfig[T]) => void} callback callback when event triggered
+ * @returns {IDisposable} A disposable that removes the event listener.
* @example
* ```ts
* // Add life cycle changed event listener
@@ -603,9 +612,9 @@ export class FUniver extends Disposable {
/**
* Fire an event, used in internal only.
- * @param {string} event key of event
- * @param {any} params params of event
- * @returns {boolean} should cancel
+ * @param {T} event key of event
+ * @param {IEventParamConfig[T]} params params of event
+ * @returns {boolean | undefined} The event's `cancel` value after listeners run; `undefined` if it was not set.
* @example
* ```ts
* this.fireEvent(univerAPI.Event.LifeCycleChanged, params);
@@ -615,6 +624,14 @@ export class FUniver extends Disposable {
return this._eventRegistry.fireEvent(event, params);
}
+ /**
+ * Gets the facade for reading the current user.
+ * @returns {FUserManager} The user manager facade.
+ * @example
+ * ```ts
+ * const user = univerAPI.getUserManager().getCurrentUser();
+ * ```
+ */
getUserManager(): FUserManager {
return this._injector.createInstance(FUserManager);
}
@@ -680,7 +697,7 @@ export class FUniver extends Disposable {
* This is an advanced document-model API. Application and agent code should normally use
* `newRichText().paragraph({ ... })`.
*
- * @param {IParagraphStyle} style The paragraph style
+ * @param {IParagraphStyle} [style] The paragraph style
* @returns {ParagraphStyleBuilder} The new paragraph style instance
* @advanced
*/
@@ -690,7 +707,7 @@ export class FUniver extends Disposable {
/**
* Create a new paragraph style value.
- * @param {IParagraphStyle} style - The paragraph style
+ * @param {IParagraphStyle} [style] - The paragraph style
* @returns {ParagraphStyleValue} The new paragraph style value instance
* @example
* ```ts
@@ -703,7 +720,7 @@ export class FUniver extends Disposable {
/**
* Create a new text style.
- * @param {ITextStyle} style - The text style
+ * @param {ITextStyle} [style] - The text style
* @returns {TextStyleBuilder} The new text style instance
* @example
* ```ts
@@ -716,7 +733,7 @@ export class FUniver extends Disposable {
/**
* Create a new text style value.
- * @param {ITextStyle} style - The text style
+ * @param {ITextStyle} [style] - The text style
* @returns {TextStyleValue} The new text style value instance
* @example
* ```ts
@@ -729,7 +746,7 @@ export class FUniver extends Disposable {
/**
* Create a new text decoration.
- * @param {ITextDecoration} decoration - The text decoration
+ * @param {ITextDecoration} [decoration] - The text decoration
* @returns {TextDecorationBuilder} The new text decoration instance
* @example
* ```ts
diff --git a/packages/docs-thread-comment/src/facade/f-document-text-range.ts b/packages/docs-thread-comment/src/facade/f-document-text-range.ts
index e00de8eba9..978b0d9345 100644
--- a/packages/docs-thread-comment/src/facade/f-document-text-range.ts
+++ b/packages/docs-thread-comment/src/facade/f-document-text-range.ts
@@ -30,8 +30,8 @@ export interface IFDocumentTextRangeThreadCommentMixin {
/**
* Creates a comment on this text range.
* @param content Plain text or a Univer document body for rich comment content.
- * @param options Optional stable IDs, author, attachments, and creation time.
- * @returns `true` when the create command succeeds; otherwise, `false`.
+ * @param [options] Optional stable IDs, author, attachments, and creation time.
+ * @returns {Promise<boolean>} `true` when the create command succeeds; otherwise, `false`.
* @throws {TypeError} If the content is empty.
* @example
* ```ts
@@ -56,7 +56,7 @@ export interface IFDocumentTextRangeThreadCommentMixin {
getComments(): ThreadComment.IFacadeThreadCommentInfo[];
/**
* Synchronizes known document threads and returns comments whose decorations overlap this text range.
- * @returns A promise resolving to the synchronized matching comment threads.
+ * @returns {Promise<ThreadComment.IFacadeThreadCommentInfo[]>} A promise resolving to the synchronized matching comment threads.
* @example
* ```ts
* const range = univerAPI.getActiveDocument()?.getTextRange(0, 12);
diff --git a/packages/docs/src/facade/f-document-section.ts b/packages/docs/src/facade/f-document-section.ts
index 7f1228973f..100eb63e58 100644
--- a/packages/docs/src/facade/f-document-section.ts
+++ b/packages/docs/src/facade/f-document-section.ts
@@ -214,6 +214,10 @@ export class FDocumentSection {
* Sets equal or explicitly sized columns for this traditional section.
* Use `columnCount = 1` to restore normal single-column layout.
* `gap` and `widths` are in 96-DPI layout pixels.
+ * @param {number} columnCount Positive integer column count.
+ * @param {IFDocumentSectionColumnOptions} [options] Column widths, gap (default 18 pixels), and separator (default none).
+ * @returns {boolean} Whether the section update succeeded.
+ * @throws {RangeError} If column dimensions or the separator are invalid, or columns exceed the available width.
* @example
* ```ts
* const fDocument = univerAPI.getActiveDocument();
@@ -258,6 +262,10 @@ export class FDocumentSection {
/**
* Sets explicit OOXML-compatible column width and trailing-space values in 96-DPI layout pixels.
+ * @param {ISectionColumnProperties[]} columns Explicit widths and trailing spaces; an empty array restores a single column.
+ * @param {ColumnSeparatorType} [separator] Column separator style. Defaults to `ColumnSeparatorType.NONE`.
+ * @returns {boolean} Whether the section update succeeded.
+ * @throws {RangeError} If column dimensions or the separator are invalid, or columns exceed the available width.
* @example
* ```ts
* const fDocument = univerAPI.getActiveDocument();
@@ -448,6 +456,8 @@ export class FDocumentSection {
/**
* Ensures a header segment linked specifically to this section.
+ * @param {SectionHeaderFooterVariant} [variant] The `'default'`, `'first'`, or `'even'` variant. Defaults to `'default'`.
+ * @returns {string} The existing or newly created section-specific segment ID.
* @example
* ```ts
* const fDocument = univerAPI.getActiveDocument();
@@ -465,6 +475,8 @@ export class FDocumentSection {
/**
* Ensures a footer segment linked specifically to this section.
+ * @param {SectionHeaderFooterVariant} [variant] The `'default'`, `'first'`, or `'even'` variant. Defaults to `'default'`.
+ * @returns {string} The existing or newly created section-specific segment ID.
* @example
* ```ts
* const fDocument = univerAPI.getActiveDocument();
@@ -482,6 +494,8 @@ export class FDocumentSection {
/**
* Returns the effective header id after resolving links to previous sections.
+ * @param {SectionHeaderFooterVariant} [variant] The `'default'`, `'first'`, or `'even'` variant. Defaults to `'default'`.
+ * @returns {string | null} The effective segment ID, or `null` if no segment is available.
* @example
* ```ts
* const fDocument = univerAPI.getActiveDocument();
@@ -494,6 +508,8 @@ export class FDocumentSection {
/**
* Returns the effective footer id after resolving links to previous sections.
+ * @param {SectionHeaderFooterVariant} [variant] The `'default'`, `'first'`, or `'even'` variant. Defaults to `'default'`.
+ * @returns {string | null} The effective segment ID, or `null` if no segment is available.
* @example
* ```ts
* const fDocument = univerAPI.getActiveDocument();
@@ -506,6 +522,8 @@ export class FDocumentSection {
/**
* Whether this header variant inherits the previous section's reference.
+ * @param {SectionHeaderFooterVariant} [variant] The `'default'`, `'first'`, or `'even'` variant. Defaults to `'default'`.
+ * @returns {boolean} Whether this variant inherits from the previous section.
* @example
* ```ts
* const fDocument = univerAPI.getActiveDocument();
@@ -518,6 +536,8 @@ export class FDocumentSection {
/**
* Whether this footer variant inherits the previous section's reference.
+ * @param {SectionHeaderFooterVariant} [variant] The `'default'`, `'first'`, or `'even'` variant. Defaults to `'default'`.
+ * @returns {boolean} Whether this variant inherits from the previous section.
* @example
* ```ts
* const fDocument = univerAPI.getActiveDocument();
@@ -530,6 +550,9 @@ export class FDocumentSection {
/**
* Links or unlinks this header variant. Unlinking clones the inherited header.
+ * @param {boolean} linkedToPrevious Whether to inherit the previous section's header/footer.
+ * @param {SectionHeaderFooterVariant} [variant] The `'default'`, `'first'`, or `'even'` variant. Defaults to `'default'`.
+ * @returns {boolean} Whether the link update succeeded.
* @example
* ```ts
* const fDocument = univerAPI.getActiveDocument();
@@ -544,6 +567,9 @@ export class FDocumentSection {
/**
* Links or unlinks this footer variant. Unlinking clones the inherited footer.
+ * @param {boolean} linkedToPrevious Whether to inherit the previous section's header/footer.
+ * @param {SectionHeaderFooterVariant} [variant] The `'default'`, `'first'`, or `'even'` variant. Defaults to `'default'`.
+ * @returns {boolean} Whether the link update succeeded.
* @example
* ```ts
* const fDocument = univerAPI.getActiveDocument();
@@ -559,6 +585,8 @@ export class FDocumentSection {
/**
* Updates header/footer switches and margins on this section break.
* `marginHeader` and `marginFooter` are in 96-DPI layout pixels.
+ * @param {IHeaderFooterProps} options Header/footer switches and margins to update. Omitted properties are preserved.
+ * @returns {boolean} Whether the update command succeeded.
* @example
* ```ts
* const fDocument = univerAPI.getActiveDocument();
diff --git a/packages/docs/src/facade/f-document-text-range.ts b/packages/docs/src/facade/f-document-text-range.ts
index 04ecb64c6c..ec8af2817b 100644
--- a/packages/docs/src/facade/f-document-text-range.ts
+++ b/packages/docs/src/facade/f-document-text-range.ts
@@ -166,6 +166,8 @@ export class FDocumentTextRange extends FBaseInitialable {
* Existing text-run splitting, merging, and normalization are handled by
* the document mutation pipeline.
* `style.fs` is a font size in points (pt), not CSS pixels.
+ * @param {ITextStyle} style Text-style properties to merge into the range.
+ * @returns {boolean} Whether the style update succeeded; `false` for an empty range.
* @example
* ```ts
* const fDocument = univerAPI.getActiveDocument();
@@ -196,6 +198,8 @@ export class FDocumentTextRange extends FBaseInitialable {
/**
* Replaces the range with plain text while preserving document mutation semantics.
+ * @param {string} text Replacement plain text. An empty string deletes the range.
+ * @returns {boolean} Whether the replacement succeeded.
* @example
* ```ts
* const fDocument = univerAPI.getActiveDocument();
diff --git a/packages/docs/src/facade/f-document.ts b/packages/docs/src/facade/f-document.ts
index d09765d950..47a1d0914f 100644
--- a/packages/docs/src/facade/f-document.ts
+++ b/packages/docs/src/facade/f-document.ts
@@ -101,7 +101,7 @@ export class FDocument extends FBaseInitialable {
/**
* Get the document data model of the document.
- * @param {string} segmentId The segment id used to get the header/footer data model. Defaults to an empty string for the document data model of the document.
+ * @param {string} [segmentId] The segment id used to get the header/footer data model. Defaults to an empty string for the document data model of the document.
* @returns {DocumentDataModel} The document data model.
* @example
* ```typescript
@@ -149,7 +149,7 @@ export class FDocument extends FBaseInitialable {
* Get the document body or header/footer body by the segment id.
* The main body has an empty segment id.
* The header and footer body have their respective segment ids.
- * @param {string} segmentId The segment id of the body. Defaults to an empty string for the main body.
+ * @param {string} [segmentId] The segment id of the body. Defaults to an empty string for the main body.
* @returns {IDocumentBody} The document body.
* @example
* ```typescript
@@ -168,6 +168,7 @@ export class FDocument extends FBaseInitialable {
return body;
}
+ /** Releases this facade's resources. Use `univerAPI.disposeUnit()` to unload the owning unit. */
override dispose(): void {
super.dispose();
}
@@ -377,7 +378,7 @@ export class FDocument extends FBaseInitialable {
/**
* Ensure the page header segment exists and return its segment id.
- * @param {number} pageIndex The zero-based page index. Defaults to the first page.
+ * @param {number} [pageIndex] The zero-based page index. Defaults to the first page.
* @returns {string} The header segment id.
* @example
* ```ts
@@ -392,7 +393,7 @@ export class FDocument extends FBaseInitialable {
/**
* Ensure the page footer segment exists and return its segment id.
- * @param {number} pageIndex The zero-based page index. Defaults to the first page.
+ * @param {number} [pageIndex] The zero-based page index. Defaults to the first page.
* @returns {string} The footer segment id.
* @example
* ```ts
@@ -409,7 +410,7 @@ export class FDocument extends FBaseInitialable {
* Insert plain text at a document body offset.
* @param {number} index The zero-based insertion offset.
* @param {string} text The plain text to insert.
- * @param {string} segmentId The segment id of the body. Defaults to an empty string for the main body.
+ * @param {string} [segmentId] The segment id of the body. Defaults to an empty string for the main body.
* @returns {boolean} `true` if the edit was applied.
* @example
* ```ts
@@ -457,6 +458,8 @@ export class FDocument extends FBaseInitialable {
* Traditional and Unspecified documents keep the legacy header/footer
* behavior. Modern documents reject this API. `marginHeader` and
* `marginFooter` use 96-DPI layout pixels.
+ * @param {IHeaderFooterProps} options Header/footer switches and margins to update. Omitted properties are preserved.
+ * @returns {boolean} Whether the update command succeeded.
* @example
* ```ts
* const fDocument = univerAPI.getActiveDocument();
@@ -483,7 +486,7 @@ export class FDocument extends FBaseInitialable {
* The end offset is exclusive, and offsets are scoped to the selected body segment.
* @param {number} startOffset The inclusive start offset.
* @param {number} endOffset The exclusive end offset.
- * @param {string} segmentId The header/footer segment id, or an empty string for the main body.
+ * @param {string} [segmentId] The header/footer segment id, or an empty string for the main body.
* @returns {FDocumentTextRange} A fixed text-range facade.
* @example
* ```ts
@@ -516,6 +519,8 @@ export class FDocument extends FBaseInitialable {
/**
* Returns a traditional section by zero-based index, or `null` in modern documents.
+ * @param {number} index Zero-based section index.
+ * @returns {FDocumentSection | null} The matching section, or `null` if none exists or the document is not Traditional.
* @example
* ```ts
* const fDocument = univerAPI.getActiveDocument();
@@ -529,6 +534,8 @@ export class FDocument extends FBaseInitialable {
/**
* Returns the traditional section containing a data-stream offset, or `null` in modern documents.
+ * @param {number} offset Zero-based data-stream offset in the main document body.
+ * @returns {FDocumentSection | null} The matching section, or `null` if none exists or the document is not Traditional.
* @example
* ```ts
* const fDocument = univerAPI.getActiveDocument();
@@ -618,6 +625,8 @@ export class FDocument extends FBaseInitialable {
* In a single-column section, the traditional renderer advances to the next physical page.
* Modern documents must use ColumnGroup. Unspecified documents must resolve
* their flavor first. Both throw `DocsSectionUnsupportedDocumentFlavorError`.
+ * @param {number} offset Zero-based data-stream offset at which to insert the column break.
+ * @returns {boolean} Whether the insertion succeeded.
* @example
* ```ts
* const fDocument = univerAPI.getActiveDocument();
@@ -644,6 +653,10 @@ export class FDocument extends FBaseInitialable {
* Inserts a horizontal rule using the existing paragraph `borderBottom` mechanism.
* The returned paragraph can be inspected or removed with normal paragraph APIs.
* Border width and padding are in points (pt).
+ * @param {number} offset Zero-based insertion offset in the selected body segment.
+ * @param {IParagraphBorder} [border] Bottom border appearance. Defaults to a solid gray 1 pt line with 5 pt padding.
+ * @param {string} [segmentId] Header/footer segment ID, or an empty string for the main body (default).
+ * @returns {FDocumentParagraph | null} The inserted paragraph, or `null` if insertion fails.
* @example
* ```ts
* const fDocument = univerAPI.getActiveDocument();
@@ -686,7 +699,7 @@ export class FDocument extends FBaseInitialable {
/**
* Get all paragraphs in the document body or header/footer body by the segment id.
- * @param {string} segmentId The segment id of the body. Defaults to an empty string for the main body.
+ * @param {string} [segmentId] The segment id of the body. Defaults to an empty string for the main body.
* @returns {FDocumentParagraph[]} An array of paragraph facade instances.
* @example
* ```ts
@@ -707,7 +720,7 @@ export class FDocument extends FBaseInitialable {
/**
* Get a paragraph by its paragraph id and segment id.
* @param {string} paragraphId The paragraph id.
- * @param {string} segmentId The segment id of the body. Defaults to an empty string for the main body.
+ * @param {string} [segmentId] The segment id of the body. Defaults to an empty string for the main body.
* @returns {FDocumentParagraph | null} The paragraph facade instance, or `null` if the paragraph is not found.
* @example
* ```ts
@@ -732,7 +745,7 @@ export class FDocument extends FBaseInitialable {
/**
* Find a paragraph by its text content and segment id.
* @param {string} text The text content to search for.
- * @param {string} segmentId The segment id of the body. Defaults to an empty string for the main body.
+ * @param {string} [segmentId] The segment id of the body. Defaults to an empty string for the main body.
* @returns {FDocumentParagraph | null} The paragraph facade instance, or `null` if the paragraph is not found.
* @example
* ```ts
@@ -787,8 +800,8 @@ export class FDocument extends FBaseInitialable {
/**
* Insert a plain-text paragraph before the paragraph at the given paragraph index.
* @param {number} index The zero-based paragraph insertion index.
- * @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.
+ * @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 inserted paragraph facade instance.
* @example
* ```ts
@@ -829,8 +842,8 @@ 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.
+ * @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
* ```ts
diff --git a/packages/docs/src/facade/f-univer.ts b/packages/docs/src/facade/f-univer.ts
index 072f197c14..51fb01d1c3 100644
--- a/packages/docs/src/facade/f-univer.ts
+++ b/packages/docs/src/facade/f-univer.ts
@@ -26,11 +26,11 @@ export interface IFUniverDocsMixin {
/**
* Create a new document and get the API handler of that document.
* @param {Partial<IDocumentData>} data The snapshot of the document.
- * @param {ICreateUnitOptions} options The options of creating the document.
+ * @param {ICreateUnitOptions} [options] The options of creating the document.
* @returns {FDocument} The document API instance.
* @example
* ```typescript
- * const fDocument = univerAPI.createUniverDoc({ id: 'document-01', title: 'Document1' });
+ * const fDocument = univerAPI.createDocument({ id: 'document-01', title: 'Document1' });
* console.log(fDocument);
* ```
*/
@@ -92,6 +92,5 @@ export class FUniverDocsMixin extends FUniver implements IFUniverDocsMixin {
FUniver.extend(FUniverDocsMixin);
declare module '@univerjs/core/facade' {
- // eslint-disable-next-line ts/naming-convention
interface FUniver extends IFUniverDocsMixin {}
}
diff --git a/packages/engine-formula/src/facade/f-formula.ts b/packages/engine-formula/src/facade/f-formula.ts
index 725b2bfa0f..eede063305 100644
--- a/packages/engine-formula/src/facade/f-formula.ts
+++ b/packages/engine-formula/src/facade/f-formula.ts
@@ -210,6 +210,8 @@ export class FFormula extends FBase {
/**
* Listens for formula results after every affected model has applied them.
+ * @param {(result: ISetFormulaCalculationResultMutation) => void} callback Receives each applied formula result asynchronously.
+ * @returns {IDisposable} A disposable that unsubscribes from future result notifications.
*/
calculationResultApplied(callback: (result: ISetFormulaCalculationResultMutation) => void): IDisposable {
const subscription = this._injector.get(FormulaCalculationSessionService).resultApplied$.subscribe((result) => {
@@ -226,6 +228,8 @@ export class FFormula extends FBase {
/**
* Waits until the latest formula-calculation results have been applied.
+ * @param {number} [timeout] Maximum wait in milliseconds. Omit to wait without an overall timeout.
+ * @returns {Promise<void>} Resolves when the latest calculation results have been applied; rejects if the supplied timeout expires.
*/
onCalculationResultApplied(timeout?: number): Promise<void> {
return this._injector.get(FormulaCalculationSessionService).waitForLatestApplied(timeout);
diff --git a/packages/engine-formula/src/facade/f-univer.ts b/packages/engine-formula/src/facade/f-univer.ts
index 11f176ac27..e6b4678c44 100644
--- a/packages/engine-formula/src/facade/f-univer.ts
+++ b/packages/engine-formula/src/facade/f-univer.ts
@@ -21,6 +21,15 @@ import { FFormula } from './f-formula';
* @ignore
*/
export interface IFUniverEngineFormulaMixin {
+ /**
+ * Gets the formula engine facade for calculation, parsing, and dependency queries.
+ * @returns {FFormula} The formula engine facade.
+ * @example
+ * ```ts
+ * const formula = univerAPI.getFormula();
+ * await formula.onCalculationResultApplied();
+ * ```
+ */
getFormula(): FFormula;
}
@@ -32,6 +41,5 @@ export class FUniverEngineFormulaMixin extends FUniver implements IFUniverEngine
FUniver.extend(FUniverEngineFormulaMixin);
declare module '@univerjs/core/facade' {
- // eslint-disable-next-line ts/naming-convention
interface FUniver extends IFUniverEngineFormulaMixin {}
}
diff --git a/packages/network/src/facade/f-network.ts b/packages/network/src/facade/f-network.ts
index 15aa41d9ec..e543de0aab 100644
--- a/packages/network/src/facade/f-network.ts
+++ b/packages/network/src/facade/f-network.ts
@@ -38,8 +38,8 @@ export class FNetwork extends FBase {
/**
* Send a GET request to the server.
* @param {string} url - The requested URL.
- * @param {IRequestParams} [params] - Query parameters.
- * @returns {Promise<HTTPResponse>} Network response.
+ * @param {IRequestParams} [params] - Request options, including query parameters, headers, and response type.
+ * @returns {Promise<HTTPResponse<T>>} A promise resolving to the HTTP response with a body of type `T`.
*/
get<T>(url: string, params?: IRequestParams): Promise<HTTPResponse<T>> {
return this._httpService.get(url, params) as Promise<HTTPResponse<T>>; ;
@@ -48,8 +48,8 @@ export class FNetwork extends FBase {
/**
* Send a POST request to the server.
* @param {string} url - The requested URL.
- * @param {IPostRequestParams} [params] - Query parameters.
- * @returns {Promise<HTTPResponse>} Network response.
+ * @param {IPostRequestParams} [params] - Request options, including body, query parameters, headers, and response type.
+ * @returns {Promise<HTTPResponse<T>>} A promise resolving to the HTTP response with a body of type `T`.
*/
post<T>(url: string, params?: IPostRequestParams): Promise<HTTPResponse<T>> {
return this._httpService.post(url, params) as Promise<HTTPResponse<T>>; ;
@@ -58,8 +58,8 @@ export class FNetwork extends FBase {
/**
* Send a PUT request to the server.
* @param {string} url - The requested URL
- * @param {IPostRequestParams} [params] - Query parameters
- * @returns {Promise<HTTPResponse>} Network response
+ * @param {IPostRequestParams} [params] - Request options, including body, query parameters, headers, and response type
+ * @returns {Promise<HTTPResponse<T>>} A promise resolving to the HTTP response with a body of type `T`.
*/
put<T>(url: string, params?: IPostRequestParams): Promise<HTTPResponse<T>> {
return this._httpService.put(url, params) as Promise<HTTPResponse<T>>; ;
@@ -68,8 +68,8 @@ export class FNetwork extends FBase {
/**
* Send DELETE request to the server.
* @param {string} url - The requested URL
- * @param {IRequestParams} [params] - Query parameters
- * @returns {Promise<HTTPResponse>} Network response
+ * @param {IRequestParams} [params] - Request options, including query parameters, headers, and response type
+ * @returns {Promise<HTTPResponse<T>>} A promise resolving to the HTTP response with a body of type `T`.
*/
delete<T>(url: string, params?: IRequestParams): Promise<HTTPResponse<T>> {
return this._httpService.delete(url, params) as Promise<HTTPResponse<T>>; ;
@@ -78,8 +78,8 @@ export class FNetwork extends FBase {
/**
* Send PATCH request to the server.
* @param {string} url - The requested URL
- * @param {IPostRequestParams} [params] - Query parameters
- * @returns {Promise<HTTPResponse>} Network response
+ * @param {IPostRequestParams} [params] - Request options, including body, query parameters, headers, and response type
+ * @returns {Promise<HTTPResponse<T>>} A promise resolving to the HTTP response with a body of type `T`.
*/
patch<T>(url: string, params?: IPostRequestParams): Promise<HTTPResponse<T>> {
return this._httpService.patch(url, params) as Promise<HTTPResponse<T>>;
@@ -90,8 +90,8 @@ export class FNetwork extends FBase {
* Univer wraps the stream in an [`Observable`](https://rxjs.dev/guide/observable) which you can call `subscribe` on.
* @param {HTTPRequestMethod} method - HTTP request method
* @param {string} url - The requested URL
- * @param {IPostRequestParams} [params] - params Query parameters
- * @returns {Observable<HTTPEvent>} An observable that emits the network response.
+ * @param {IPostRequestParams} [params] - params Request options, including body, query parameters, headers, and response type
+ * @returns {Observable<HTTPEvent<T>>} An observable of HTTP events with response data of type `T`.
*/
getSSE<T>(
method: HTTPRequestMethod,
diff --git a/packages/sheets-data-validation/src/facade/f-data-validation.ts b/packages/sheets-data-validation/src/facade/f-data-validation.ts
index f814ff312c..c083b05f07 100644
--- a/packages/sheets-data-validation/src/facade/f-data-validation.ts
+++ b/packages/sheets-data-validation/src/facade/f-data-validation.ts
@@ -229,8 +229,8 @@ export class FDataValidation {
}
/**
- * Gets the unit ID of the worksheet
- * @returns {string | undefined} The unit ID of the worksheet
+ * Gets the unit ID of the workbook
+ * @returns {string | undefined} The unit ID of the workbook
* @example
* ```typescript
* const fWorkbook = univerAPI.getActiveWorkbook();
diff --git a/packages/sheets-data-validation/src/facade/f-range.ts b/packages/sheets-data-validation/src/facade/f-range.ts
index 0047d3d775..3719786242 100644
--- a/packages/sheets-data-validation/src/facade/f-range.ts
+++ b/packages/sheets-data-validation/src/facade/f-range.ts
@@ -153,7 +153,7 @@ export interface IFRangeSheetsDataValidationMixin {
getValidatorStatus(): Promise<DataValidationStatus[][]>;
/**
* Get data validation errors for a specific range in current worksheet.
- * @returns A promise that resolves to an array of validation errors in the specified range.
+ * @returns {Promise<IDataValidationError[]>} A promise that resolves to an array of validation errors in the specified range.
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
@@ -305,6 +305,5 @@ export class FRangeSheetsDataValidationMixin extends FRange implements IFRangeSh
FRange.extend(FRangeSheetsDataValidationMixin);
declare module '@univerjs/sheets/facade' {
- // eslint-disable-next-line ts/naming-convention
interface FRange extends IFRangeSheetsDataValidationMixin { }
}
diff --git a/packages/sheets-data-validation/src/facade/f-workbook.ts b/packages/sheets-data-validation/src/facade/f-workbook.ts
index df3edd8709..2b2e17a77e 100644
--- a/packages/sheets-data-validation/src/facade/f-workbook.ts
+++ b/packages/sheets-data-validation/src/facade/f-workbook.ts
@@ -42,7 +42,7 @@ export interface IDataValidationError {
export interface IFWorkbookSheetsDataValidationMixin {
/**
* Get data validation validator status for current workbook.
- * @returns A promise that resolves to a matrix of validator status.
+ * @returns {Promise<Record<string, ObjectMatrix<Nullable<DataValidationStatus>>>>} A promise resolving to an object keyed by sheet ID, with a validation-status matrix for each sheet.
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
@@ -54,11 +54,11 @@ export interface IFWorkbookSheetsDataValidationMixin {
/**
* Get all data validation errors for current workbook.
- * @returns A promise that resolves to an array of validation errors.
+ * @returns {Promise<IDataValidationError[]>} A promise that resolves to an array of validation errors.
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
- * const errors = await fWorkbook.getAllDataValidationError();
+ * const errors = await fWorkbook.getAllDataValidationErrorAsync();
* console.log(errors);
* ```
*/
@@ -182,6 +182,5 @@ export class FWorkbookSheetsDataValidationMixin extends FWorkbook implements IFW
FWorkbook.extend(FWorkbookSheetsDataValidationMixin);
declare module '@univerjs/sheets/facade' {
- // eslint-disable-next-line ts/naming-convention
interface FWorkbook extends IFWorkbookSheetsDataValidationMixin { }
}
diff --git a/packages/sheets-data-validation/src/facade/f-worksheet.ts b/packages/sheets-data-validation/src/facade/f-worksheet.ts
index fe49abf4da..cddc8c72b5 100644
--- a/packages/sheets-data-validation/src/facade/f-worksheet.ts
+++ b/packages/sheets-data-validation/src/facade/f-worksheet.ts
@@ -29,6 +29,7 @@ export interface IFWorksheetDataValidationMixin {
/**
* Get all data validation rules in current sheet.
* @returns {FDataValidation[]} All data validation rules
+ * @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getSheetByName('Sheet1');
@@ -42,6 +43,7 @@ export interface IFWorksheetDataValidationMixin {
/**
* Get data validation validator status for current sheet.
* @returns {Promise<ObjectMatrix<Nullable<DataValidationStatus>>>} matrix of validator status
+ * @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getSheetByName('Sheet1');
@@ -56,6 +58,7 @@ export interface IFWorksheetDataValidationMixin {
* get data validation rule by rule id
* @param ruleId - the rule id
* @returns {Nullable<FDataValidation>} data validation rule
+ * @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getSheetByName('Sheet1');
@@ -68,13 +71,13 @@ export interface IFWorksheetDataValidationMixin {
/**
* Get all data validation errors for current worksheet.
- * @returns A promise that resolves to an array of validation errors.
+ * @returns {Promise<IDataValidationError[]>} A promise that resolves to an array of validation errors.
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getSheetByName('Sheet1');
* if (!fWorksheet) return;
- * const errors = await fWorksheet.getAllDataValidationError();
+ * const errors = await fWorksheet.getAllDataValidationErrorAsync();
* console.log(errors);
* ```
*/
@@ -194,6 +197,5 @@ export class FWorksheetDataValidationMixin extends FWorksheet implements IFWorks
FWorksheet.extend(FWorksheetDataValidationMixin);
declare module '@univerjs/sheets/facade' {
- // eslint-disable-next-line ts/naming-convention
interface FWorksheet extends IFWorksheetDataValidationMixin {}
}
diff --git a/packages/sheets-drawing-ui/src/facade/f-range.ts b/packages/sheets-drawing-ui/src/facade/f-range.ts
index 96df56621a..065bad1dc0 100644
--- a/packages/sheets-drawing-ui/src/facade/f-range.ts
+++ b/packages/sheets-drawing-ui/src/facade/f-range.ts
@@ -40,7 +40,7 @@ export interface IFRangeSheetsDrawingUIMixin {
* Inserts an image into the current cell.
*
* @param {string | File} file File or URL string
- * @returns True if the image is inserted successfully, otherwise false
+ * @returns {Promise<boolean>} True if the image is inserted successfully, otherwise false
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
@@ -161,6 +161,5 @@ export class FRangeSheetsDrawingUIMixin extends FRange implements IFRangeSheetsD
FRange.extend(FRangeSheetsDrawingUIMixin);
declare module '@univerjs/sheets/facade' {
- // eslint-disable-next-line ts/naming-convention
interface FRange extends IFRangeSheetsDrawingUIMixin { }
}
diff --git a/packages/sheets-drawing-ui/src/facade/f-worksheet.ts b/packages/sheets-drawing-ui/src/facade/f-worksheet.ts
index 9338678d33..b96ef13ebb 100644
--- a/packages/sheets-drawing-ui/src/facade/f-worksheet.ts
+++ b/packages/sheets-drawing-ui/src/facade/f-worksheet.ts
@@ -330,7 +330,7 @@ export interface IFWorksheetDrawingUIMixin {
* @param {string} [id] - The float dom id, if not given will be auto generated
* @returns float dom id and dispose function
* @example
- * ```ts
+ * ```tsx
* const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1');
* if (!fWorksheet) return;
*
@@ -729,6 +729,5 @@ export class FWorksheetDrawingUIMixin extends FWorksheet implements IFWorksheetD
FWorksheet.extend(FWorksheetDrawingUIMixin);
declare module '@univerjs/sheets/facade' {
- // eslint-disable-next-line ts/naming-convention
interface FWorksheet extends IFWorksheetDrawingUIMixin { }
}
diff --git a/packages/sheets-drawing/src/facade/f-over-grid-image.ts b/packages/sheets-drawing/src/facade/f-over-grid-image.ts
index 4edba7f954..b789563346 100644
--- a/packages/sheets-drawing/src/facade/f-over-grid-image.ts
+++ b/packages/sheets-drawing/src/facade/f-over-grid-image.ts
@@ -726,16 +726,40 @@ export class FOverGridImageBuilder {
return this;
}
+ /**
+ * Sets the workbook unit ID of the image to build.
+ * @param {string} unitId The target workbook unit ID.
+ * @returns {FOverGridImageBuilder} This builder, for chaining.
+ */
setUnitId(unitId: string): FOverGridImageBuilder {
this._image.unitId = unitId;
return this;
}
+ /**
+ * Sets the worksheet ID of the image to build.
+ * @param {string} subUnitId The target worksheet ID.
+ * @returns {FOverGridImageBuilder} This builder, for chaining.
+ */
setSubUnitId(subUnitId: string): FOverGridImageBuilder {
this._image.subUnitId = subUnitId;
return this;
}
+ /**
+ * Builds image data for insertion or updating; this does not insert the image.
+ * An explicit placement takes precedence over the individual position and size fields.
+ * Without explicit placement, zero width or height is filled from the source image's intrinsic size.
+ * @returns {Promise<ISheetImage>} A promise resolving to the built sheet image data.
+ * @example
+ * ```ts
+ * const sheet = univerAPI.getActiveWorkbook()?.getActiveSheet();
+ * if (sheet) {
+ * const image = await sheet.newOverGridImage().setSource('https://example.com/image.png').buildAsync();
+ * sheet.insertImages([image]);
+ * }
+ * ```
+ */
async buildAsync(): Promise<ISheetImage> {
const sheetSkeletonService = this._sheetSkeletonService;
@@ -1011,7 +1035,7 @@ export class FOverGridImage extends FBase {
* Set the position of the image
* @param {number} row - The row index of the image start position
* @param {number} column - The column index of the image start position
- * @returns {boolean} true if the position is set successfully, otherwise false
+ * @returns {Promise<boolean>} A promise resolving to whether the image update succeeded.
* @example
* ```ts
* // set the position of the image, the start position is F6 cell.
@@ -1019,7 +1043,7 @@ export class FOverGridImage extends FBase {
* const fWorksheet = fWorkbook.getSheetByName('Sheet1');
* if (!fWorksheet) return;
* const image = fWorksheet.getImages()[0];
- * const result = image?.setPositionAsync(5, 5);
+ * const result = await image?.setPositionAsync(5, 5);
* console.log(result);
* ```
*/
@@ -1027,9 +1051,9 @@ export class FOverGridImage extends FBase {
/**
* @param {number} row - The row index of the image start position
* @param {number} column - The column index of the image start position
- * @param {number} rowOffset - The row offset of the image start position, pixel unit
- * @param {number} columnOffset - The column offset of the image start position, pixel unit
- * @returns {boolean} true if the position is set successfully, otherwise false
+ * @param {number} [rowOffset] - The row offset of the image start position, pixel unit
+ * @param {number} [columnOffset] - The column offset of the image start position, pixel unit
+ * @returns {Promise<boolean>} A promise resolving to whether the image update succeeded.
* @example
* ```ts
* // set the position of the image, the start position is F6 cell, and the offset is 10px.
@@ -1037,7 +1061,7 @@ export class FOverGridImage extends FBase {
* const fWorksheet = fWorkbook.getSheetByName('Sheet1');
* if (!fWorksheet) return;
* const image = fWorksheet.getImages()[0];
- * const result = image?.setPositionAsync(5, 5, 10, 10);
+ * const result = await image?.setPositionAsync(5, 5, 10, 10);
* console.log(result);
* ```
*/
@@ -1060,7 +1084,7 @@ export class FOverGridImage extends FBase {
* Set the size of the image
* @param {number} width - The width of the image, pixel unit
* @param {number} height - The height of the image, pixel unit
- * @returns {boolean} true if the size is set successfully, otherwise false
+ * @returns {Promise<boolean>} A promise resolving to whether the image update succeeded.
* @example
* ```ts
* // set the image width 120px and height 50px
@@ -1068,7 +1092,7 @@ export class FOverGridImage extends FBase {
* const fWorksheet = fWorkbook.getSheetByName('Sheet1');
* if (!fWorksheet) return;
* const image = fWorksheet.getImages()[0];
- * const result = image?.setSizeAsync(120, 50);
+ * const result = await image?.setSizeAsync(120, 50);
* console.log(result);
* ```
*/
@@ -1082,10 +1106,10 @@ export class FOverGridImage extends FBase {
/**
* Set the cropping region of the image by defining the top, bottom, left, and right edges, thereby displaying the specific part of the image you want.
- * @param {number} top - The number of pixels to crop from the top of the image
- * @param {number} left - The number of pixels to crop from the left side of the image
- * @param {number} bottom - The number of pixels to crop from the bottom of the image
- * @param {number} right - The number of pixels to crop from the right side of the image
+ * @param {number} [top] - The number of pixels to crop from the top of the image
+ * @param {number} [left] - The number of pixels to crop from the left side of the image
+ * @param {number} [bottom] - The number of pixels to crop from the bottom of the image
+ * @param {number} [right] - The number of pixels to crop from the right side of the image
* @returns {boolean} true if the crop is set successfully, otherwise false
* @example
* ```ts
diff --git a/packages/sheets-drawing/src/facade/f-worksheet.ts b/packages/sheets-drawing/src/facade/f-worksheet.ts
index 279363d758..72f806535f 100644
--- a/packages/sheets-drawing/src/facade/f-worksheet.ts
+++ b/packages/sheets-drawing/src/facade/f-worksheet.ts
@@ -50,7 +50,7 @@ export interface IFWorksheetDrawingMixin {
/**
* Insert an image to the sheet
* @param {string} url - The image url
- * @returns true if the image is inserted successfully
+ * @returns {Promise<boolean>} true if the image is inserted successfully
* @example
* ```ts
* // Insert an image to the sheet, default position is A1
@@ -65,7 +65,7 @@ export interface IFWorksheetDrawingMixin {
* @param {string} url - The image url
* @param {number} column - The column index to insert the image
* @param {number} row - The row index to insert the image
- * @returns True if the image is inserted successfully
+ * @returns {Promise<boolean>} True if the image is inserted successfully
* @example
* ```ts
* // Insert an image to the sheet, position is F6
@@ -82,7 +82,7 @@ export interface IFWorksheetDrawingMixin {
* @param {number} row - The row index to insert the image
* @param {number} offsetX - The column offset, pixel unit
* @param {number} offsetY - The row offset, pixel unit
- * @returns True if the image is inserted successfully
+ * @returns {Promise<boolean>} True if the image is inserted successfully
* @example
* ```ts
* // Insert an image to the sheet, position is F6, offset is 10px
@@ -919,6 +919,5 @@ function getDrawingBounds(drawing: ISheetDrawing): IGroupBaseBound | null {
FWorksheet.extend(FWorksheetDrawingMixin);
declare module '@univerjs/sheets/facade' {
- // eslint-disable-next-line ts/naming-convention
interface FWorksheet extends IFWorksheetDrawingMixin { }
}
diff --git a/packages/sheets-filter/src/facade/f-filter.ts b/packages/sheets-filter/src/facade/f-filter.ts
index 27d4bb56b8..13218d8d64 100644
--- a/packages/sheets-filter/src/facade/f-filter.ts
+++ b/packages/sheets-filter/src/facade/f-filter.ts
@@ -92,7 +92,7 @@ export class FFilter {
/**
* Get the filter criteria of a column.
- * @param {number} column - The column index.
+ * @param {number} column - The absolute, zero-based worksheet column index, not an index relative to the filter range.
* @returns {Nullable<IFilterColumn>} The filter criteria of the column.
* @example
* ```typescript
@@ -144,7 +144,7 @@ export class FFilter {
/**
* Clear the filter criteria of a column.
- * @param {number} column - The column index.
+ * @param {number} column - The absolute, zero-based worksheet column index, not an index relative to the filter range.
* @returns {FFilter} The FFilter instance for chaining.
* @example
* ```typescript
@@ -203,7 +203,7 @@ export class FFilter {
/**
* Set the filter criteria of a column.
- * @param {number} column - The column index.
+ * @param {number} column - The absolute, zero-based worksheet column index, not an index relative to the filter range.
* @param {ISetSheetsFilterCriteriaCommandParams['criteria']} criteria - The new filter criteria.
* @returns {FFilter} The FFilter instance for chaining.
* @example
diff --git a/packages/sheets-hyper-link/src/facade/f-range.ts b/packages/sheets-hyper-link/src/facade/f-range.ts
index d9fd415e70..f351d716ce 100644
--- a/packages/sheets-hyper-link/src/facade/f-range.ts
+++ b/packages/sheets-hyper-link/src/facade/f-range.ts
@@ -36,7 +36,7 @@ export interface IFRangeSheetsHyperlinkMixin {
* The hyperlink can be a URL, a range link, or a sheet link.
* When the hyperlink is a range link or a sheet link, the url should be the url of the target range or sheet.
* @param {string} url - The hyperlink url, can be a URL, a range link, or a sheet link.
- * @param {string} [label] - The display text of the hyperlink. If not provided, the url will be used as the display text.
+ * @param {string} [label] - The display text of the hyperlink. If omitted, the existing cell text is linked. Supply a label when linking an empty cell.
* @return {Promise<boolean>} A promise that resolves to true if the hyperlink is set successfully, otherwise false.
*
* @example
@@ -71,8 +71,8 @@ export interface IFRangeSheetsHyperlinkMixin {
setHyperLink(url: string, label?: string): Promise<boolean>;
/**
- * Get all hyperlinks in this range.
- * @return {ICellHyperLink[]} An array of hyperlinks in this range.
+ * Gets the first hyperlink from each cell containing hyperlinks in this range.
+ * @returns {ICellHyperLink[]} At most one hyperlink per cell, with absolute, zero-based worksheet coordinates.
*
* @example
* ```ts
@@ -87,8 +87,10 @@ export interface IFRangeSheetsHyperlinkMixin {
/**
* Update the hyperlink of this range top left cell.
* @param {string} url - The new hyperlink url, can be a URL, a range link, or a sheet link.
- * @param {string} [label] - The new display text of the hyperlink. If not provided, the url will be used as the display text.
+ * @param {string} [label] - The new display text of the hyperlink. If omitted, the replacement display text is empty. Supply a label to keep the link visible.
*
+ * @returns {Promise<boolean>} A promise resolving to whether the update succeeded.
+ * @throws {Error} The promise rejects if the top-left cell contains no hyperlink.
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
@@ -260,6 +262,5 @@ export class FRangeSheetsHyperlinkMixin extends FRange implements IFRangeSheetsH
FRange.extend(FRangeSheetsHyperlinkMixin);
declare module '@univerjs/sheets/facade' {
- // eslint-disable-next-line ts/naming-convention
interface FRange extends IFRangeSheetsHyperlinkMixin {}
}
diff --git a/packages/sheets-numfmt/src/facade/f-range.ts b/packages/sheets-numfmt/src/facade/f-range.ts
index e0a81c752d..8170cbf601 100644
--- a/packages/sheets-numfmt/src/facade/f-range.ts
+++ b/packages/sheets-numfmt/src/facade/f-range.ts
@@ -61,13 +61,13 @@ export interface IFRangeSheetsNumfmtMixin {
* ['#,##0.00', '0.00%'],
* ['yyyy-MM-DD', '']
* ]);
- * console.log(fRange.getDisplayValues()); // [['1,234.57', '12.34%'], ['2025-01-01', 0.9876]]
+ * console.log(fRange.getDisplayValues()); // [['1,234.57', '12.34%'], ['2025-01-01', '0.9876']]
* ```
*/
setNumberFormats(patterns: string[][]): FRange;
/**
- * Get the number formatting of the top-left cell of the given range. Empty cells return an empty string.
+ * Get the number formatting of the top-left cell of the given range. Returns an empty string when no number format is set, even if the cell contains a value.
* @returns {string} The number format of the top-left cell of the range.
* @example
* ```ts
@@ -155,6 +155,5 @@ export class FRangeSheetsNumfmtMixin extends FRange implements IFRangeSheetsNumf
FRange.extend(FRangeSheetsNumfmtMixin);
declare module '@univerjs/sheets/facade' {
- // eslint-disable-next-line ts/naming-convention
interface FRange extends IFRangeSheetsNumfmtMixin { }
}
diff --git a/packages/sheets-table/src/facade/f-enum.ts b/packages/sheets-table/src/facade/f-enum.ts
index a5c56a2f15..8a1563b18d 100644
--- a/packages/sheets-table/src/facade/f-enum.ts
+++ b/packages/sheets-table/src/facade/f-enum.ts
@@ -21,10 +21,15 @@ import { TableColumnFilterTypeEnum, TableConditionTypeEnum, TableDateCompareType
* @ignore
*/
export interface IFSheetsTableEnumMixin {
+ /** Filter kinds available for table columns. */
TableColumnFilterTypeEnum: typeof TableColumnFilterTypeEnum;
+ /** Value types used by table condition filters. */
TableConditionTypeEnum: typeof TableConditionTypeEnum;
+ /** Comparison operators for numeric table filters. */
TableNumberCompareTypeEnum: typeof TableNumberCompareTypeEnum;
+ /** Comparison operators for text table filters. */
TableStringCompareTypeEnum: typeof TableStringCompareTypeEnum;
+ /** Comparison operators for date table filters. */
TableDateCompareTypeEnum: typeof TableDateCompareTypeEnum;
}
@@ -52,6 +57,5 @@ export class FSheetsTableEnumMixin extends FEnum implements IFSheetsTableEnumMix
FEnum.extend(FSheetsTableEnumMixin);
declare module '@univerjs/core/facade' {
- // eslint-disable-next-line ts/naming-convention
interface FEnum extends IFSheetsTableEnumMixin { }
}
diff --git a/packages/sheets-table/src/facade/f-workbook.ts b/packages/sheets-table/src/facade/f-workbook.ts
index 5f8b81bb01..09b685dd59 100644
--- a/packages/sheets-table/src/facade/f-workbook.ts
+++ b/packages/sheets-table/src/facade/f-workbook.ts
@@ -45,7 +45,7 @@ export interface IFWorkbookSheetsTableMixin {
/**
* Get table information
* @param {string} tableId The table id
- * @returns {ITableInfo} The table information
+ * @returns {ITableInfoWithUnitId | undefined} The table information, including workbook and worksheet IDs, or `undefined` if not found.
* @example
* ```typescript
* const fWorkbook = univerAPI.getActiveWorkbook();
@@ -74,7 +74,7 @@ export interface IFWorkbookSheetsTableMixin {
/**
* Get table information by name
* @param {string} tableName The table name
- * @returns {ITableInfo} The table information
+ * @returns {ITableInfoWithUnitId | undefined} The table information, including workbook and worksheet IDs, or `undefined` if not found.
* @example
* ```typescript
* const fWorkbook = univerAPI.getActiveWorkbook();
@@ -119,7 +119,7 @@ export interface IFWorkbookSheetsTableMixin {
* @param {ITableRange} rangeInfo The table range information
* @param {string} [tableId] The table id
* @param {ITableOptions} [options] The table options
- * @returns {string} The table id
+ * @returns {Promise<string | undefined>} A promise resolving to the table ID, or `undefined` if the name is invalid or creation fails.
* @example
* ```typescript
* const fWorkbook = univerAPI.getActiveWorkbook();
@@ -150,7 +150,7 @@ export interface IFWorkbookSheetsTableMixin {
* set table filter
* @param {string} tableId The table id
* @param {number} column The column index, starting from 0.
- * @param {ITableFilterItem} filter The filter item
+ * @param {ITableFilterItem | undefined} filter The filter to apply, or `undefined` to clear the column filter.
* @returns {Promise<boolean>} The result of set table filter
* @example
* ```typescript
@@ -185,12 +185,12 @@ export interface IFWorkbookSheetsTableMixin {
* }
* ```
*/
- setTableFilter(tableId: string, column: number, filter: ITableFilterItem | undefined): void;
+ setTableFilter(tableId: string, column: number, filter: ITableFilterItem | undefined): Promise<boolean>;
/**
* Remove table
* @param {string} tableId The table id
- * @returns {boolean} The result of remove table
+ * @returns {Promise<boolean>} A promise resolving to whether the table was removed; `false` if the table is not found.
* @example
* ```typescript
* const fWorkbook = univerAPI.getActiveWorkbook();
@@ -287,6 +287,5 @@ export class FWorkbookSheetsTableMixin extends FWorkbook implements IFWorkbookSh
FWorkbook.extend(FWorkbookSheetsTableMixin);
declare module '@univerjs/sheets/facade' {
- // eslint-disable-next-line ts/naming-convention
interface FWorkbook extends IFWorkbookSheetsTableMixin { }
}
diff --git a/packages/sheets-table/src/facade/f-worksheet.ts b/packages/sheets-table/src/facade/f-worksheet.ts
index 9b49f29b20..925876eebb 100644
--- a/packages/sheets-table/src/facade/f-worksheet.ts
+++ b/packages/sheets-table/src/facade/f-worksheet.ts
@@ -47,7 +47,7 @@ export interface IFWorksheetTableMixin {
* @param {ITableRange} rangeInfo The table range information
* @param {string} [tableId] The table id
* @param {ITableOptions} [options] The table options
- * @returns {Promise<boolean>} Whether the table was added successfully
+ * @returns {Promise<boolean> | boolean} `false` for an invalid table name; otherwise, a promise resolving to whether the command succeeded.
* @example
* ```typescript
* const fWorkbook = univerAPI.getActiveWorkbook();
@@ -187,7 +187,7 @@ export interface IFWorksheetTableMixin {
* Set the name of a table
* @param {string} tableId The table id
* @param {string} tableName The new table name
- * @returns {Promise<boolean>} Whether the table name was set successfully
+ * @returns {Promise<boolean> | boolean} `false` for an invalid table name; otherwise, a promise resolving to whether the command succeeded.
* @example
* ```typescript
* const fWorkbook = univerAPI.getActiveWorkbook();
@@ -474,6 +474,5 @@ export class FWorksheetTableMixin extends FWorksheet implements IFWorksheetTable
FWorksheet.extend(FWorksheetTableMixin);
declare module '@univerjs/sheets/facade' {
- // eslint-disable-next-line ts/naming-convention
interface FWorksheet extends IFWorksheetTableMixin { }
}
diff --git a/packages/sheets-thread-comment/src/facade/f-range.ts b/packages/sheets-thread-comment/src/facade/f-range.ts
index 325820d672..10a5652f24 100644
--- a/packages/sheets-thread-comment/src/facade/f-range.ts
+++ b/packages/sheets-thread-comment/src/facade/f-range.ts
@@ -76,8 +76,8 @@ export interface IFRangeSheetsThreadCommentMixin {
/**
* Add a comment to the start cell in the current range.
* @param content The content of the comment.
- * @param options Optional stable IDs, author, attachments, and creation time.
- * @returns Whether the comment is added successfully.
+ * @param [options] Optional stable IDs, author, attachments, and creation time.
+ * @returns {Promise<boolean>} Whether the comment is added successfully.
* @throws {TypeError} If the content is empty.
* @example
* ```ts
@@ -108,7 +108,7 @@ export interface IFRangeSheetsThreadCommentMixin {
/**
* Clear the comment of the start cell in the current range.
- * @returns Whether the comment is cleared successfully.
+ * @returns {Promise<boolean>} Whether the comment is cleared successfully.
* @example
* ```ts
* const range = univerAPI.getActiveWorkbook().getActiveSheet().getRange('A1');
@@ -120,7 +120,7 @@ export interface IFRangeSheetsThreadCommentMixin {
/**
* Clear all of the comments in the current range.
- * @returns Whether the comments are cleared successfully.
+ * @returns {Promise<boolean>} Whether the comments are cleared successfully.
* @example
* ```ts
* const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1');
diff --git a/packages/sheets-thread-comment/src/facade/f-thread-comment.ts b/packages/sheets-thread-comment/src/facade/f-thread-comment.ts
index ac931f9540..048728258e 100644
--- a/packages/sheets-thread-comment/src/facade/f-thread-comment.ts
+++ b/packages/sheets-thread-comment/src/facade/f-thread-comment.ts
@@ -41,7 +41,7 @@ export class FTheadCommentItem {
/**
* Create a new FTheadCommentItem
- * @param {IThreadComment|undefined} comment The comment
+ * @param {IThreadComment|undefined} [comment] The comment
* @returns {FTheadCommentItem} A new instance of FTheadCommentItem
* @example
* ```ts
@@ -370,7 +370,7 @@ export class FThreadComment {
/**
* Get the replies of the comment
- * @returns {FThreadComment[]} the replies of the comment
+ * @returns {FThreadComment[] | undefined} The loaded replies, or `undefined` when the thread or its replies are unavailable.
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
@@ -515,7 +515,7 @@ export class FThreadComment {
/**
* Resolve the comment
- * @param {boolean} resolved Whether the comment is resolved
+ * @param {boolean} [resolved] Whether the comment is resolved
* @returns {Promise<boolean>} Set the comment to resolved or not operation result
* @example
* ```ts
diff --git a/packages/sheets-thread-comment/src/facade/f-worksheet.ts b/packages/sheets-thread-comment/src/facade/f-worksheet.ts
index 4badae5652..faa392065c 100644
--- a/packages/sheets-thread-comment/src/facade/f-worksheet.ts
+++ b/packages/sheets-thread-comment/src/facade/f-worksheet.ts
@@ -68,6 +68,7 @@ export interface IFWorksheetCommentMixin {
/**
* get comment by comment id
* @param {string} commentId comment id
+ * @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getSheetByName('Sheet1');
@@ -131,6 +132,5 @@ export class FWorksheetCommentMixin extends FWorksheet implements IFWorksheetCom
FWorksheet.extend(FWorksheetCommentMixin);
declare module '@univerjs/sheets/facade' {
- // eslint-disable-next-line ts/naming-convention
interface FWorksheet extends IFWorksheetCommentMixin {}
}
diff --git a/packages/sheets-ui/src/facade/f-range.ts b/packages/sheets-ui/src/facade/f-range.ts
index a2b39a27a0..203646cbdf 100644
--- a/packages/sheets-ui/src/facade/f-range.ts
+++ b/packages/sheets-ui/src/facade/f-range.ts
@@ -154,8 +154,8 @@ interface IFRangeSheetsUIMixin {
/**
* Attach a DOM popup to the current range.
- * @param {IFCanvasPopup} alert The alert to attach
- * @returns {Nullable<IDisposable>} The disposable object to detach the alert.
+ * @param {IFCanvasPopup} popup The popup to attach.
+ * @returns {Nullable<IDisposable>} A disposable that detaches the popup, or `null` if the popup cannot be attached.
* @example
* ```ts
* // Register a custom popup component
@@ -184,8 +184,8 @@ interface IFRangeSheetsUIMixin {
/**
* Highlight the range with the specified style and primary cell.
- * @param {Nullable<Partial<ISelectionStyle>>} style - style for highlight range.
- * @param {Nullable<ISelectionCell>} primary - primary cell for highlight range.
+ * @param {Nullable<Partial<ISelectionStyle>>} [style] - style for highlight range.
+ * @param {Nullable<ISelectionCell>} [primary] - primary cell for highlight range.
* @returns {IDisposable} The disposable object to remove the highlight.
* @example
* ```ts
@@ -317,7 +317,7 @@ class FRangeSheetsUIMixin extends FRange implements IFRangeSheetsUIMixin {
/**
* attachRangePopup
* @param popup
- * @returns {IDisposable} disposable
+ * @returns {Nullable<IDisposable>} A disposable that detaches the popup, or `null` if the popup cannot be attached.
* @example
* ```typescript
* let fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1');
@@ -372,7 +372,6 @@ class FRangeSheetsUIMixin extends FRange implements IFRangeSheetsUIMixin {
FRange.extend(FRangeSheetsUIMixin);
declare module '@univerjs/sheets/facade' {
- // eslint-disable-next-line ts/naming-convention
interface FRange extends IFRangeSheetsUIMixin { }
}
diff --git a/packages/sheets-ui/src/facade/f-workbook.ts b/packages/sheets-ui/src/facade/f-workbook.ts
index 1ee879707b..fc3ba69282 100644
--- a/packages/sheets-ui/src/facade/f-workbook.ts
+++ b/packages/sheets-ui/src/facade/f-workbook.ts
@@ -105,7 +105,7 @@ export interface IFWorkbookSheetsUIMixin {
/**
* End the editing process of the current active cell
- * @param {boolean} save - Whether to save the changes, default is true
+ * @param {boolean} [save] - Whether to save the changes, default is true
* @returns {Promise<boolean>} Whether the editing process is ended successfully
* @example
* ```ts
@@ -141,7 +141,7 @@ export interface IFWorkbookSheetsUIMixin {
/**
* Get scroll state of specified sheet.
* @param {string} sheetId - sheet id
- * @returns {IScrollState} scroll state
+ * @returns {Nullable<IScrollState>} The sheet scroll state, or a nullish value when no state is available.
* @example
* ``` ts
* const fWorkbook = univerAPI.getActiveWorkbook();
@@ -341,6 +341,5 @@ export class FWorkbookSheetsUIMixin extends FWorkbook implements IFWorkbookSheet
FWorkbook.extend(FWorkbookSheetsUIMixin);
declare module '@univerjs/sheets/facade' {
- // eslint-disable-next-line ts/naming-convention
interface FWorkbook extends IFWorkbookSheetsUIMixin {}
}
diff --git a/packages/sheets-ui/src/facade/f-worksheet.ts b/packages/sheets-ui/src/facade/f-worksheet.ts
index deea1b64f2..e2ad8b17a9 100644
--- a/packages/sheets-ui/src/facade/f-worksheet.ts
+++ b/packages/sheets-ui/src/facade/f-worksheet.ts
@@ -62,8 +62,8 @@ export interface IFWorksheetUIMixin {
/**
* Highlight multiple ranges on the worksheet.
* @param {FRange[]} ranges The ranges to highlight.
- * @param {Nullable<Partial<ISelectionStyle>>} style - style for highlight ranges.
- * @param {Nullable<ISelectionCell>} primary - primary cell for highlight ranges.
+ * @param {Nullable<Partial<ISelectionStyle>>} [style] - style for highlight ranges.
+ * @param {Nullable<ISelectionCell>} [primary] - primary cell for highlight ranges.
* @return {IDisposable} An IDisposable to remove the highlights.
* @example
* ```ts
@@ -113,7 +113,7 @@ export interface IFWorksheetUIMixin {
/**
* Get visible range of main viewport.
- * @returns {IRange} - visible range
+ * @returns {IRange | null} The visible range of the main viewport, or `null` if no sheet skeleton is available.
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
@@ -121,14 +121,16 @@ export interface IFWorksheetUIMixin {
* if (!fWorksheet) return;
* const visibleRange = fWorksheet.getVisibleRange();
* console.log(visibleRange);
- * console.log(fWorksheet.getRange(visibleRange).getA1Notation());
+ * if (visibleRange) {
+ * console.log(fWorksheet.getRange(visibleRange).getA1Notation());
+ * }
* ```
*/
getVisibleRange(): IRange | null;
/**
* Get visible ranges of all viewports.
- * @returns {Record<SHEET_VIEWPORT_KEY, IRange>} - visible ranges of all viewports
+ * @returns {Map<SHEET_VIEWPORT_KEY, IRange> | null} Visible ranges keyed by viewport in a `Map`, or `null` if no sheet skeleton is available.
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
@@ -137,7 +139,9 @@ export interface IFWorksheetUIMixin {
* const visibleRanges = fWorksheet.getVisibleRangesOfAllViewports();
* console.log(visibleRanges);
* const mainLeftTopViewportRange = visibleRanges?.get(univerAPI.Enum.SHEET_VIEWPORT_KEY.VIEW_MAIN_LEFT_TOP);
- * console.log(fWorksheet.getRange(mainLeftTopViewportRange).getA1Notation());
+ * if (mainLeftTopViewportRange) {
+ * console.log(fWorksheet.getRange(mainLeftTopViewportRange).getA1Notation());
+ * }
* ```
*/
getVisibleRangesOfAllViewports(): Map<SHEET_VIEWPORT_KEY, IRange> | null;
@@ -292,7 +296,7 @@ export interface IFWorksheetUIMixin {
customizeRowHeader(cfg: IRowsHeaderCfgParam): void;
/**
- * Set column height for column header.
+ * Sets the height of the column header in pixels.
* @param {number} height - The height to set.
* @returns {FWorksheet} - The FWorksheet instance for chaining.
* @example
@@ -306,7 +310,7 @@ export interface IFWorksheetUIMixin {
setColumnHeaderHeight(height: number): FWorksheet;
/**
- * Set column height for column header.
+ * Sets the width of the row header in pixels.
* @param {number} width - The width to set.
* @returns {FWorksheet} - The FWorksheet instance for chaining.
* @example
@@ -553,6 +557,5 @@ export class FWorksheetUIMixin extends FWorksheet implements IFWorksheetUIMixin
FWorksheet.extend(FWorksheetUIMixin);
declare module '@univerjs/sheets/facade' {
- // eslint-disable-next-line ts/naming-convention
interface FWorksheet extends IFWorksheetUIMixin { }
}
diff --git a/packages/sheets/src/facade/f-defined-name.ts b/packages/sheets/src/facade/f-defined-name.ts
index 289f78b457..8b66311daa 100644
--- a/packages/sheets/src/facade/f-defined-name.ts
+++ b/packages/sheets/src/facade/f-defined-name.ts
@@ -107,7 +107,7 @@ export class FDefinedNameBuilder {
/**
* Sets the formula of the defined name builder.
- * @param {string }formula The formula of the defined name.
+ * @param {string} formula The formula without the leading `=`; this method prepends it.
* @returns {FDefinedNameBuilder} The instance of `FDefinedNameBuilder` for method chaining.
* @example
* ```ts
@@ -370,7 +370,7 @@ export class FDefinedName extends FBase {
/**
* Sets the formula of the defined name.
- * @param {string} formula The formula of the defined name.
+ * @param {string} formula The formula without the leading `=`; this method prepends it.
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
diff --git a/packages/sheets/src/facade/f-range.ts b/packages/sheets/src/facade/f-range.ts
index e0871dccc4..b1b7afbb53 100644
--- a/packages/sheets/src/facade/f-range.ts
+++ b/packages/sheets/src/facade/f-range.ts
@@ -293,8 +293,8 @@ export class FRange extends FBaseInitialable {
}
/**
- * Gets the width of the applied area
- * @returns {number} The width of the area
+ * Returns the number of columns in this range.
+ * @returns {number} The column count, not a size in pixels.
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
@@ -309,8 +309,8 @@ export class FRange extends FBaseInitialable {
}
/**
- * Gets the height of the applied area
- * @returns {number} The height of the area
+ * Returns the number of rows in this range.
+ * @returns {number} The row count, not a size in pixels.
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
@@ -325,8 +325,8 @@ export class FRange extends FBaseInitialable {
}
/**
- * Return range whether this range is merged
- * @returns {boolean} if true is merged
+ * Checks whether this range exactly matches a merged cell range.
+ * @returns {boolean} `true` only for an exact merged range match. Use `isPartOfMerge()` to check overlap.
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
@@ -349,7 +349,7 @@ export class FRange extends FBaseInitialable {
* Return first cell style data in this range. Please note that if there are row styles, col styles and (or)
* worksheet style, they will be merged into the cell style. You can use `type` to specify the type of the style to get.
*
- * @param {GetStyleType} type - The type of the style to get. 'row' means get the composed style of row, col and
+ * @param {GetStyleType} [type] - The type of the style to get. 'row' means get the composed style of row, col and
* default worksheet style. 'col' means get the composed style of col, row and default worksheet style.
* 'cell' means get the style of cell without merging row style, col style and default worksheet style.
* Default is 'row'.
@@ -375,7 +375,7 @@ export class FRange extends FBaseInitialable {
/**
* Get the font family of the cell.
*
- * @param {GetStyleType} type - The type of the style to get. 'row' means get the composed style of row, col and
+ * @param {GetStyleType} [type] - The type of the style to get. 'row' means get the composed style of row, col and
* default worksheet style. 'col' means get the composed style of col, row and default worksheet style.
* 'cell' means get the style of cell without merging row style, col style and default worksheet style.
* Default is 'row'.
@@ -397,7 +397,7 @@ export class FRange extends FBaseInitialable {
/**
* Get the font size of the cell.
*
- * @param {GetStyleType} type - The type of the style to get. 'row' means get the composed style of row, col and
+ * @param {GetStyleType} [type] - The type of the style to get. 'row' means get the composed style of row, col and
* default worksheet style. 'col' means get the composed style of col, row and default worksheet style.
* 'cell' means get the style of cell without merging row style, col style and default worksheet style.
* Default is 'row'.
@@ -419,7 +419,7 @@ export class FRange extends FBaseInitialable {
/**
* Return first cell style in this range.
*
- * @param {GetStyleType} type - The type of the style to get. 'row' means get the composed style of row, col and
+ * @param {GetStyleType} [type] - The type of the style to get. 'row' means get the composed style of row, col and
* default worksheet style. 'col' means get the composed style of col, row and default worksheet style.
* 'cell' means get the style of cell without merging row style, col style and default worksheet style.
* Default is 'row'.
@@ -442,7 +442,7 @@ export class FRange extends FBaseInitialable {
/**
* Returns the cell styles for the cells in the range.
*
- * @param {GetStyleType} type - The type of the style to get. 'row' means get the composed style of row, col and
+ * @param {GetStyleType} [type] - The type of the style to get. 'row' means get the composed style of row, col and
* default worksheet style. 'col' means get the composed style of col, row and default worksheet style.
* 'cell' means get the style of cell without merging row style, col style and default worksheet style.
* Default is 'row'.
@@ -489,7 +489,7 @@ export class FRange extends FBaseInitialable {
getValue(): CellValue | null;
/**
* Return first cell value in this range
- * @param {boolean} includeRichText Should the returns of this func to include rich text
+ * @param {true} includeRichText Pass `true` to return a `RichTextValue` for rich-text content instead of plain text.
* @returns {CellValue | RichTextValue | null} The cell value
* @example
* ```ts
@@ -583,7 +583,7 @@ export class FRange extends FBaseInitialable {
getValues(): Nullable<CellValue>[][];
/**
* Returns the cell values for the cells in the range.
- * @param {boolean} includeRichText Should the returns of this func to include rich text
+ * @param {true} includeRichText Pass `true` to return `RichTextValue` entries for rich-text content instead of plain text.
* @returns {Nullable<RichTextValue | CellValue>[][]} A two-dimensional array of cell values.
* @example
* ```ts
@@ -947,7 +947,10 @@ export class FRange extends FBaseInitialable {
return this._worksheet.getRange(this._range).getWrap() === BooleanNumber.TRUE;
}
- /** Gets whether the top-left cell shrinks its font size to fit the cell width. */
+ /**
+ * Gets whether the top-left cell shrinks its font size to fit the cell width.
+ * @returns {boolean} Whether shrink-to-fit is enabled for the top-left cell.
+ */
getShrinkToFit(): boolean {
const { startRow, startColumn } = this._range;
return this._worksheet.getComposedCellStyle(startRow, startColumn)?.stf === BooleanNumber.TRUE;
@@ -1057,6 +1060,7 @@ export class FRange extends FBaseInitialable {
* Set custom meta data for first cell in current range.
* @param {CustomData} data The custom meta data
* @returns {FRange} This range, for chaining
+ * @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getSheetByName('Sheet1');
@@ -1087,6 +1091,7 @@ export class FRange extends FBaseInitialable {
* Set custom meta data for current range.
* @param {CustomData[][]} datas The custom meta data
* @returns {FRange} This range, for chaining
+ * @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getSheetByName('Sheet1');
@@ -1135,7 +1140,7 @@ export class FRange extends FBaseInitialable {
/**
* Returns the custom meta data for the cells in the range.
- * @returns {CustomData[][]} A two-dimensional array of custom meta data
+ * @returns {Nullable<CustomData>[][]} A two-dimensional array of custom metadata, with `null` for cells without metadata.
* @example
* ```
* const fWorkbook = univerAPI.getActiveWorkbook();
@@ -1287,18 +1292,55 @@ export class FRange extends FBaseInitialable {
}
/**
- * Sets the value of the range.
- * @param {CellValue | ICellData} value The value can be a number, string, boolean, or standard cell format. If it begins with `=`, it is interpreted as a formula. The value is tiled to all cells in the range.
+ * Sets the value or specified cell properties for every cell in this range.
+ *
+ * There are two input modes:
+ *
+ * - `CellValue` (`number`, `string`, or `boolean`): replaces the cell content. A string starting
+ * with `=` and containing at least one more character is written as a formula (`f`), clearing
+ * the previous value (`v`) and rich text (`p`). Other values clear the previous formula and
+ * rich text. Strings recognized as formatted numbers (for example, percentages, dates, or
+ * currencies) are converted to numeric values and apply the parsed number format. Existing
+ * formatting is otherwise preserved.
+ * - `ICellData`: updates cell-data fields directly, for explicit control over `v` (value),
+ * `f` (formula), `p` (rich text), `t` (value type), and `s` (style). The object bypasses the
+ * formula and formatted-number parsing above: `{ v: '=SUM(A1:A2)' }` does not set a formula;
+ * use `{ f: '=SUM(A1:A2)', v: null, p: null }` instead. Omitted content fields are not
+ * automatically cleared, so use `f: null` and `p: null` when replacing a formula or rich text
+ * with `v`. Use `v: null` to clear the stored value. Supplied style properties are merged into
+ * the existing style; `s: null` clears the style.
+ *
+ * In both modes, the stored value is converted according to its cell type. Unless an `ICellData`
+ * input supplies `t`, the type is inferred from the value, number format, and existing cell type.
+ * Consequently, passing `{ v: '00123' }` alone does not guarantee that the value stays a string;
+ * supply `t: CellValueType.STRING` to store it as text.
+ *
+ * @param {CellValue | ICellData} value The scalar content or cell-data update to apply throughout the range.
* @returns {FRange} This range, for chaining
+ * @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getSheetByName('Sheet1');
* if (!fWorksheet) return;
- * const fRange = fWorksheet.getRange('B2');
+ * const fRange = fWorksheet.getRange('B2:B3');
+ *
+ * // Replace the content of both cells, preserving their formatting.
* fRange.setValue(123);
*
- * // or
- * fRange.setValue({ v: 234, s: { bg: { rgb: '#ff0000' } } });
+ * // Parse a percentage and apply its number format to both cells.
+ * fRange.setValue('25%');
+ *
+ * // Write the same formula to both cells.
+ * fRange.setValue('=SUM(A1:A2)');
+ *
+ * // Explicitly replace content and update the background color.
+ * fRange.setValue({ v: 234, f: null, p: null, s: { bg: { rgb: '#ff0000' } } });
+ *
+ * // Store numeric-looking text (CellValueType is imported from '@univerjs/core').
+ * fRange.setValue({ v: '00123', t: CellValueType.STRING, f: null, p: null });
+ *
+ * // Clear value, formula, and rich text while preserving formatting.
+ * fRange.setValue({ v: null, f: null, p: null });
* ```
*/
setValue(value: CellValue | ICellData): FRange {
@@ -1319,9 +1361,11 @@ export class FRange extends FBaseInitialable {
}
/**
- * Set new value for current cell, first cell in this range.
- * @param {CellValue | ICellData} value The value can be a number, string, boolean, or standard cell format. If it begins with `=`, it is interpreted as a formula. The value is tiled to all cells in the range.
+ * Sets the value or specified cell properties of the top-left cell in this range.
+ * Uses the same scalar parsing and cell-data update rules as {@link FRange.setValue}.
+ * @param {CellValue | ICellData} value The scalar content or cell-data update to apply to the top-left cell only.
* @returns {FRange} This range, for chaining
+ * @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getSheetByName('Sheet1');
@@ -1395,7 +1439,7 @@ export class FRange extends FBaseInitialable {
/**
* Set the rich text value for the cells in the range.
- * @param {RichTextValue[][]} values The rich text value
+ * @param {(RichTextValue | IDocumentData)[][]} values A two-dimensional array of rich-text values or document data matching this range's dimensions.
* @returns {FRange} The range
* @example
* ```ts
@@ -1412,7 +1456,7 @@ export class FRange extends FBaseInitialable {
* .setStyle(6, 7, { bl: 1, cl: { rgb: '#c81e1e' } });
* fRange.setRichTextValues([
* [richText, richText],
- * [null, null]
+ * [richText, richText]
* ]);
* console.log(fRange.getValue(true).toPlainText()); // Hello World
* ```
@@ -1433,7 +1477,8 @@ export class FRange extends FBaseInitialable {
/**
* Set the cell wrap of the given range.
- * Cells with wrap enabled (the default) resize to display their full content. Cells with wrap disabled display as much as possible in the cell without resizing or running to multiple lines.
+ * Pass `true` to set `WrapStrategy.WRAP`, or `false` to reset to `WrapStrategy.UNSPECIFIED`.
+ * Use `setWrapStrategy()` to explicitly select clipping or overflow behavior.
* @param {boolean} isWrapEnabled Whether to enable wrap
* @returns {FRange} this range, for chaining
* @example
@@ -1457,7 +1502,15 @@ export class FRange extends FBaseInitialable {
return this;
}
- /** Sets whether cells shrink their font size to fit the cell width. */
+ /**
+ * Sets whether cells shrink their font size to fit the cell width.
+ * @param {boolean} enabled Whether to enable shrink-to-fit for this range.
+ * @returns {FRange} This range, for chaining.
+ * @example
+ * ```ts
+ * univerAPI.getActiveWorkbook()?.getActiveSheet().getRange('A1:B2').setShrinkToFit(true);
+ * ```
+ */
setShrinkToFit(enabled: boolean): FRange {
this._commandService.syncExecuteCommand(SetShrinkToFitCommand.id, {
unitId: this._workbook.getUnitId(),
@@ -1496,7 +1549,7 @@ export class FRange extends FBaseInitialable {
/**
* Set the vertical (top to bottom) alignment for the given range (top/middle/bottom).
- * @param {"top" | "middle" | "bottom"} alignment The vertical alignment
+ * @param {FVerticalAlignment} alignment The vertical alignment
* @returns {FRange} this range, for chaining
* @example
* ```ts
@@ -1520,7 +1573,7 @@ export class FRange extends FBaseInitialable {
/**
* Set the horizontal (left to right) alignment for the given range (left/center/right).
- * @param {"left" | "center" | "normal"} alignment The horizontal alignment
+ * @param {FHorizontalAlignment} alignment The horizontal alignment
* @returns {FRange} this range, for chaining
* @example
* ```ts
@@ -1543,8 +1596,13 @@ export class FRange extends FBaseInitialable {
}
/**
- * Sets a different value for each cell in the range. The value can be a two-dimensional array or a standard range matrix (must match the dimensions of this range), consisting of numbers, strings, Boolean values or Composed of standard cell formats. If a value begins with `=`, it is interpreted as a formula.
- * @param {CellValue[][] | IObjectMatrixPrimitiveType<CellValue> | ICellData[][] | IObjectMatrixPrimitiveType<ICellData>} value The value can be a two-dimensional array or a standard range matrix (must match the dimensions of this range), consisting of numbers, strings, Boolean values or Composed of standard cell formats.
+ * Sets cell values or specified cell properties using an array or a sparse matrix.
+ * Each entry follows the scalar parsing and cell-data update rules of {@link FRange.setValue}.
+ *
+ * A two-dimensional array is relative to this range's top-left cell and must match its dimensions.
+ * A sparse matrix uses absolute, zero-based worksheet row and column keys. Only supplied entries
+ * are updated; matrix coordinates are not offset by or clipped to this range.
+ * @param {CellValue[][] | IObjectMatrixPrimitiveType<CellValue> | ICellData[][] | IObjectMatrixPrimitiveType<ICellData>} value An array relative to this range, or a sparse matrix using absolute worksheet coordinates.
* @returns {FRange} This range, for chaining
* @example
* ```ts
@@ -1556,6 +1614,12 @@ export class FRange extends FBaseInitialable {
* [1, { v: 2, s: { bg: { rgb: '#ff0000' } } }],
* [3, 4]
* ]);
+ *
+ * // Update only B2 and C3 using absolute worksheet coordinates.
+ * fWorksheet.getRange('B2:C3').setValues({
+ * 1: { 1: 'B2' },
+ * 2: { 2: { v: 10, f: null, p: null } },
+ * });
* ```
*/
setValues(
@@ -2001,6 +2065,7 @@ export class FRange extends FBaseInitialable {
* @param {number} callback.row the row number of the cell
* @param {number} callback.col the column number of the cell
* @param {ICellData} callback.cell the cell data
+ * @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getSheetByName('Sheet1');
@@ -2027,6 +2092,7 @@ export class FRange extends FBaseInitialable {
* @param {AbsoluteRefType} [startAbsoluteRefType] - The absolute reference type for the start cell.
* @param {AbsoluteRefType} [endAbsoluteRefType] - The absolute reference type for the end cell.
* @returns {string} The A1 notation of the range.
+ * @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getSheetByName('Sheet1');
@@ -2340,11 +2406,12 @@ export class FRange extends FBaseInitialable {
}
/**
- * Clears content and formatting information of the range. Or Optionally clears only the contents or only the formatting.
+ * Clears the range content and formatting, or only one of them as specified by the options.
+ * Both content and formatting are cleared when both flags are true or both are false.
* @param {IFacadeClearOptions} [options] - Options for clearing the range. If not provided, the contents and formatting are cleared both.
- * @param {boolean} [options.contentsOnly] - If true, the contents of the range are cleared. If false, the contents and formatting are cleared. Default is false.
- * @param {boolean} [options.formatOnly] - If true, the formatting of the range is cleared. If false, the contents and formatting are cleared. Default is false.
- * @returns {FWorksheet} Returns the current worksheet instance for method chaining
+ * @param {boolean} [options.contentsOnly] - If true, the contents of the range are cleared. Effective only when `formatOnly` is false. Defaults to false.
+ * @param {boolean} [options.formatOnly] - Clears only formatting when true and `contentsOnly` is false. Defaults to false.
+ * @returns {FRange} This range, for chaining.
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
@@ -2379,7 +2446,7 @@ export class FRange extends FBaseInitialable {
/**
* Clears content of the range, while preserving formatting information.
- * @returns {FWorksheet} Returns the current worksheet instance for method chaining
+ * @returns {FRange} This range, for chaining.
* @example
* ```typescript
* const fWorkbook = univerAPI.getActiveWorkbook();
@@ -2402,7 +2469,7 @@ export class FRange extends FBaseInitialable {
/**
* Clears formatting information of the range, while preserving contents.
- * @returns {FWorksheet} Returns the current worksheet instance for method chaining
+ * @returns {FRange} This range, for chaining.
* @example
* ```typescript
* const fWorkbook = univerAPI.getActiveWorkbook();
@@ -2595,7 +2662,6 @@ export class FRange extends FBaseInitialable {
* console.log(range3.getA1Notation()); // B2:D4
* ```
*/
- // eslint-disable-next-line complexity
getDataRegion(dimension?: Dimension): FRange {
const { startRow, startColumn, endRow, endColumn } = this._range;
const maxRows = this._worksheet.getMaxRows();
@@ -2755,8 +2821,8 @@ export class FRange extends FBaseInitialable {
* Returns a new range that is relative to the current range, whose upper left point is offset from the current range by the given rows and columns, and with the given height and width in cells.
* @param {number} rowOffset - The number of rows down from the range's top-left cell; negative values represent rows up from the range's top-left cell.
* @param {number} columnOffset - The number of columns right from the range's top-left cell; negative values represent columns left from the range's top-left cell.
- * @param {number} numRows - The height in rows of the new range.
- * @param {number} numColumns - The width in columns of the new range.
+ * @param {number} [numRows] - The height in rows of the new range.
+ * @param {number} [numColumns] - The width in columns of the new range.
* @returns {FRange} The new range.
* @example
* ```ts
diff --git a/packages/sheets/src/facade/f-selection.ts b/packages/sheets/src/facade/f-selection.ts
index cb949ec79d..8b83722868 100644
--- a/packages/sheets/src/facade/f-selection.ts
+++ b/packages/sheets/src/facade/f-selection.ts
@@ -93,7 +93,7 @@ export class FSelection {
/**
* Represents the current select cell in the sheet.
- * @returns {ISelectionCell} The current select cell info.Pay attention to the type of the return value.
+ * @returns {Nullable<ISelectionCell>} The primary cell of the current selection, or `null` when none exists.
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
diff --git a/packages/sheets/src/facade/f-univer.ts b/packages/sheets/src/facade/f-univer.ts
index c33e59e4a1..ff8fd6728c 100644
--- a/packages/sheets/src/facade/f-univer.ts
+++ b/packages/sheets/src/facade/f-univer.ts
@@ -76,7 +76,7 @@ export interface IFUniverSheetsMixin {
/**
* Create a new spreadsheet and get the API handler of that spreadsheet.
* @param {Partial<IWorkbookData>} data The snapshot of the spreadsheet.
- * @param {ICreateUnitOptions} options The options of creating the spreadsheet.
+ * @param {ICreateUnitOptions} [options] The options of creating the spreadsheet.
* @returns {FWorkbook} The spreadsheet API instance.
* @example
* ```ts
@@ -118,13 +118,12 @@ export interface IFUniverSheetsMixin {
/**
* Get the target of the sheet.
- * @param {ICommandInfo<object>} commandInfo - The commandInfo of the command.
- * @returns {Nullable<{ workbook: FWorkbook; worksheet: FWorksheet }>} - The target of the sheet.
+ * @param {{ unitId?: string; subUnitId?: string; sheetId?: string }} [params] Target IDs from the command parameters. Omitted IDs use the current workbook and active sheet.
+ * @returns {{ workbook: FWorkbook; worksheet: FWorksheet; unitId: string; subUnitId: string } | null} The resolved workbook, worksheet, and their IDs, or `null` if the target cannot be resolved.
* @example
* ```ts
* univerAPI.addEvent(univerAPI.Event.CommandExecuted, (event) => {
- * const { options, ...commandInfo } = event;
- * const target = univerAPI.getSheetCommandTarget(commandInfo.params);
+ * const target = univerAPI.getSheetCommandTarget(event.params);
* if (!target) return;
* const { workbook, worksheet } = target;
* console.log(workbook, worksheet);
@@ -226,7 +225,6 @@ export class FUniverSheetsMixin extends FUniver implements IFUniverSheetsMixin {
/**
* @ignore
*/
- // eslint-disable-next-line max-lines-per-function
override _initialize(injector: Injector): void {
const univerInstanceService = injector.get(IUniverInstanceService);
const commandService = injector.get(ICommandService);
@@ -745,6 +743,5 @@ export class FUniverSheetsMixin extends FUniver implements IFUniverSheetsMixin {
FUniver.extend(FUniverSheetsMixin);
declare module '@univerjs/core/facade' {
- // eslint-disable-next-line ts/naming-convention
interface FUniver extends IFUniverSheetsMixin { }
}
diff --git a/packages/sheets/src/facade/f-workbook.ts b/packages/sheets/src/facade/f-workbook.ts
index ad3df1927f..a3aa4c757c 100644
--- a/packages/sheets/src/facade/f-workbook.ts
+++ b/packages/sheets/src/facade/f-workbook.ts
@@ -27,7 +27,6 @@ import type {
} from '@univerjs/core';
import type { ISetDefinedNameMutationParam } from '@univerjs/engine-formula';
import type { IRangeThemeStyleJSON, ISetSelectionsOperationParams, ISheetCommandSharedParams } from '@univerjs/sheets';
-import type { FontLine as _FontLine } from './f-range';
import {
ICommandService,
ILogService,
@@ -107,6 +106,7 @@ export class FWorkbook extends FBaseInitialable {
return this._workbook;
}
+ /** Releases this facade's resources. Use `univerAPI.disposeUnit()` to unload the owning unit. */
override dispose(): void {
super.dispose();
//@ts-ignore
@@ -436,7 +436,7 @@ export class FWorkbook extends FBaseInitialable {
// #region editing
/**
* Undo the last action.
- * @returns {FWorkbook} A promise that resolves to true if the undo was successful, false otherwise.
+ * @returns {FWorkbook} This workbook, for chaining.
* @example
* ```ts
* // The code below undoes the last action
@@ -452,7 +452,7 @@ export class FWorkbook extends FBaseInitialable {
/**
* Redo the last undone action.
- * @returns {FWorkbook} A promise that resolves to true if the redo was successful, false otherwise.
+ * @returns {FWorkbook} This workbook, for chaining.
* @example
* ```ts
* // The code below redoes the last undone action
@@ -471,7 +471,6 @@ export class FWorkbook extends FBaseInitialable {
* @callback onBeforeCommandExecuteCallback
* @param {ICommandInfo<ISheetCommandSharedParams>} command The command that was executed.
*/
-
/**
* Register a callback that will be triggered before invoking a command targeting the Univer sheet.
* @param {onBeforeCommandExecuteCallback} callback the callback.
@@ -500,7 +499,6 @@ export class FWorkbook extends FBaseInitialable {
* @callback onCommandExecutedCallback
* @param {ICommandInfo<ISheetCommandSharedParams>} command The command that was executed
*/
-
/**
* Register a callback that will be triggered when a command is invoked targeting the Univer sheet.
* @param {onCommandExecutedCallback} callback the callback.
@@ -529,7 +527,6 @@ export class FWorkbook extends FBaseInitialable {
* @callback onSelectionChangeCallback
* @param {IRange[]} selections The new selection.
*/
-
/**
* Register a callback that will be triggered when the selection changes.
* @param {onSelectionChangeCallback} callback The callback.
@@ -875,7 +872,7 @@ export class FWorkbook extends FBaseInitialable {
* const definedNameParam = fWorkbook.newDefinedNameBuilder()
* .setRef('Sheet1!$A$1')
* .setName('MyDefinedName')
- * .setComment('This is a comment');
+ * .setComment('This is a comment')
* .build();
* console.log(definedNameParam);
* fWorkbook.insertDefinedNameBuilder(definedNameParam);
@@ -1028,7 +1025,7 @@ export class FWorkbook extends FBaseInitialable {
/**
* Create a range theme style.
* @param {string} themeName - The name of the theme to register
- * @param {Omit<IRangeThemeStyleJSON, 'name'>} themeStyleJson - The theme style json to register
+ * @param {Omit<IRangeThemeStyleJSON, 'name'>} [themeStyleJson] - The theme style json to register
* @returns {RangeThemeStyle} - The created range theme style
* @example
* ```ts
@@ -1160,13 +1157,3 @@ export class FWorkbook extends FBaseInitialable {
this._workbook.removeStyles(styleKeys);
}
}
-
-/**
- * @ignore
- */
-// eslint-disable-next-line ts/no-namespace
-export namespace FWorkbook {
- export type FontLine = _FontLine;
- export type FontStyle = _FontLine;
- export type FontWeight = _FontLine;
-}
diff --git a/packages/sheets/src/facade/f-worksheet.ts b/packages/sheets/src/facade/f-worksheet.ts
index 98b08721a4..3d12f4f5ce 100644
--- a/packages/sheets/src/facade/f-worksheet.ts
+++ b/packages/sheets/src/facade/f-worksheet.ts
@@ -114,7 +114,9 @@ function assertValidRowInsertion(methodName: string, rowIndex: number, rowCount:
}
export interface IFacadeClearOptions {
+ /** Clears only content when true and `formatOnly` is false. */
contentsOnly?: boolean;
+ /** Clears only formatting when true and `contentsOnly` is false. */
formatOnly?: boolean;
}
@@ -145,6 +147,7 @@ export class FWorksheet extends FBaseInitialable {
super(_injector);
}
+ /** Releases this facade's resources. Use `univerAPI.disposeUnit()` to unload the owning unit. */
override dispose(): void {
super.dispose();
//@ts-ignore
@@ -232,7 +235,7 @@ export class FWorksheet extends FBaseInitialable {
/**
* Get the current selection of the worksheet.
- * @returns {FSelection} return the current selections of the worksheet or null if there is no selection.
+ * @returns {FSelection | null} The current selections, or `null` when no selection data is available.
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1');
@@ -256,7 +259,7 @@ export class FWorksheet extends FBaseInitialable {
/**
* Get the default style of the worksheet.
- * @returns {IStyleData} Default style of the worksheet.
+ * @returns {Nullable<IStyleData> | string} The default style object or style ID, or a nullish value when no default style is set.
* @example
* ```typescript
* const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1');
@@ -315,7 +318,7 @@ export class FWorksheet extends FBaseInitialable {
/**
* Set the default style of the worksheet
- * @param {string} style - The style to set
+ * @param {string | Nullable<IStyleData>} style - A style ID or style object, or `null` to clear the default style.
* @returns {FWorksheet} This worksheet instance for chaining
* @example
* ```typescript
@@ -339,8 +342,8 @@ export class FWorksheet extends FBaseInitialable {
}
/**
- * Set the default style of the worksheet row
- * @param {number} index - The row index
+ * Set the default style of the worksheet column
+ * @param {number} index - The zero-based column index
* @param {string | Nullable<IStyleData>} style - The style name or style data
* @returns {FWorksheet} This sheet, for chaining.
* @example
@@ -372,8 +375,8 @@ export class FWorksheet extends FBaseInitialable {
}
/**
- * Set the default style of the worksheet column
- * @param {number} index - The column index
+ * Set the default style of the worksheet row
+ * @param {number} index - The zero-based row index
* @param {string | Nullable<IStyleData>} style - The style name or style data
* @returns {FWorksheet} This sheet, for chaining.
* @example
@@ -589,7 +592,7 @@ export class FWorksheet extends FBaseInitialable {
/**
* Inserts one or more consecutive blank rows in a sheet starting at the specified location.
* @param {number} rowIndex - The existing row before which rows are inserted. The index is zero-based and must be between 0 and `getMaxRows() - 1`.
- * @param {number} numRows - The positive number of rows to insert.
+ * @param {number} [numRows] - The positive number of rows to insert.
* @returns {FWorksheet} This sheet, for chaining.
* @example
* ```typescript
@@ -841,7 +844,7 @@ export class FWorksheet extends FBaseInitialable {
/**
* Hides one or more consecutive rows starting at the given index. Use 0-index for this method
* @param {number} rowIndex - The starting index of the rows to hide
- * @param {number} numRow - The number of rows to hide
+ * @param {number} [numRow] - The number of rows to hide
* @returns {FWorksheet} This sheet, for chaining.
* @example
* ```typescript
@@ -903,9 +906,9 @@ export class FWorksheet extends FBaseInitialable {
}
/**
- * Scrolling sheet to make specific rows visible.
+ * Unhides one or more consecutive rows starting at the given zero-based index.
* @param {number} rowIndex - The starting index of the rows
- * @param {number} numRows - The number of rows
+ * @param {number} [numRows] - The number of rows
* @returns {FWorksheet} This worksheet instance for chaining
* @example
* ```typescript
@@ -959,7 +962,7 @@ export class FWorksheet extends FBaseInitialable {
/**
* Make certain row wrap and auto height.
* @param {number} rowPosition - The row position to change.
- * @param {BooleanNumber} auto - Whether to auto fit the row height.
+ * @param {BooleanNumber} [auto] - Whether to auto fit the row height.
* @returns {FWorksheet} This worksheet instance for chaining
* @example
* ```ts
@@ -1246,7 +1249,7 @@ export class FWorksheet extends FBaseInitialable {
/**
* Inserts one or more consecutive blank columns in a sheet starting at the specified location.
* @param {number} columnIndex - The index indicating where to insert a column, starting at 0 for the first column
- * @param {number} numColumns - The number of columns to insert
+ * @param {number} [numColumns] - The number of columns to insert
* @returns {FWorksheet} This sheet, for chaining
* @example
* ```typescript
@@ -1493,7 +1496,7 @@ export class FWorksheet extends FBaseInitialable {
/**
* Hides one or more consecutive columns starting at the given index. Use 0-index for this method
* @param {number} columnIndex - The starting index of the columns to hide
- * @param {number} numColumn - The number of columns to hide
+ * @param {number} [numColumn] - The number of columns to hide
* @returns {FWorksheet} This sheet, for chaining
* @example
* ```typescript
@@ -1558,7 +1561,7 @@ export class FWorksheet extends FBaseInitialable {
/**
* Show one or more consecutive columns starting at the given index. Use 0-index for this method
* @param {number} columnIndex - The starting index of the columns to unhide
- * @param {number} numColumns - The number of columns to unhide
+ * @param {number} [numColumns] - The number of columns to unhide
* @returns {FWorksheet} This sheet, for chaining
* @example
* ```typescript
@@ -1658,7 +1661,7 @@ export class FWorksheet extends FBaseInitialable {
* fRange.setValue('Whenever it is a damp, drizzly November in my soul...');
*
* // Set the column A to a width which fits the text
- * fWorksheet.autoResizeColumn(0);
+ * fWorksheet.autoResizeColumns(0);
*
* // Get the width of the column A
* console.log(fWorksheet.getColumnWidth(0));
@@ -2172,7 +2175,7 @@ export class FWorksheet extends FBaseInitialable {
/**
* Sets the sheet tab color.
- * @param {string|null|undefined} color - A color code in CSS notation (like '#ffffff' or 'white'), or null to reset the tab color.
+ * @param {string} color - A color in CSS notation, such as '#ffffff' or 'white'.
* @returns {FWorksheet} Returns the current worksheet instance for method chaining
* @example
* ```ts
@@ -2194,8 +2197,7 @@ export class FWorksheet extends FBaseInitialable {
/**
* Get the tab color of the sheet.
- * @returns {string} The tab color of the sheet or undefined.
- * The default color is css style property 'unset'.
+ * @returns {string | undefined} The tab color, or `undefined` when no color is set.
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
@@ -2330,10 +2332,11 @@ export class FWorksheet extends FBaseInitialable {
}
/**
- * Clears the sheet of content and formatting information.Or Optionally clears only the contents or only the formatting.
+ * Clears the sheet content and formatting, or only one of them as specified by the options.
+ * Both content and formatting are cleared when both flags are true or both are false.
* @param {IFacadeClearOptions} [options] - Options for clearing the sheet. If not provided, the contents and formatting are cleared both.
- * @param {boolean} [options.contentsOnly] - If true, the contents of the sheet are cleared. If false, the contents and formatting are cleared. Default is false.
- * @param {boolean} [options.formatOnly] - If true, the formatting of the sheet is cleared. If false, the contents and formatting are cleared. Default is false.
+ * @param {boolean} [options.contentsOnly] - If true, the contents of the sheet are cleared. Effective only when `formatOnly` is false. Defaults to false.
+ * @param {boolean} [options.formatOnly] - Clears only formatting when true and `contentsOnly` is false. Defaults to false.
* @returns {FWorksheet} Returns the current worksheet instance for method chaining
* @example
* ```ts
@@ -2461,8 +2464,8 @@ export class FWorksheet extends FBaseInitialable {
}
/**
- * Returns the column index of the last column that contains content.
- * @returns {number} the column index of the last column that contains content.
+ * Returns the zero-based index of the last column with stored cell data, including formatting-only cells.
+ * @returns {number} The last stored column index, or 0 for an empty sheet.
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
@@ -2479,8 +2482,8 @@ export class FWorksheet extends FBaseInitialable {
}
/**
- * Returns the row index of the last row that contains content.
- * @returns {number} the row index of the last row that contains content.
+ * Returns the zero-based index of the last row with stored cell data, including formatting-only cells.
+ * @returns {number} The last stored row index, or 0 for an empty sheet.
* @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.ts
index 93f45e5680..f0bc87546d 100644
--- a/packages/sheets/src/facade/permission/f-range-permission.ts
+++ b/packages/sheets/src/facade/permission/f-range-permission.ts
@@ -73,7 +73,7 @@ export class FRangePermission extends FBase {
/**
* Protect the current range.
- * @param {IRangeProtectionOptions} options Protection options.
+ * @param {IRangeProtectionOptions} [options] Protection options.
* @returns {Promise<FRangeProtectionRule>} The created protection rule.
* @example
* ```ts
@@ -89,7 +89,6 @@ export class FRangePermission extends FBase {
* console.log(rule);
* ```
*/
-
async protect(options?: IRangeProtectionOptions): Promise<FRangeProtectionRule> {
if (this.isProtected()) {
throw new Error('Range is already protected');
diff --git a/packages/sheets/src/facade/permission/f-range-protection-rule.ts b/packages/sheets/src/facade/permission/f-range-protection-rule.ts
index 4132c98d45..05f2e29c34 100644
--- a/packages/sheets/src/facade/permission/f-range-protection-rule.ts
+++ b/packages/sheets/src/facade/permission/f-range-protection-rule.ts
@@ -76,7 +76,7 @@ export class FRangeProtectionRule {
/**
* Update the protected ranges.
* @param {FRange[]} ranges New ranges to protect.
- * @returns {Promise<void>} A promise that resolves when the ranges are updated.
+ * @returns {Promise<boolean>} A promise resolving to whether the protected ranges were updated.
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
@@ -138,7 +138,7 @@ export class FRangeProtectionRule {
/**
* Delete the current protection rule.
- * @returns {Promise<void>} A promise that resolves when the rule is removed.
+ * @returns {Promise<boolean>} A promise resolving to whether the rule was removed.
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
diff --git a/packages/sheets/src/facade/permission/f-workbook-permission.ts b/packages/sheets/src/facade/permission/f-workbook-permission.ts
index 04edb968f7..c220e12360 100644
--- a/packages/sheets/src/facade/permission/f-workbook-permission.ts
+++ b/packages/sheets/src/facade/permission/f-workbook-permission.ts
@@ -244,7 +244,7 @@ export class FWorkbookPermission extends FBase {
/**
* Set multiple collaborators at once (replaces existing collaborators).
- * @param {Array<{ user: IUser; role: UnitRole }>} collaborators Array of collaborators with user information and role.
+ * @param {Array<{ user: ICollaboratorUser; role: UnitRole }>} collaborators Array of collaborators with user information and role.
* @returns {Promise<void>} A promise that resolves when the collaborators are set.
* @example
* ```ts
@@ -280,7 +280,7 @@ export class FWorkbookPermission extends FBase {
/**
* Add a single collaborator.
- * @param {IUser} user The user information (userID, name, avatar).
+ * @param {ICollaboratorUser} user The user information (userID, name, avatar).
* @param {UnitRole} role The role to assign.
* @returns {Promise<void>} A promise that resolves when the collaborator is added.
* @example
@@ -307,7 +307,7 @@ export class FWorkbookPermission extends FBase {
/**
* Update an existing collaborator's role and information.
- * @param {IUser} user The updated user information (userID, name, avatar).
+ * @param {ICollaboratorUser} user The updated user information (userID, name, avatar).
* @param {UnitRole} role The new role to assign.
* @returns {Promise<void>} A promise that resolves when the collaborator is updated.
* @example
diff --git a/packages/sheets/src/facade/permission/f-worksheet-permission.ts b/packages/sheets/src/facade/permission/f-worksheet-permission.ts
index 743becdfc9..d1ca434bbe 100644
--- a/packages/sheets/src/facade/permission/f-worksheet-permission.ts
+++ b/packages/sheets/src/facade/permission/f-worksheet-permission.ts
@@ -116,7 +116,7 @@ export class FWorksheetPermission extends FBase {
/**
* Create worksheet protection with collaborators support.
* This must be called before setting permission points for collaboration to work.
- * @param {IWorksheetProtectionOptions} options Protection options including allowed users.
+ * @param {IWorksheetProtectionOptions} [options] Protection options including allowed users.
* @returns {Promise<string>} The permissionId for the created protection.
* @example
* ```ts
@@ -206,7 +206,7 @@ export class FWorksheetPermission extends FBase {
/**
* Remove worksheet protection.
* This deletes the protection rule and resets all permission points to allowed.
- * @returns {Promise<void>} A promise that resolves when protection is removed.
+ * @returns {Promise<boolean>} A promise resolving to whether protection was removed; also resolves to `true` if already unprotected.
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
@@ -613,7 +613,6 @@ export class FWorksheetPermission extends FBase {
* console.log(rules);
* ```
*/
- // eslint-disable-next-line max-lines-per-function
async protectRanges(
configs: Array<{
ranges: FRange[];
@@ -733,7 +732,7 @@ export class FWorksheetPermission extends FBase {
/**
* Remove multiple protection rules at once.
* @param {string[]} ruleIds Array of rule IDs to remove.
- * @returns {Promise<void>} A promise that resolves when the rules are removed.
+ * @returns {Promise<boolean>} A promise resolving to whether the rules were removed; also resolves to `true` for an empty ID list.
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
@@ -800,7 +799,7 @@ export class FWorksheetPermission extends FBase {
* Debug cell permission information.
* @param {number} row Row index.
* @param {number} col Column index.
- * @returns {FRangeProtectionRule | undefined} Debug information about which rules affect this cell, or null if no rules apply.
+ * @returns {Promise<FRangeProtectionRule | undefined>} A promise resolving to the protection rule affecting this cell, or `undefined` if no range protection rule applies.
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
diff --git a/packages/thread-comment/src/facade/f-univer.ts b/packages/thread-comment/src/facade/f-univer.ts
index 37e1c8a6ae..5d8076e458 100644
--- a/packages/thread-comment/src/facade/f-univer.ts
+++ b/packages/thread-comment/src/facade/f-univer.ts
@@ -20,25 +20,29 @@ import * as ThreadComment from '@univerjs/thread-comment';
export interface IFUniverThreadCommentMixin {
/**
- * Creates a root comment on a serialized product anchor.
+ * Creates a root comment on a drawing, page element, page position, or Base record anchor.
+ * For a sheet-cell comment, use `FRange.addCommentAsync`; for document text, use `FDocumentTextRange.createCommentAsync`.
* @param options Comment content, owner IDs, stable anchor, and optional caller-controlled IDs.
- * @returns `true` when the command succeeds; otherwise, `false`.
+ * @returns {Promise<boolean>} `true` when the command succeeds; otherwise, `false`.
* @throws {TypeError} If the content is empty or the anchor is invalid.
* @example
* ```ts
- * const presentation = univerAPI.getActivePresentation();
- * if (!presentation) throw new Error('No active presentation');
- * const slide = presentation.getSlideByIndex(0);
- * const element = slide?.getElements()[0];
- * if (!slide || !element) throw new Error('No commentable slide element');
+ * const workbook = univerAPI.getActiveWorkbook();
+ * if (!workbook) {
+ * throw new Error('No active workbook');
+ * }
+ * const sheet = workbook.getActiveSheet();
+ * const image = sheet.getImages()[0];
+ * if (!image) {
+ * throw new Error('No image to comment on');
+ * }
*
* await univerAPI.createCommentAsync({
- * unitId: presentation.getId(),
- * subUnitId: slide.getId(),
+ * unitId: workbook.getId(),
+ * subUnitId: sheet.getSheetId(),
* anchor: {
- * kind: univerAPI.Enum.ThreadCommentAnchorKind.SLIDE_ELEMENT,
- * pageId: slide.getId(),
- * elementId: element.getId(),
+ * kind: univerAPI.Enum.ThreadCommentAnchorKind.SHEET_DRAWING,
+ * elementId: image.getId(),
* },
* content: 'Verify this value.',
* });
@@ -48,7 +52,7 @@ export interface IFUniverThreadCommentMixin {
/**
* Adds a reply to an existing root thread.
* @param options Reply content and the owning unit, subunit, and thread IDs.
- * @returns `true` when the reply is created. Returns `false` when the root thread is not loaded or the command fails.
+ * @returns {Promise<boolean>} `true` when the reply is created. Returns `false` when the root thread is not loaded or the command fails.
* @throws {TypeError} If the content is empty.
* @example
* ```ts
@@ -67,7 +71,7 @@ export interface IFUniverThreadCommentMixin {
/**
* Updates the content or attachments of an existing root comment or reply.
* @param options Updated content and the owning unit, subunit, and comment IDs.
- * @returns `true` when the update command succeeds; otherwise, `false`.
+ * @returns {Promise<boolean>} `true` when the update command succeeds; otherwise, `false`.
* @throws {TypeError} If the content is empty.
* @example
* ```ts
@@ -86,7 +90,7 @@ export interface IFUniverThreadCommentMixin {
/**
* Deletes one comment, or the complete root and reply tree when `deleteThread` is `true`.
* @param options Owning IDs, target comment ID, and the optional whole-thread flag.
- * @returns `true` when the delete command succeeds; otherwise, `false`.
+ * @returns {Promise<boolean>} `true` when the delete command succeeds; otherwise, `false`.
* @example
* ```ts
* const [comment] = univerAPI.getComments({ resolved: false });
@@ -104,7 +108,7 @@ export interface IFUniverThreadCommentMixin {
/**
* Resolves a thread. Pass `resolved: false` to reopen it.
* @param options Owning IDs, a comment ID in the thread, and the desired resolution state.
- * @returns `true` when the resolve command succeeds; otherwise, `false`.
+ * @returns {Promise<boolean>} `true` when the resolve command succeeds; otherwise, `false`.
* @example
* ```ts
* const [comment] = univerAPI.getComments({ resolved: false });
@@ -120,15 +124,18 @@ export interface IFUniverThreadCommentMixin {
resolveCommentAsync(options: ThreadComment.IResolveThreadCommentOptions): Promise<boolean>;
/**
* Queries locally loaded threads by unit, subunit, anchor kind, author, or resolution state.
- * @param query Optional filters. Omit the argument to return every locally loaded thread.
+ * @param [query] Optional filters. Omit the argument to return every locally loaded thread.
* @returns Matching root threads, their replies, anchor kinds, parsed anchors, and related user IDs.
* @example
* ```ts
- * const presentation = univerAPI.getActivePresentation();
+ * const workbook = univerAPI.getActiveWorkbook();
+ * if (!workbook) {
+ * throw new Error('No active workbook');
+ * }
* const openAgentReviews = univerAPI.getComments({
- * unitIds: presentation ? [presentation.getId()] : [],
+ * unitIds: [workbook.getId()],
* authorIds: ['agent-reviewer'],
- * anchorKinds: [univerAPI.Enum.ThreadCommentAnchorKind.SLIDE_ELEMENT],
+ * anchorKinds: [univerAPI.Enum.ThreadCommentAnchorKind.SHEET_DRAWING],
* resolved: false,
* });
* const sheetCellReviews = univerAPI.getComments({
@@ -140,14 +147,17 @@ export interface IFUniverThreadCommentMixin {
/**
* Synchronizes locally known threads from the configured datasource, then applies the same filters as `getComments`.
* This method does not discover thread IDs that have never been loaded into the model.
- * @param query Optional filters. Omit the argument to synchronize and return every known thread.
- * @returns A promise resolving to the synchronized matching threads.
+ * @param [query] Optional filters. Omit the argument to synchronize and return every known thread.
+ * @returns {Promise<ThreadComment.IFacadeThreadCommentInfo[]>} A promise resolving to the synchronized matching threads.
* @example
* ```ts
- * const presentation = univerAPI.getActivePresentation();
+ * const workbook = univerAPI.getActiveWorkbook();
+ * if (!workbook) {
+ * throw new Error('No active workbook');
+ * }
* const comments = await univerAPI.listCommentsAsync({
- * unitIds: presentation ? [presentation.getId()] : [],
- * anchorKinds: [univerAPI.Enum.ThreadCommentAnchorKind.SLIDE_ELEMENT],
+ * unitIds: [workbook.getId()],
+ * anchorKinds: [univerAPI.Enum.ThreadCommentAnchorKind.SHEET_DRAWING],
* resolved: false,
* });
* comments.forEach(({ root, children, anchorKind, anchor }) => {
diff --git a/packages/ui/src/facade/f-univer.ts b/packages/ui/src/facade/f-univer.ts
index a0593a18b8..a77475d9dd 100644
--- a/packages/ui/src/facade/f-univer.ts
+++ b/packages/ui/src/facade/f-univer.ts
@@ -144,7 +144,7 @@ export interface IFUniverUIMixin {
* @param {IFacadeMenuItem} menuItem the menu item
* @returns the {@link FMenu} object
* @example
- * ```ts
+ * ```tsx
* // Univer Icon can be viewed at https://docs.univer.ai/icons
* import { SmileIcon } from '@univerjs/icons'
*
@@ -256,7 +256,7 @@ export interface IFUniverUIMixin {
* @param {IDialogPartMethodOptions} dialog the dialog options
* @returns {IDisposable} the disposable object
* @example
- * ```ts
+ * ```tsx
* import { Button } from '@univerjs/design';
*
* univerAPI.openDialog({
@@ -298,6 +298,7 @@ export interface IFUniverUIMixin {
/**
* Show a message.
* @returns {FUniver} the {@link FUniver} instance for chaining
+ * @param {IMessageProps} options Message content, type, duration, and other display options.
* @example
* ```ts
* univerAPI.showMessage({
@@ -325,7 +326,7 @@ export interface IFUniverUIMixin {
* @param {BuiltInUIPart} key the built-in UI part
* @param {boolean} visible the visibility
* @returns the {@link FUniver} instance for chaining
- * example
+ * @example
* ```ts
* // Hide header, footer, and toolbar
* univerAPI.setUIVisible(univerAPI.Enum.BuiltInUIPart.HEADER, false)
@@ -373,7 +374,7 @@ export interface IFUniverUIMixin {
* @param {IComponentOptions} [options] - The options of the component.
* @returns {IDisposable} The disposable object.
* @example
- * ```ts
+ * ```tsx
* const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1');
* if (!fWorksheet) return;
*
@@ -551,6 +552,5 @@ export class FUniverUIMixin extends FUniver implements IFUniverUIMixin {
FUniver.extend(FUniverUIMixin);
declare module '@univerjs/core/facade' {
- // eslint-disable-next-line ts/naming-convention
interface FUniver extends IFUniverUIMixin { }
}
diff --git a/packages/watermark/src/facade/f-univer.ts b/packages/watermark/src/facade/f-univer.ts
index 6ede922495..3186a69d66 100644
--- a/packages/watermark/src/facade/f-univer.ts
+++ b/packages/watermark/src/facade/f-univer.ts
@@ -20,6 +20,7 @@ import { IWatermarkTypeEnum } from '@univerjs/engine-render';
import { WatermarkImageBaseConfig, WatermarkService, WatermarkTextBaseConfig } from '@univerjs/watermark';
interface IFWatermarkEnumMixin {
+ /** Text and image watermark types accepted by `addWatermark`. */
IWatermarkTypeEnum: typeof IWatermarkTypeEnum;
}
@@ -130,9 +131,7 @@ FUniver.extend(FUniverWatermarkMixin);
FEnum.extend(FWatermarkEnumMixin);
declare module '@univerjs/core/facade' {
- // eslint-disable-next-line ts/naming-convention
interface FUniver extends IFUniverWatermarkMixin { }
- // eslint-disable-next-line ts/naming-convention
export interface FEnum extends IFWatermarkEnumMixin {
}
}