Build your own AI office with Univer Office SDK. Bring editing, calculation, collaboration, and file processing into your product for people and AI agents. Built on an extensible open-source core.
TypeScript boardcollaborationdocdocxexceloffce365officepdfpptpptxpresentationsdksheetslidesspreadsheetuniverwordwordprocessorworkspacexlsx
docs(facade): supplement notes and example (#4713)
wpxp123456da83f66f93d8
diff --git a/examples/src/sheets/main.ts b/examples/src/sheets/main.tsindex 00a33f54a3..83fb3188dd 100644--- a/examples/src/sheets/main.ts+++ b/examples/src/sheets/main.ts@@ -467,8 +467,8 @@ function initEvent() {});// checked- window.univerAPI?.addEvent(window.univerAPI.Event.BeforeCommentDeleted, (params) => {- logService.log('===BeforeCommentDeleted', params);+ window.univerAPI?.addEvent(window.univerAPI.Event.BeforeCommentDelete, (params) => {+ logService.log('===BeforeCommentDelete', params);});// checkeddiff --git a/packages/docs-ui/src/views/rich-text-editor/hooks/use-editor.ts b/packages/docs-ui/src/views/rich-text-editor/hooks/use-editor.tsindex 238f9d94a0..8a680eaf37 100644--- a/packages/docs-ui/src/views/rich-text-editor/hooks/use-editor.ts+++ b/packages/docs-ui/src/views/rich-text-editor/hooks/use-editor.ts@@ -17,6 +17,7 @@import type { IDocumentData, Nullable } from '@univerjs/core';import type { RefObject } from 'react';import type { Editor } from '../../../services/editor/editor';+import { Tools } from '@univerjs/core';import { useDependency } from '@univerjs/ui';import { useLayoutEffect, useMemo, useState } from 'react';import { IEditorService } from '../../../services/editor/editor-manager.service';@@ -37,6 +38,8 @@ export function useEditor(opts: IUseEditorProps) {useLayoutEffect(() => {if (container.current) {+ const _initialValue = Tools.deepClone(initialValue);+const snapshot: IDocumentData = {body: {dataStream: '\r\n',@@ -48,9 +51,9 @@ export function useEditor(opts: IUseEditorProps) {startIndex: 0,}],},- ...initialValue,+ ..._initialValue,documentStyle: {- ...initialValue?.documentStyle,+ ..._initialValue?.documentStyle,pageSize: {width: !isSingle ? container.current.clientWidth : Infinity,height: Infinity,diff --git a/packages/sheets-sort/src/facade/f-range.ts b/packages/sheets-sort/src/facade/f-range.tsindex ce8cf9a92e..707215d8b4 100644--- a/packages/sheets-sort/src/facade/f-range.ts+++ b/packages/sheets-sort/src/facade/f-range.ts@@ -26,16 +26,22 @@ export type SortColumnSpec = { column: number; ascending: boolean } | number;export interface IFRangeSort {/*** Sorts the cells in the given range, by column(s) and order specified.- * @param {SortColumnSpec | SortColumnSpec[]} column The column index with order or an array of column indexes with order. The column index starts from 1.- * @returns The range itself for chaining.+ * @param {SortColumnSpec | SortColumnSpec[]} column The column index with order or an array of column indexes with order. The range first column index is 0.+ * @returns {FRange} The range itself for chaining.* @example* ```typescript- * const activeSpreadsheet = univerAPI.getActiveWorkbook();- * const activeSheet = activeSpreadsheet.getActiveSheet();- * const range = activeSheet.getRange(0, 0, 10, 10);- * range.sort(1); // Sorts the range by the first column in ascending order.- * range.sort({ column: 1, ascending: false }); // Sorts the range by the first column in descending order.- * range.sort([{ column: 1, ascending: false }, 2]); // Sorts the range by the first column in descending order and the second column in ascending order.+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * const fWorksheet = fWorkbook.getActiveSheet();+ * const fRange = fWorksheet.getRange('D1:G10');+ *+ * // Sorts the range by the first column in ascending order.+ * fRange.sort(0);+ *+ * // Sorts the range by the first column in descending order.+ * fRange.sort({ column: 0, ascending: false });+ *+ * // Sorts the range by the first column in descending order and the second column in ascending order.+ * fRange.sort([{ column: 0, ascending: false }, 1]);* ```*/sort(column: SortColumnSpec | SortColumnSpec[]): FRange;diff --git a/packages/sheets-sort/src/facade/f-worksheet.ts b/packages/sheets-sort/src/facade/f-worksheet.tsindex 14981a0d87..b24c4a334a 100644--- a/packages/sheets-sort/src/facade/f-worksheet.ts+++ b/packages/sheets-sort/src/facade/f-worksheet.ts@@ -27,7 +27,7 @@ export interface IFWorksheetSort {/*** Sort the worksheet by the specified column.* @param {number} colIndex The column index to sort by.- * @param {boolean} [asc=true] The sort order. `true` for ascending, `false` for descending.+ * @param {boolean} [asc=true] The sort order. `true` for ascending, `false` for descending. The column A index is 0.* @returns {FWorksheet} The worksheet itself for chaining.* @example* ```typescript@@ -47,7 +47,6 @@ export interface IFWorksheetSort {export class FWorksheetSort extends FWorksheet implements IFWorksheetSort {override sort(colIndex: number, asc = true): FWorksheet {const orderRules: IOrderRule[] = [{- // real column index should be colIndex - 1.colIndex,type: asc ? SortType.ASC : SortType.DESC,}];diff --git a/packages/sheets-thread-comment/src/facade/f-event.ts b/packages/sheets-thread-comment/src/facade/f-event.tsindex 387b48e746..76a87abd8f 100644--- a/packages/sheets-thread-comment/src/facade/f-event.ts+++ b/packages/sheets-thread-comment/src/facade/f-event.ts@@ -29,10 +29,12 @@ interface ICommentEventMixin {* @see {@link ISheetCommentAddEvent}* @example* ```ts- * univerAPI.addEventListener(CommentEvent.CommentAdded, (event) => {- * const { comment, workbook, worksheet, row, col } = event;- * console.log(event);+ * const disposable = univerAPI.addEvent(univerAPI.Event.CommentAdded, (params) => {+ * const { comment, workbook, worksheet, row, col } = params;+ * console.log(params);* });+ *+ * // Remove the event listener, use `disposable.dispose()`* ```*/readonly CommentAdded: 'CommentAdded';@@ -42,10 +44,15 @@ interface ICommentEventMixin {* @see {@link IBeforeSheetCommentAddEvent}* @example* ```ts- * univerAPI.addEventListener(CommentEvent.BeforeCommentAdd, (event) => {- * const { comment, workbook, worksheet, row, col } = event;- * console.log(event);+ * const disposable = univerAPI.addEvent(univerAPI.Event.BeforeCommentAdd, (params) => {+ * const { comment, workbook, worksheet, row, col } = params;+ * console.log(params);+ *+ * // Cancel the comment add operation+ * params.cancel = true;* });+ *+ * // Remove the event listener, use `disposable.dispose()`* ```*/readonly BeforeCommentAdd: 'BeforeCommentAdd';@@ -55,10 +62,12 @@ interface ICommentEventMixin {* @see {@link ISheetCommentUpdateEvent}* @example* ```ts- * univerAPI.addEventListener(CommentEvent.CommentUpdated, (event) => {- * const { comment, workbook, worksheet, row, col } = event;- * console.log(event);+ * const disposable = univerAPI.addEvent(univerAPI.Event.CommentUpdated, (params) => {+ * const { comment, workbook, worksheet, row, col } = params;+ * console.log(params);* });+ *+ * // Remove the event listener, use `disposable.dispose()`* ```*/readonly CommentUpdated: 'CommentUpdated';@@ -68,10 +77,15 @@ interface ICommentEventMixin {* @see {@link IBeforeSheetCommentUpdateEvent}* @example* ```ts- * univerAPI.addEventListener(CommentEvent.BeforeCommentUpdate, (event) => {- * const { comment, workbook, worksheet, row, col, newContent } = event;- * console.log(event);+ * const disposable = univerAPI.addEvent(univerAPI.Event.BeforeCommentUpdate, (params) => {+ * const { comment, workbook, worksheet, row, col, newContent } = params;+ * console.log(params);+ *+ * // Cancel the comment update operation+ * params.cancel = true;* });+ *+ * // Remove the event listener, use `disposable.dispose()`* ```*/readonly BeforeCommentUpdate: 'BeforeCommentUpdate';@@ -81,10 +95,12 @@ interface ICommentEventMixin {* @see {@link ISheetCommentDeleteEvent}* @example* ```ts- * univerAPI.addEventListener(CommentEvent.CommentDeleted, (event) => {- * const { commentId, workbook, worksheet } = event;- * console.log(event);+ * const disposable = univerAPI.addEvent(univerAPI.Event.CommentDeleted, (params) => {+ * const { commentId, workbook, worksheet } = params;+ * console.log(params);* });+ *+ * // Remove the event listener, use `disposable.dispose()`* ```*/readonly CommentDeleted: 'CommentDeleted';@@ -94,23 +110,30 @@ interface ICommentEventMixin {* @see {@link IBeforeSheetCommentDeleteEvent}* @example* ```ts- * univerAPI.addEventListener(CommentEvent.BeforeCommentDeleted, (event) => {- * const { commentId, workbook, worksheet } = event;- * console.log(event);+ * const disposable = univerAPI.addEvent(univerAPI.Event.BeforeCommentDelete, (params) => {+ * const { comment, workbook, worksheet, row, col } = params;+ * console.log(params);+ *+ * // Cancel the comment delete operation+ * params.cancel = true;* });+ *+ * // Remove the event listener, use `disposable.dispose()`* ```*/- readonly BeforeCommentDeleted: 'BeforeCommentDeleted';+ readonly BeforeCommentDelete: 'BeforeCommentDelete';/*** Event fired after comment resolve* @see {@link ISheetCommentResolveEvent}* @example* ```ts- * univerAPI.addEventListener(CommentEvent.CommentResolved, (event) => {- * const { comment, row, col, resolved, workbook, worksheet } = event;- * console.log(event);+ * const disposable = univerAPI.addEvent(univerAPI.Event.CommentResolved, (params) => {+ * const { comment, row, col, resolved, workbook, worksheet } = params;+ * console.log(params);* });+ *+ * // Remove the event listener, use `disposable.dispose()`* ```*/readonly CommentResolved: 'CommentResolved';@@ -120,10 +143,15 @@ interface ICommentEventMixin {* @see {@link ISheetCommentResolveEvent}* @example* ```ts- * univerAPI.addEventListener(CommentEvent.BeforeCommentResolve, (event) => {- * const { comment, row, col, resolved, workbook, worksheet } = event;- * console.log(event);+ * const disposable = univerAPI.addEvent(univerAPI.Event.BeforeCommentResolve, (params) => {+ * const { comment, row, col, resolved, workbook, worksheet } = params;+ * console.log(params);+ *+ * // Cancel the comment resolve operation+ * params.cancel = true;* });+ *+ * // Remove the event listener, use `disposable.dispose()`* ```*/readonly BeforeCommentResolve: 'BeforeCommentResolve';@@ -137,7 +165,7 @@ const CommentEvent: ICommentEventMixin = {BeforeCommentUpdate: 'BeforeCommentUpdate',CommentDeleted: 'CommentDeleted',- BeforeCommentDeleted: 'BeforeCommentDeleted',+ BeforeCommentDelete: 'BeforeCommentDelete',CommentResolved: 'CommentResolved',BeforeCommentResolve: 'BeforeCommentResolve',@@ -167,8 +195,8 @@ export class FCommentEvent extends FEventName {return CommentEvent.CommentDeleted;}- override get BeforeCommentDeleted(): 'BeforeCommentDeleted' {- return CommentEvent.BeforeCommentDeleted;+ override get BeforeCommentDelete(): 'BeforeCommentDelete' {+ return CommentEvent.BeforeCommentDelete;}override get CommentResolved(): 'CommentResolved' {@@ -318,7 +346,7 @@ export interface ISheetCommentEventConfig {BeforeCommentUpdate: IBeforeSheetCommentUpdateEvent;CommentUpdated: ISheetCommentUpdateEvent;- BeforeCommentDeleted: IBeforeSheetCommentDeleteEvent;+ BeforeCommentDelete: IBeforeSheetCommentDeleteEvent;CommentDeleted: ISheetCommentDeleteEvent;BeforeCommentResolve: ISheetCommentResolveEvent;diff --git a/packages/sheets-thread-comment/src/facade/f-range.ts b/packages/sheets-thread-comment/src/facade/f-range.tsindex 0026387989..e61eb7ac44 100644--- a/packages/sheets-thread-comment/src/facade/f-range.ts+++ b/packages/sheets-thread-comment/src/facade/f-range.ts@@ -14,8 +14,9 @@* limitations under the License.*/+import type { IDocumentBody, Nullable } from '@univerjs/core';import type { IThreadComment } from '@univerjs/thread-comment';-import { generateRandomId, ICommandService, type IDocumentBody, type Nullable, Range, Tools, UserManagerService } from '@univerjs/core';+import { generateRandomId, ICommandService, Range, Tools, UserManagerService } from '@univerjs/core';import { SheetsThreadCommentModel } from '@univerjs/sheets-thread-comment';import { FRange } from '@univerjs/sheets/facade';import { AddCommentCommand, DeleteCommentTreeCommand, getDT } from '@univerjs/thread-comment';diff --git a/packages/sheets-thread-comment/src/facade/f-thread-comment.ts b/packages/sheets-thread-comment/src/facade/f-thread-comment.tsindex f331b759ba..469ca5eb86 100644--- a/packages/sheets-thread-comment/src/facade/f-thread-comment.ts+++ b/packages/sheets-thread-comment/src/facade/f-thread-comment.ts@@ -45,7 +45,8 @@ export class FTheadCommentItem {* @returns {FTheadCommentItem} A new instance of FTheadCommentItem* @example* ```ts- * const comment = univerAPI.newTheadComment();+ * const commentBuilder = univerAPI.newTheadComment();+ * console.log(commentBuilder);* ```*/static create(comment?: IThreadComment): FTheadCommentItem {@@ -63,10 +64,8 @@ export class FTheadCommentItem {* @returns {string} The person id of the comment* @example* ```ts- * const comment = univerAPI.getActiveWorkbook()- * .getSheetById(sheetId)- * .getCommentById(commentId);- * const personId = comment.personId;+ * const commentBuilder = univerAPI.newTheadComment();+ * console.log(commentBuilder.personId);* ```*/get personId(): string {@@ -78,10 +77,8 @@ export class FTheadCommentItem {* @returns {string} The date time of the comment* @example* ```ts- * const comment = univerAPI.getActiveWorkbook()- * .getSheetById(sheetId)- * .getCommentById(commentId);- * const dateTime = comment.dateTime;+ * const commentBuilder = univerAPI.newTheadComment();+ * console.log(commentBuilder.dateTime);* ```*/get dateTime(): string {@@ -93,10 +90,8 @@ export class FTheadCommentItem {* @returns {RichTextValue} The content of the comment* @example* ```ts- * const comment = univerAPI.getActiveWorkbook()- * .getSheetById(sheetId)- * .getCommentById(commentId);- * const content = comment.content;+ * const commentBuilder = univerAPI.newTheadComment();+ * console.log(commentBuilder.content);* ```*/get content(): RichTextValue {@@ -108,10 +103,8 @@ export class FTheadCommentItem {* @returns {string} The id of the comment* @example* ```ts- * const comment = univerAPI.getActiveWorkbook()- * .getSheetById(sheetId)- * .getCommentById(commentId);- * const id = comment.id;+ * const commentBuilder = univerAPI.newTheadComment();+ * console.log(commentBuilder.id);* ```*/get id(): string {@@ -123,10 +116,8 @@ export class FTheadCommentItem {* @returns {string} The thread id of the comment* @example* ```ts- * const comment = univerAPI.getActiveWorkbook()- * .getSheetById(sheetId)- * .getCommentById(commentId);- * const threadId = comment.threadId;+ * const commentBuilder = univerAPI.newTheadComment();+ * console.log(commentBuilder.threadId);* ```*/get threadId(): string {@@ -138,10 +129,9 @@ export class FTheadCommentItem {* @returns {FTheadCommentBuilder} The comment builder* @example* ```ts- * const comment = univerAPI.getActiveWorkbook()- * .getSheetById(sheetId)- * .getCommentById(commentId);- * const newComment = comment.copy();+ * const commentBuilder = univerAPI.newTheadComment();+ * const newCommentBuilder = commentBuilder.copy();+ * console.log(newCommentBuilder);* ```*/copy(): FTheadCommentBuilder {@@ -160,11 +150,21 @@ export class FTheadCommentBuilder extends FTheadCommentItem {/*** Set the content of the comment* @param {IDocumentBody | RichTextValue} content The content of the comment- * @returns {FTheadCommentBuilder} The comment builder+ * @returns {FTheadCommentBuilder} The comment builder for chaining* @example* ```ts- * const comment = univerAPI.newTheadComment()- * .setContent(univerAPI.newRichText().insertText('hello zhangsan'));+ * // Create a new comment+ * const richText = univerAPI.newRichText().insertText('hello univer');+ * const commentBuilder = univerAPI.newTheadComment()+ * .setContent(richText);+ * console.log(commentBuilder.content);+ *+ * // Add the comment to the cell A1+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * const fWorksheet = fWorkbook.getActiveSheet();+ * const cell = fWorksheet.getRange('A1');+ * const result = await cell.addCommentAsync(commentBuilder);+ * console.log(result);* ```*/setContent(content: IDocumentBody | RichTextValue): FTheadCommentBuilder {@@ -179,11 +179,22 @@ export class FTheadCommentBuilder extends FTheadCommentItem {/*** Set the person id of the comment* @param {string} userId The person id of the comment- * @returns {FTheadCommentBuilder} The comment builder+ * @returns {FTheadCommentBuilder} The comment builder for chaining* @example* ```ts- * const comment = univerAPI.newTheadComment()- * .setPersonId('123');+ * // Create a new comment+ * const richText = univerAPI.newRichText().insertText('hello univer');+ * const commentBuilder = univerAPI.newTheadComment()+ * .setContent(richText)+ * .setPersonId('mock-user-id');+ * console.log(commentBuilder.personId);+ *+ * // Add the comment to the cell A1+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * const fWorksheet = fWorkbook.getActiveSheet();+ * const cell = fWorksheet.getRange('A1');+ * const result = await cell.addCommentAsync(commentBuilder);+ * console.log(result);* ```*/setPersonId(userId: string): FTheadCommentBuilder {@@ -194,11 +205,22 @@ export class FTheadCommentBuilder extends FTheadCommentItem {/*** Set the date time of the comment* @param {Date} date The date time of the comment- * @returns {FTheadCommentBuilder} The comment builder+ * @returns {FTheadCommentBuilder} The comment builder for chaining* @example* ```ts- * const comment = univerAPI.newTheadComment()- * .setDateTime(new Date());+ * // Create a new comment+ * const richText = univerAPI.newRichText().insertText('hello univer');+ * const commentBuilder = univerAPI.newTheadComment()+ * .setContent(richText)+ * .setDateTime(new Date('2025-02-21 14:22:22'));+ * console.log(commentBuilder.dateTime);+ *+ * // Add the comment to the cell A1+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * const fWorksheet = fWorkbook.getActiveSheet();+ * const cell = fWorksheet.getRange('A1');+ * const result = await cell.addCommentAsync(commentBuilder);+ * console.log(result);* ```*/setDateTime(date: Date): FTheadCommentBuilder {@@ -209,11 +231,22 @@ export class FTheadCommentBuilder extends FTheadCommentItem {/*** Set the id of the comment* @param {string} id The id of the comment- * @returns {FTheadCommentBuilder} The comment builder+ * @returns {FTheadCommentBuilder} The comment builder for chaining* @example* ```ts- * const comment = univerAPI.newTheadComment()- * .setId('123');+ * // Create a new comment+ * const richText = univerAPI.newRichText().insertText('hello univer');+ * const commentBuilder = univerAPI.newTheadComment()+ * .setContent(richText)+ * .setId('mock-comment-id');+ * console.log(commentBuilder.id);+ *+ * // Add the comment to the cell A1+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * const fWorksheet = fWorkbook.getActiveSheet();+ * const cell = fWorksheet.getRange('A1');+ * const result = await cell.addCommentAsync(commentBuilder);+ * console.log(result);* ```*/setId(id: string): FTheadCommentBuilder {@@ -227,8 +260,19 @@ export class FTheadCommentBuilder extends FTheadCommentItem {* @returns {FTheadCommentBuilder} The comment builder* @example* ```ts- * const comment = univerAPI.newTheadComment()- * .setThreadId('123');+ * // Create a new comment+ * const richText = univerAPI.newRichText().insertText('hello univer');+ * const commentBuilder = univerAPI.newTheadComment()+ * .setContent(richText)+ * .setThreadId('mock-thread-id');+ * console.log(commentBuilder.threadId);+ *+ * // Add the comment to the cell A1+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * const fWorksheet = fWorkbook.getActiveSheet();+ * const cell = fWorksheet.getRange('A1');+ * const result = await cell.addCommentAsync(commentBuilder);+ * console.log(result);* ```*/setThreadId(threadId: string): FTheadCommentBuilder {@@ -241,9 +285,15 @@ export class FTheadCommentBuilder extends FTheadCommentItem {* @returns {IThreadComment} The comment* @example* ```ts+ * const richText = univerAPI.newRichText().insertText('hello univer');* const comment = univerAPI.newTheadComment()- * .setContent(univerAPI.newRichText().insertText('hello zhangsan'))+ * .setContent(richText)+ * .setPersonId('mock-user-id')+ * .setDateTime(new Date('2025-02-21 14:22:22'))+ * .setId('mock-comment-id')+ * .setThreadId('mock-thread-id')* .build();+ * console.log(comment);* ```*/build(): IThreadComment {@@ -281,10 +331,12 @@ export class FThreadComment {* @returns {boolean} Whether the comment is a root comment* @example* ```ts- * const comment = univerAPI.getActiveWorkbook()- * .getSheetById(sheetId)- * .getCommentById(commentId);- * const isRoot = comment.getIsRoot();+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * const fWorksheet = fWorkbook.getActiveSheet();+ * const comments = fWorksheet.getComments();+ * comments.forEach((comment) => {+ * console.log(comment.getIsRoot());+ * });* ```*/getIsRoot(): boolean {@@ -296,10 +348,12 @@ export class FThreadComment {* @returns {IBaseComment} The comment data* @example* ```ts- * const comment = univerAPI.getActiveWorkbook()- * .getSheetById(sheetId)- * .getCommentById(commentId);- * const commentData = comment.getCommentData();+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * const fWorksheet = fWorkbook.getActiveSheet();+ * const comments = fWorksheet.getComments();+ * comments.forEach((comment) => {+ * console.log(comment.getCommentData());+ * });* ```*/getCommentData(): IBaseComment {@@ -312,10 +366,17 @@ export class FThreadComment {* @returns {FThreadComment[]} the replies of the comment* @example* ```ts- * const comment = univerAPI.getActiveWorkbook()- * .getSheetById(sheetId)- * .getCommentById(commentId);- * const replies = comment.getReplies();+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * const fWorksheet = fWorkbook.getActiveSheet();+ * const comments = fWorksheet.getComments();+ * comments.forEach((comment) => {+ * if (comment.getIsRoot()) {+ * const replies = comment.getReplies();+ * replies.forEach((reply) => {+ * console.log(reply.getCommentData());+ * });+ * }+ * });* ```*/getReplies(): FThreadComment[] | undefined {@@ -330,10 +391,12 @@ export class FThreadComment {* @returns {FRange | null} The range of the comment* @example* ```ts- * const comment = univerAPI.getActiveWorkbook()- * .getSheetById(sheetId)- * .getCommentById(commentId);- * const range = comment.getRange();+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * const fWorksheet = fWorkbook.getActiveSheet();+ * const comments = fWorksheet.getComments();+ * comments.forEach((comment) => {+ * console.log(comment.getRange().getA1Notation());+ * });* ```*/getRange(): FRange | null {@@ -362,10 +425,12 @@ export class FThreadComment {* @returns {RichTextValue} The rich text of the comment* @example* ```ts- * const comment = univerAPI.getActiveWorkbook()- * .getSheetById(sheetId)- * .getCommentById(commentId);- * const richText = comment.getRichText();+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * const fWorksheet = fWorkbook.getActiveSheet();+ * const comments = fWorksheet.getComments();+ * comments.forEach((comment) => {+ * console.log(comment.getRichText());+ * });* ```*/getRichText(): RichTextValue {@@ -375,13 +440,16 @@ export class FThreadComment {/*** Delete the comment and it's replies- * @returns {Promise<boolean>} success or not+ * @returns {Promise<boolean>} Whether the comment is deleted successfully* @example* ```ts- * const comment = univerAPI.getActiveWorkbook()- * .getSheetById(sheetId)- * .getCommentById(commentId);- * const success = await comment.deleteAsync();+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * const fWorksheet = fWorkbook.getActiveSheet();+ * const comments = fWorksheet.getComments();+ *+ * // Delete the first comment+ * const result = await comments[0]?.deleteAsync();+ * console.log(result);* ```*/deleteAsync(): Promise<boolean> {@@ -414,13 +482,27 @@ export class FThreadComment {/*** Update the comment content* @param {IDocumentBody | RichTextValue} content The new content of the comment- * @returns {Promise<boolean>} success or not+ * @returns {Promise<boolean>} Whether the comment is updated successfully* @example* ```ts- * const comment = univerAPI.getActiveWorkbook()- * .getSheetById(sheetId)- * .getCommentById(commentId);- * const success = await comment.updateAsync(univerAPI.newRichText().insertText('hello zhangsan'));+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * const fWorksheet = fWorkbook.getActiveSheet();+ *+ * // Create a new comment+ * const richText = univerAPI.newRichText().insertText('hello univer');+ * const commentBuilder = univerAPI.newTheadComment()+ * .setContent(richText)+ * .setId('mock-comment-id');+ * const cell = fWorksheet.getRange('A1');+ * await cell.addCommentAsync(commentBuilder);+ *+ * // Update the comment after 3 seconds+ * setTimeout(async () => {+ * const comment = fWorksheet.getCommentById('mock-comment-id');+ * const newRichText = univerAPI.newRichText().insertText('Hello Univer AI');+ * const result = await comment.updateAsync(newRichText);+ * console.log(result);+ * }, 3000);* ```*/async updateAsync(content: IDocumentBody | RichTextValue): Promise<boolean> {@@ -451,18 +533,31 @@ export class FThreadComment {return this.resolveAsync(resolved);}- /**- * Resolve the comment- * @param {boolean} resolved Whether the comment is resolved- * @returns {Promise<boolean>} success or not- * @example- * ```ts- * const comment = univerAPI.getActiveWorkbook()- * .getSheetById(sheetId)- * .getCommentById(commentId);- * const success = await comment.resolveAsync(true);- * ```- */+ /**+ * Resolve the comment+ * @param {boolean} resolved Whether the comment is resolved+ * @returns {Promise<boolean>} Set the comment to resolved or not operation result+ * @example+ * ```ts+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * const fWorksheet = fWorkbook.getActiveSheet();+ *+ * // Create a new comment+ * const richText = univerAPI.newRichText().insertText('hello univer');+ * const commentBuilder = univerAPI.newTheadComment()+ * .setContent(richText)+ * .setId('mock-comment-id');+ * const cell = fWorksheet.getRange('A1');+ * await cell.addCommentAsync(commentBuilder);+ *+ * // Resolve the comment after 3 seconds+ * setTimeout(async () => {+ * const comment = fWorksheet.getCommentById('mock-comment-id');+ * const result = await comment.resolveAsync(true);+ * console.log(result);+ * }, 3000);+ * ```+ */resolveAsync(resolved?: boolean): Promise<boolean> {return this._commandService.executeCommand(ResolveCommentCommand.id,@@ -478,20 +573,29 @@ export class FThreadComment {/*** Reply to the comment* @param {FTheadCommentBuilder} comment The comment to reply to- * @returns {Promise<boolean>} success or not+ * @returns {Promise<boolean>} Whether the comment is replied successfully* @example* ```ts- * const comment = univerAPI.getActiveWorkbook()- * .getSheetById(sheetId)- * .getCommentById(commentId);+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * const fWorksheet = fWorkbook.getActiveSheet();*- * const reply = univerAPI.newTheadComment()- * .setContent(univerAPI.newRichText().insertText('hello zhangsan'));+ * // Create a new comment+ * const richText = univerAPI.newRichText().insertText('hello univer');+ * const commentBuilder = univerAPI.newTheadComment()+ * .setContent(richText)+ * .setId('mock-comment-id');+ * const cell = fWorksheet.getRange('A1');+ * await cell.addCommentAsync(commentBuilder);*- * const success = await comment.replyAsync(reply);+ * // Reply to the comment+ * const replyText = univerAPI.newRichText().insertText('Hello Univer AI');+ * const reply = univerAPI.newTheadComment().setContent(replyText);+ * const comment = fWorksheet.getCommentById('mock-comment-id');+ * const result = await comment.replyAsync(reply);+ * console.log(result);* ```*/- async replyAsync(comment: FTheadCommentBuilder): Promise<boolean> {+ replyAsync(comment: FTheadCommentBuilder): Promise<boolean> {const commentData = comment.build();return this._commandService.executeCommand(AddCommentCommand.id,@@ -499,11 +603,10 @@ export class FThreadComment {unitId: this._thread.unitId,subUnitId: this._thread.subUnitId,comment: {-id: generateRandomId(),parentId: this._thread.id,threadId: this._thread.threadId,- ref: this._parent?.ref,+ ref: this._parent?.ref || (this._thread as IThreadComment).ref,unitId: this._thread.unitId,subUnitId: this._thread.subUnitId,text: commentData.text,diff --git a/packages/sheets-thread-comment/src/facade/f-univer.ts b/packages/sheets-thread-comment/src/facade/f-univer.tsindex 3d64057b83..6f923446ea 100644--- a/packages/sheets-thread-comment/src/facade/f-univer.ts+++ b/packages/sheets-thread-comment/src/facade/f-univer.ts@@ -27,31 +27,45 @@ import { FTheadCommentBuilder, FTheadCommentItem } from './f-thread-comment';*/export interface IFUniverCommentMixin {/**- * @deprecated use `univerAPI.addEvent(univerAPI.Event.CommentAdded, () => {})` as instead+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.CommentAdded, (params) => {})` as instead*/onCommentAdded(callback: (event: ISheetCommentAddEvent) => void): IDisposable;/**- * @deprecated use `univerAPI.addEvent(univerAPI.Event.CommentUpdated, () => {})` as instead+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.CommentUpdated, (params) => {})` as instead*/onCommentUpdated(callback: (event: ISheetCommentUpdateEvent) => void): IDisposable;/**- * @deprecated use `univerAPI.addEvent(univerAPI.Event.CommentDeleted, () => {})` as instead+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.CommentDeleted, (params) => {})` as instead*/onCommentDeleted(callback: (event: ISheetCommentDeleteEvent) => void): IDisposable;/**- * @deprecated use `univerAPI.addEvent(univerAPI.Event.CommentResolved, () => {})` as instead+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.CommentResolved, (params) => {})` as instead*/onCommentResolved(callback: (event: ISheetCommentResolveEvent) => void): IDisposable;/**- * create a new thread comment- * @returns {FTheadCommentBuilder} thead comment builder+ * Create a new thread comment+ * @returns {FTheadCommentBuilder} The thead comment builder* @example* ```ts- * const comment = univerAPI.newTheadComment().setContent(univerAPI.newRichText().insertText('hello zhangsan'));+ * // Create a new comment+ * const richText = univerAPI.newRichText().insertText('hello univer');+ * const commentBuilder = univerAPI.newTheadComment()+ * .setContent(richText)+ * .setPersonId('mock-user-id')+ * .setDateTime(new Date('2025-02-21 14:22:22'))+ * .setId('mock-comment-id')+ * .setThreadId('mock-thread-id');+ *+ * // Add the comment to the cell A1+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * const fWorksheet = fWorkbook.getActiveSheet();+ * const cell = fWorksheet.getRange('A1');+ * const result = await cell.addCommentAsync(commentBuilder);+ * console.log(result);* ```*/newTheadComment(): FTheadCommentBuilder;@@ -228,7 +242,7 @@ export class FUniverCommentMixin extends FUniver implements IFUniverCommentMixin);this.registerEventHandler(- this.Event.BeforeCommentDeleted,+ this.Event.BeforeCommentDelete,() => commandService.beforeCommandExecuted((commandInfo) => {if (commandInfo.id !== DeleteCommentCommand.id && commandInfo.id !== DeleteCommentTreeCommand.id) return;const params = commandInfo.params as { unitId: string; subUnitId: string; sheetId: string };@@ -249,7 +263,7 @@ export class FUniverCommentMixin extends FUniver implements IFUniverCommentMixincol: threadComment.getRange()?.getColumn() ?? 0,comment: threadComment,};- this.fireEvent(this.Event.BeforeCommentDeleted, eventParams);+ this.fireEvent(this.Event.BeforeCommentDelete, eventParams);if (eventParams.cancel) {throw new CanceledError();}diff --git a/packages/sheets-thread-comment/src/facade/f-workbook.ts b/packages/sheets-thread-comment/src/facade/f-workbook.tsindex 25f852317f..637d2678c2 100644--- a/packages/sheets-thread-comment/src/facade/f-workbook.ts+++ b/packages/sheets-thread-comment/src/facade/f-workbook.ts@@ -30,34 +30,47 @@ type IUpdateCommandParams = any;*/export interface IFWorkbookThreadCommentMixin {/**- * Get all comments in the current sheet- * @returns all comments in the current sheet+ * Get all comments in the current workbook+ * @returns {FThreadComment[]} All comments in the current workbook* @example* ```ts- * const workbook = univerAPI.getActiveWorkbook();- * const comments = workbook.getComments();+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * const comments = fWorkbook.getComments();+ * comments.forEach((comment) => {+ * const isRoot = comment.getIsRoot();+ *+ * if (isRoot) {+ * console.log('root comment:', comment.getCommentData());+ *+ * const replies = comment.getReplies();+ * replies.forEach((reply) => {+ * console.log('reply comment:', reply.getCommentData());+ * });+ * }+ * });* ```*/getComments(): FThreadComment[];/**- * Clear all comments in the current sheet- * @returns Whether the comments are cleared successfully.+ * Clear all comments in the current workbook+ * @returns {Promise<boolean>} Whether the comments are cleared successfully.* @example* ```ts- * const workbook = univerAPI.getActiveWorkbook();- * const success = await workbook.clearComments();+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * const result = await fWorkbook.clearComments();+ * console.log(result);* ```*/clearComments(): Promise<boolean>;/**- * @deprecated use `univerAPI.addEvent(univerAPI.Event.CommentUpdated, () => {})` as instead+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.CommentUpdated, (params) => {})` as instead*/onThreadCommentChange(callback: (commentUpdate: CommentUpdate) => void | false): IDisposable;/**- * @deprecated use `univerAPI.addEvent(univerAPI.Event.BeforeCommentAdd, () => {})` as instead+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.BeforeCommentAdd, (params) => {})` as instead*/onBeforeAddThreadComment(this: FWorkbook,@@ -65,7 +78,7 @@ export interface IFWorkbookThreadCommentMixin {): IDisposable;/**- * @deprecated use `univerAPI.addEvent(univerAPI.Event.BeforeCommentUpdate, () => {})` as instead+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.BeforeCommentUpdate, (params) => {})` as instead*/onBeforeUpdateThreadComment(this: FWorkbook,@@ -73,7 +86,7 @@ export interface IFWorkbookThreadCommentMixin {): IDisposable;/**- * @deprecated use `univerAPI.addEvent(univerAPI.Event.BeforeCommentDelete, () => {})` as instead+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.BeforeCommentDelete, (params) => {})` as instead*/onBeforeDeleteThreadComment(this: FWorkbook,diff --git a/packages/sheets-thread-comment/src/facade/f-worksheet.ts b/packages/sheets-thread-comment/src/facade/f-worksheet.tsindex 1e3d5967d3..653862ee56 100644--- a/packages/sheets-thread-comment/src/facade/f-worksheet.ts+++ b/packages/sheets-thread-comment/src/facade/f-worksheet.ts@@ -28,21 +28,37 @@ import { FThreadComment } from './f-thread-comment';export interface IFWorksheetCommentMixin {/*** Get all comments in the current sheet- * @returns all comments in the current sheet+ * @returns {FThreadComment[]} All comments in the current sheet+ * @example* ```ts- * const workbook = univerAPI.getActiveWorkbook();- * const worksheet = workbook.getSheetById(sheetId);- * const comments = worksheet.getComments();+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * const fWorksheet = fWorkbook.getActiveSheet();+ * const comments = fWorksheet.getComments();+ * comments.forEach((comment) => {+ * const isRoot = comment.getIsRoot();+ *+ * if (isRoot) {+ * console.log('root comment:', comment.getCommentData());+ *+ * const replies = comment.getReplies();+ * replies.forEach((reply) => {+ * console.log('reply comment:', reply.getCommentData());+ * });+ * }+ * });* ```*/getComments(): FThreadComment[];/*** Clear all comments in the current sheet+ * @returns {Promise<boolean>} Whether the comments are cleared successfully.+ * @example* ```ts- * const workbook = univerAPI.getActiveWorkbook();- * const worksheet = workbook.getSheetById(sheetId);- * await worksheet.clearComments();+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * const fWorksheet = fWorkbook.getActiveSheet();+ * const result = await fWorksheet.clearComments();+ * console.log(result);* ```*/clearComments(): Promise<boolean>;@@ -51,9 +67,19 @@ export interface IFWorksheetCommentMixin {* get comment by comment id* @param {string} commentId comment id* ```ts- * const workbook = univerAPI.getActiveWorkbook();- * const worksheet = workbook.getSheetById(sheetId);- * const comment = worksheet.getCommentById(commentId);+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * const fWorksheet = fWorkbook.getActiveSheet();+ *+ * // Create a new comment+ * const richText = univerAPI.newRichText().insertText('hello univer');+ * const commentBuilder = univerAPI.newTheadComment()+ * .setContent(richText)+ * .setId('mock-comment-id');+ * const cell = fWorksheet.getRange('A1');+ * await cell.addCommentAsync(commentBuilder);+ *+ * const comment = fWorksheet.getCommentById('mock-comment-id');+ * console.log(comment, comment?.getCommentData());* ```*/getCommentById(commentId: string): FThreadComment | undefined;diff --git a/packages/sheets-ui/src/facade/f-event.ts b/packages/sheets-ui/src/facade/f-event.tsindex b6987a76cd..64d5af9444 100644--- a/packages/sheets-ui/src/facade/f-event.ts+++ b/packages/sheets-ui/src/facade/f-event.ts@@ -160,12 +160,15 @@ export interface IFSheetsUIEventNameMixin {* Type of the event parameter is {@link IBeforeClipboardChangeParam}* @example* ```ts- * univerAPI.addEvent(univerAPI.Event.BeforeClipboardChange, (param) => {- * const {text, html} = param;- * console.log('debugger', text, html); // {text: '...', html: '...'}- * // if want to cancel the clipboard change- * param.cancel = true;+ * const disposable = univerAPI.addEvent(univerAPI.Event.BeforeClipboardChange, (params) => {+ * const { workbook, worksheet, text, html, fromSheet, fromRange } = params;+ * console.log(params);+ *+ * // Cancel the clipboard change operation+ * params.cancel = true;* })+ *+ * // Remove the event listener, use `disposable.dispose()`* ```*/readonly BeforeClipboardChange: 'BeforeClipboardChange';@@ -175,36 +178,45 @@ export interface IFSheetsUIEventNameMixin {* Type of the event parameter is {@link IClipboardChangedParam}* @example* ```ts- * univerAPI.addEvent(univerAPI.Event.ClipboardChanged, (param) => {- * const {text, html} = param;- * console.log('debugger', text, html); // {text: '...', html: '...'}+ * const disposable = univerAPI.addEvent(univerAPI.Event.ClipboardChanged, (params) => {+ * const { workbook, worksheet, text, html, fromSheet, fromRange } = params;+ * console.log(params);* })+ *+ * // Remove the event listener, use `disposable.dispose()`* ```*/readonly ClipboardChanged: 'ClipboardChanged';+/*** Trigger this event before pasting.* Type of the event parameter is {@link IBeforeClipboardPasteParam}* @example* ```ts- * univerAPI.addEvent(univerAPI.Event.BeforeClipboardPaste, (param) => {- * const {text, html} = param;- * console.log('debugger', text, html);- * // if want to cancel the clipboard paste- * param.cancel = true;+ * const disposable = univerAPI.addEvent(univerAPI.Event.BeforeClipboardPaste, (params) => {+ * const { workbook, worksheet, text, html } = params;+ * console.log(params);+ *+ * // Cancel the clipboard paste operation+ * params.cancel = true;* })+ *+ * // Remove the event listener, use `disposable.dispose()`* ```*/readonly BeforeClipboardPaste: 'BeforeClipboardPaste';+/*** Trigger this event after pasting.* Type of the event parameter is {@link IClipboardPastedParam}* @example* ```ts- * univerAPI.addEvent(univerAPI.Event.ClipboardPasted, (param) => {- * const {text, html} = param;- * console.log('debugger', text, html); // {text: '...', html: '...'}+ * const disposable = univerAPI.addEvent(univerAPI.Event.ClipboardPasted, (params) => {+ * const { workbook, worksheet, text, html } = params;+ * console.log(params);* })+ *+ * // Remove the event listener, use `disposable.dispose()`* ```*/readonly ClipboardPasted: 'ClipboardPasted';@@ -214,53 +226,78 @@ export interface IFSheetsUIEventNameMixin {* @see {@link IBeforeSheetEditStartEventParams}* @example* ```ts- * univerAPI.addEvent(univerAPI.Event.BeforeSheetEditStart, (params) => {+ * const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetEditStart, (params) => {* const { worksheet, workbook, row, column, eventType, keycode, isZenEditor } = params;+ * console.log(params);+ *+ * // Cancel the cell edit start operation+ * params.cancel = true;* });+ *+ * // Remove the event listener, use `disposable.dispose()`* ```*/readonly BeforeSheetEditStart: 'BeforeSheetEditStart';+/*** Event fired after a cell is edited- * @see {@link ISheetEditEndedEventParams}+ * @see {@link ISheetEditStartedEventParams}* @example* ```ts- * univerAPI.addEvent(univerAPI.Event.SheetEditStarted, (params) => {+ * const disposable = univerAPI.addEvent(univerAPI.Event.SheetEditStarted, (params) => {* const { worksheet, workbook, row, column, eventType, keycode, isZenEditor } = params;+ * console.log(params);* });+ *+ * // Remove the event listener, use `disposable.dispose()`* ```*/readonly SheetEditStarted: 'SheetEditStarted';+/*** Event fired when a cell is being edited* @see {@link ISheetEditChangingEventParams}* @example* ```ts- * univerAPI.addEvent(univerAPI.Event.SheetEditChanging, (params) => {+ * const disposable = univerAPI.addEvent(univerAPI.Event.SheetEditChanging, (params) => {* const { worksheet, workbook, row, column, value, isZenEditor } = params;+ * console.log(params);* });+ *+ * // Remove the event listener, use `disposable.dispose()`* ```*/readonly SheetEditChanging: 'SheetEditChanging';+/*** Event fired before a cell edit ends* @see {@link IBeforeSheetEditEndEventParams}* @example* ```ts- * univerAPI.addEvent(univerAPI.Event.BeforeSheetEditEnd, (params) => {- * const { worksheet, workbook, row, column, value, eventType, keycode, isZenEditor } = params;+ * const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetEditEnd, (params) => {+ * const { worksheet, workbook, row, column, value, eventType, keycode, isZenEditor, isConfirm } = params;+ * console.log(params);+ *+ * // Cancel the cell edit end operation+ * params.cancel = true;* });+ *+ * // Remove the event listener, use `disposable.dispose()`* ```*/readonly BeforeSheetEditEnd: 'BeforeSheetEditEnd';+/*** Event fired after a cell edit ends* @see {@link ISheetEditEndedEventParams}* @example* ```ts- * univerAPI.addEvent(univerAPI.Event.SheetEditEnded, (params) => {- * const { worksheet, workbook, row, column, eventType, keycode, isZenEditor } = params;+ * const disposable = univerAPI.addEvent(univerAPI.Event.SheetEditEnded, (params) => {+ * const { worksheet, workbook, row, column, eventType, keycode, isZenEditor, isConfirm } = params;+ * console.log(params);* });+ *+ * // Remove the event listener, use `disposable.dispose()`* ```*/readonly SheetEditEnded: 'SheetEditEnded';@@ -270,20 +307,27 @@ export interface IFSheetsUIEventNameMixin {* @see {@link ICellEventParam}* @example* ```ts- * univerAPI.addEvent(univerAPI.Event.CellClicked, (params) => {- * const { worksheet, workbook, row, column, value, isZenEditor } = params;+ * const disposable = univerAPI.addEvent(univerAPI.Event.CellClicked, (params) => {+ * const { worksheet, workbook, row, column } = params;+ * console.log(params);* });+ *+ * // Remove the event listener, use `disposable.dispose()`* ```*/readonly CellClicked: 'CellClicked';+/*** Event fired when a cell is pointer down* @see {@link ICellEventParam}* @example* ```ts- * univerAPI.addEvent(univerAPI.Event.CellPointerDown, (params) => {+ * const disposable = univerAPI.addEvent(univerAPI.Event.CellPointerDown, (params) => {* const { worksheet, workbook, row, column } = params;+ * console.log(params);* });+ *+ * // Remove the event listener, use `disposable.dispose()`* ```*/readonly CellPointerDown: 'CellPointerDown';@@ -293,9 +337,12 @@ export interface IFSheetsUIEventNameMixin {* @see {@link ICellEventParam}* @example* ```ts- * univerAPI.addEvent(univerAPI.Event.CellPointerUp, (params) => {+ * const disposable = univerAPI.addEvent(univerAPI.Event.CellPointerUp, (params) => {* const { worksheet, workbook, row, column } = params;+ * console.log(params);* });+ *+ * // Remove the event listener, use `disposable.dispose()`* ```*/readonly CellPointerUp: 'CellPointerUp';@@ -305,140 +352,177 @@ export interface IFSheetsUIEventNameMixin {* @see {@link ICellEventParam}* @example* ```ts- * univerAPI.addEvent(univerAPI.Event.CellHover, (params) => {+ * const disposable = univerAPI.addEvent(univerAPI.Event.CellHover, (params) => {* const { worksheet, workbook, row, column } = params;+ * console.log(params);* });+ *+ * // Remove the event listener, use `disposable.dispose()`* ```*/readonly CellHover: 'CellHover';+/*** Event fired when move on spreadsheet cells* @see {@link ICellEventParam}* @example* ```ts- * univerAPI.addEvent(univerAPI.Event.CellPointerMove, (params) => {+ * const disposable = univerAPI.addEvent(univerAPI.Event.CellPointerMove, (params) => {* const { worksheet, workbook, row, column } = params;+ * console.log(params);* });+ *+ * // Remove the event listener, use `disposable.dispose()`* ```*/readonly CellPointerMove: 'CellPointerMove';/*** Triggered when a row header is clicked- * @param {ISheetRowHeaderEvent} params - Event parameters containing unitId, subUnitId, and row index+ * @see {@link ISheetRowHeaderEvent}* @example* ```typescript- * univerAPI.onSheetEvent(Event.RowHeaderClick, (params) => {- * console.log(`Row ${params.row} header clicked in sheet ${params.worksheet.getSheetId()}`);+ * const disposable = univerAPI.addEvent(univerAPI.Event.RowHeaderClick, (params) => {+ * const { worksheet, workbook, row } = params;+ * console.log(params);* });+ *+ * // Remove the event listener, use `disposable.dispose()`* ```*/readonly RowHeaderClick: 'RowHeaderClick';/*** Triggered when pointer is pressed down on a row header- * @param {ISheetRowHeaderEvent} params - Event parameters containing unitId, subUnitId, and row index+ * @see {@link ISheetRowHeaderEvent}* @example* ```typescript- * univerAPI.onSheetEvent(Event.RowHeaderPointerDown, (params) => {- * console.log(`Pointer down on row ${params.row} header in sheet ${params.worksheet.getSheetId()}`);+ * const disposable = univerAPI.addEvent(univerAPI.Event.RowHeaderPointerDown, (params) => {+ * const { worksheet, workbook, row } = params;+ * console.log(params);* });+ *+ * // Remove the event listener, use `disposable.dispose()`* ```*/readonly RowHeaderPointerDown: 'RowHeaderPointerDown';/*** Triggered when pointer is released on a row header- * @param {ISheetRowHeaderEvent} params - Event parameters containing unitId, subUnitId, and row index+ * @see {@link ISheetRowHeaderEvent}* @example* ```typescript- * univerAPI.onSheetEvent(Event.RowHeaderPointerUp, (params) => {- * console.log(`Pointer up on row ${params.row} header in sheet ${params.worksheet.getSheetId()}`);+ * const disposable = univerAPI.addEvent(univerAPI.Event.RowHeaderPointerUp, (params) => {+ * const { worksheet, workbook, row } = params;+ * console.log(params);* });+ *+ * // Remove the event listener, use `disposable.dispose()`* ```*/readonly RowHeaderPointerUp: 'RowHeaderPointerUp';/*** Triggered when pointer hovers over a row header- * @param {ISheetRowHeaderEvent} params - Event parameters containing unitId, subUnitId, and row index+ * @see {@link ISheetRowHeaderEvent}* @example* ```typescript- * univerAPI.onSheetEvent(Event.RowHeaderHover, (params) => {- * console.log(`Hovering over row ${params.row} header in sheet ${params.worksheet.getSheetId()}`);+ * const disposable = univerAPI.addEvent(univerAPI.Event.RowHeaderHover, (params) => {+ * const { worksheet, workbook, row } = params;+ * console.log(params);* });+ *+ * // Remove the event listener, use `disposable.dispose()`* ```*/readonly RowHeaderHover: 'RowHeaderHover';/*** Triggered when a column header is clicked- * @param {ISheetColumnHeaderEvent} params - Event parameters containing unitId, subUnitId, and column index+ * @see {@link ISheetColumnHeaderEvent}* @example* ```typescript- * univerAPI.onSheetEvent(Event.ColumnHeaderClick, (params) => {- * console.log(`Column ${params.column} header clicked in sheet ${params.worksheet.getSheetId()}`);+ * const disposable = univerAPI.addEvent(univerAPI.Event.ColumnHeaderClick, (params) => {+ * const { worksheet, workbook, column } = params;+ * console.log(params);* });+ *+ * // Remove the event listener, use `disposable.dispose()`* ```*/readonly ColumnHeaderClick: 'ColumnHeaderClick';/*** Triggered when pointer is pressed down on a column header- * @param {ISheetColumnHeaderEvent} params - Event parameters containing unitId, subUnitId, and column index+ * @see {@link ISheetColumnHeaderEvent}* @example* ```typescript- * univerAPI.onSheetEvent(Event.ColumnHeaderPointerDown, (params) => {- * console.log(`Pointer down on column ${params.column} header in sheet ${params.worksheet.getSheetId()}`);+ * const disposable = univerAPI.addEvent(univerAPI.Event.ColumnHeaderPointerDown, (params) => {+ * const { worksheet, workbook, column } = params;+ * console.log(params);* });+ *+ * // Remove the event listener, use `disposable.dispose()`* ```*/readonly ColumnHeaderPointerDown: 'ColumnHeaderPointerDown';/*** Triggered when pointer is released on a column header- * @param {ISheetColumnHeaderEvent} params - Event parameters containing unitId, subUnitId, and column index+ * @see {@link ISheetColumnHeaderEvent}* @example* ```typescript- * univerAPI.onSheetEvent(Event.ColumnHeaderPointerUp, (params) => {- * console.log(`Pointer up on column ${params.column} header in sheet ${params.worksheet.getSheetId()}`);+ * const disposable = univerAPI.addEvent(univerAPI.Event.ColumnHeaderPointerUp, (params) => {+ * const { worksheet, workbook, column } = params;+ * console.log(params);* });+ *+ * // Remove the event listener, use `disposable.dispose()`* ```*/readonly ColumnHeaderPointerUp: 'ColumnHeaderPointerUp';/*** Triggered when pointer hovers over a column header- * @param {ISheetColumnHeaderEvent} params - Event parameters containing unitId, subUnitId, and column index+ * @see {@link ISheetColumnHeaderEvent}* @example* ```typescript- * univerAPI.onSheetEvent(Event.ColumnHeaderHover, (params) => {- * console.log(`Hovering over column ${params.column} header in sheet ${params.worksheet.getSheetId()}`);+ * const disposable = univerAPI.addEvent(univerAPI.Event.ColumnHeaderHover, (params) => {+ * const { worksheet, workbook, column } = params;+ * console.log(params);* });+ *+ * // Remove the event listener, use `disposable.dispose()`* ```*/readonly ColumnHeaderHover: 'ColumnHeaderHover';/**- * Event fired when drag over spreadsheet cells+ * Event fired when the drag element passes over the spreadsheet cells* @see {@link ICellEventParam}* @example* ```ts- * univerAPI.getActiveWorkbook().addEvent(univerAPI.Event.DragOver, (params) => {+ * const disposable = univerAPI.addEvent(univerAPI.Event.DragOver, (params) => {* const { worksheet, workbook, row, column } = params;+ * console.log(params);* });+ *+ * // Remove the event listener, use `disposable.dispose()`* ```*/readonly DragOver: 'DragOver';/**- * Event fired when drop on spreadsheet cells+ * Event fired when the drag element is dropped on the spreadsheet cells* @see {@link ICellEventParam}* @example* ```ts- * univerAPI.getActiveWorkbook().addEvent(univerAPI.Event.Drop, (params) => {- * const { worksheet, workbook, row, column } = params;+ * const disposable = univerAPI.addEvent(univerAPI.Event.Drop, (params) => {+ * const { worksheet, workbook, row, column } = params;+ * console.log(params);* });+ *+ * // Remove the event listener, use `disposable.dispose()`* ```*/readonly Drop: 'Drop';@@ -448,9 +532,12 @@ export interface IFSheetsUIEventNameMixin {* @see {@link IScrollEventParam}* @example* ```ts- * univerAPI.addEvent(univerAPI.Event.Scroll, (params) => {+ * const disposable = univerAPI.addEvent(univerAPI.Event.Scroll, (params) => {* const { worksheet, workbook, scrollX, scrollY } = params;+ * console.log(params);* });+ *+ * // Remove the event listener, use `disposable.dispose()`* ```*/readonly Scroll: 'Scroll';@@ -460,9 +547,12 @@ export interface IFSheetsUIEventNameMixin {* @see {@link ISelectionEventParam}* @example* ```ts- * univerAPI.addEvent(univerAPI.Event.SelectionChanged, (p)=> {- * const { worksheet, workbook, selections } = p;+ * const disposable = univerAPI.addEvent(univerAPI.Event.SelectionChanged, (params)=> {+ * const { worksheet, workbook, selections } = params;+ * console.log(params);* });+ *+ * // Remove the event listener, use `disposable.dispose()`* ```*/readonly SelectionChanged: 'SelectionChanged';@@ -472,9 +562,12 @@ export interface IFSheetsUIEventNameMixin {* @see {@link ISelectionEventParam}* @example* ```ts- * univerAPI.addEvent(univerAPI.Event.SelectionMoveStart, (p)=> {- * const { worksheet, workbook, selections } = p;+ * const disposable = univerAPI.addEvent(univerAPI.Event.SelectionMoveStart, (params)=> {+ * const { worksheet, workbook, selections } = params;+ * console.log(params);* });+ *+ * // Remove the event listener, use `disposable.dispose()`* ```*/readonly SelectionMoveStart: 'SelectionMoveStart';@@ -484,9 +577,12 @@ export interface IFSheetsUIEventNameMixin {* @see {@link ISelectionEventParam}* @example* ```ts- * univerAPI.addEvent(univerAPI.Event.SelectionMoving, (p)=> {- * const { worksheet, workbook, selections } = p;+ * const disposable = univerAPI.addEvent(univerAPI.Event.SelectionMoving, (params)=> {+ * const { worksheet, workbook, selections } = params;+ * console.log(params);* });+ *+ * // Remove the event listener, use `disposable.dispose()`* ```*/readonly SelectionMoving: 'SelectionMoving';@@ -496,9 +592,12 @@ export interface IFSheetsUIEventNameMixin {* @see {@link ISelectionEventParam}* @example* ```ts- * univerAPI.addEvent(univerAPI.Event.SelectionMoveEnd, (p)=> {- * const { worksheet, workbook, selections } = p;+ * const disposable = univerAPI.addEvent(univerAPI.Event.SelectionMoveEnd, (params)=> {+ * const { worksheet, workbook, selections } = params;+ * console.log(params);* });+ *+ * // Remove the event listener, use `disposable.dispose()`* ```*/readonly SelectionMoveEnd: 'SelectionMoveEnd';@@ -508,9 +607,12 @@ export interface IFSheetsUIEventNameMixin {* @see {@link ISheetZoomEvent}* @example* ```ts- * univerAPI.addEvent(univerAPI.Event.SheetZoomChanged, (p)=> {- * const { worksheet, workbook, zoom } = p;+ * const disposable = univerAPI.addEvent(univerAPI.Event.SheetZoomChanged, (params)=> {+ * const { worksheet, workbook, zoom } = params;+ * console.log(params);* });+ *+ * // Remove the event listener, use `disposable.dispose()`* ```*/readonly SheetZoomChanged: 'SheetZoomChanged';@@ -520,9 +622,15 @@ export interface IFSheetsUIEventNameMixin {* @see {@link ISheetZoomEvent}* @example* ```ts- * univerAPI.addEvent(univerAPI.Event.BeforeSheetZoomChange, (p)=> {- * const { worksheet, workbook, zoom } = p;+ * const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetZoomChange, (params)=> {+ * const { worksheet, workbook, zoom } = params;+ * console.log(params);+ *+ * // Cancel the zoom change operation+ * params.cancel = true;* });+ *+ * // Remove the event listener, use `disposable.dispose()`* ```*/readonly BeforeSheetZoomChange: 'BeforeSheetZoomChange';@@ -532,13 +640,15 @@ export interface IFSheetsUIEventNameMixin {* @see {@link ISheetSkeletonChangedEvent}* @example* ```ts- * univerAPI.addEvent(univerAPI.Event.SheetSkeletonChanged, (p)=> {- * const { worksheet, workbook } = p;+ * const disposable = univerAPI.addEvent(univerAPI.Event.SheetSkeletonChanged, (params)=> {+ * const { worksheet, workbook, skeleton, payload, effectedRanges } = params;+ * console.log(params);* });+ *+ * // Remove the event listener, use `disposable.dispose()`* ```*/readonly SheetSkeletonChanged: 'SheetSkeletonChanged';-}export class FSheetsUIEventName implements IFSheetsUIEventNameMixin {diff --git a/packages/sheets-ui/src/facade/f-permission.ts b/packages/sheets-ui/src/facade/f-permission.tsindex 3d08d1ef21..c77ce28be5 100644--- a/packages/sheets-ui/src/facade/f-permission.ts+++ b/packages/sheets-ui/src/facade/f-permission.ts@@ -22,10 +22,12 @@ import { FPermission } from '@univerjs/sheets/facade';export interface IFPermissionSheetsUIMixin {/*** Set visibility of unauthorized pop-up window- * @param {boolean} visible+ * @param {boolean} visible - visibility of unauthorized pop-up window* @example* ```ts- * univerAPI.getPermission().setPermissionDialogVisible(false);+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * const permission = fWorkbook.getPermission();+ * permission.setPermissionDialogVisible(false);* ```*/setPermissionDialogVisible(visible: boolean): void;diff --git a/packages/sheets-ui/src/facade/f-range.ts b/packages/sheets-ui/src/facade/f-range.tsindex 58e0772780..afc2b3735f 100644--- a/packages/sheets-ui/src/facade/f-range.ts+++ b/packages/sheets-ui/src/facade/f-range.ts@@ -16,11 +16,11 @@import type { ICellWithCoord, IDisposable, ISelectionCell, Nullable } from '@univerjs/core';import type { ISelectionStyle, ISheetLocation } from '@univerjs/sheets';+import type { ICanvasPopup, ICellAlert } from '@univerjs/sheets-ui';import type { ComponentType } from '@univerjs/ui';import { DisposableCollection, generateRandomId, ILogService, toDisposable } from '@univerjs/core';import { IRenderManagerService } from '@univerjs/engine-render';-import { CellAlertManagerService, type ICanvasPopup, type ICellAlert, IMarkSelectionService, SheetCanvasPopManagerService } from '@univerjs/sheets-ui';-import { ISheetClipboardService, SheetSkeletonManagerService } from '@univerjs/sheets-ui';+import { CellAlertManagerService, IMarkSelectionService, ISheetClipboardService, SheetCanvasPopManagerService, SheetSkeletonManagerService } from '@univerjs/sheets-ui';import { FRange } from '@univerjs/sheets/facade';import { ComponentManager } from '@univerjs/ui';@@ -47,30 +47,41 @@ interface IFRangeSheetsUIMixin {* Return this cell information, including whether it is merged and cell coordinates* @returns {ICellWithCoord} cell location and coordinate.* @example- * ``` ts- * let sheet = univerAPI.getActiveWorkbook().getActiveSheet();- * sheet.getRange(5, 7).getCell();+ * ```ts+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * const fWorksheet = fWorkbook.getActiveSheet();+ * const fRange = fWorksheet.getRange('H6');+ * console.log(fRange.getCell());* ```*/getCell(this: FRange): ICellWithCoord;/*** Returns the coordinates of this cell,does not include units- * @returns coordinates of the cell, top, right, bottom, left+ * @returns {DOMRect} coordinates of the cell, top, right, bottom, left* @example- * ``` ts- * let sheet = univerAPI.getActiveWorkbook().getActiveSheet();- * sheet.getRange(5, 7).getCellRect();+ * ```ts+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * const fWorksheet = fWorkbook.getActiveSheet();+ * const fRange = fWorksheet.getRange('H6');+ * console.log(fRange.getCellRect());* ```*/getCellRect(this: FRange): DOMRect;/*** Generate HTML content for the range.+ * @returns {string} HTML content of the range.* @example- * ``` ts- * let sheet = univerAPI.getActiveWorkbook().getActiveSheet();- * sheet.getRange(5, 7).generateHTML();+ * ```ts+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * const fWorksheet = fWorkbook.getActiveSheet();+ * const fRange = fWorksheet.getRange('A1:B2');+ * fRange.setValues([+ * [1, 2],+ * [3, 4]+ * ]);+ * console.log(fRange.generateHTML());* ```*/generateHTML(this: FRange): string;@@ -79,78 +90,113 @@ interface IFRangeSheetsUIMixin {* Attach a popup to the start cell of current range.* If current worksheet is not active, the popup will not be shown.* Be careful to manager the detach disposable object, if not dispose correctly, it might memory leaks.- * @param popup The popup to attach- * @returns The disposable object to detach the popup, if the popup is not attached, return `null`.+ * @param {IFCanvasPopup} popup The popup to attach+ * @returns {Nullable<IDisposable>} The disposable object to detach the popup, if the popup is not attached, return `null`.* @example- ```- univerAPI.getComponentManager().register(- 'myPopup',- () => React.createElement('div', {- style: {- color: 'red',- fontSize: '14px'- }- }, 'Custom Popup')- );-- let sheet = univerAPI.getActiveWorkbook().getActiveSheet();- let range = sheet.getRange(2, 2, 3, 3);- univerAPI.getActiveWorkbook().setActiveRange(range);- let disposable = range.attachPopup({- componentKey: 'myPopup'- });- ```+ * ```ts+ * // Register a custom popup component+ * univerAPI.registerComponent(+ * 'myPopup',+ * () => React.createElement('div', {+ * style: {+ * color: 'red',+ * fontSize: '14px'+ * }+ * }, 'Custom Popup')+ * );+ *+ * // Attach the popup to the start cell of range C3:E5+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * const fWorksheet = fWorkbook.getActiveSheet();+ * const fRange = fWorksheet.getRange('C3:E5');+ * const disposable = fRange.attachPopup({+ * componentKey: 'myPopup'+ * });+ *+ * // Detach the popup after 5 seconds+ * setTimeout(() => {+ * disposable.dispose();+ * }, 5000);+ * ```*/attachPopup(popup: IFCanvasPopup): Nullable<IDisposable>;/*** Attach an alert popup to the start cell of current range.- * @param alert The alert to attach- * @returns The disposable object to detach the alert.+ * @param {Omit<ICellAlert, 'location'>} alert The alert to attach+ * @returns {IDisposable} The disposable object to detach the alert.* @example* ```ts- * let sheet = univerAPI.getActiveWorkbook().getActiveSheet();- * let range = sheet.getRange(2, 2, 3, 3);- * range.attachAlertPopup({ message: 'This is an alert', type: 'warning' });+ * // Attach an alert popup to the start cell of range C3:E5+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * const fWorksheet = fWorkbook.getActiveSheet();+ * const fRange = fWorksheet.getRange('C3:E5');+ *+ * const disposable = fRange.attachAlertPopup({+ * title: 'Warning',+ * message: 'This is an warning message',+ * type: 1+ * });+ *+ * // Detach the alert after 5 seconds+ * setTimeout(() => {+ * disposable.dispose();+ * }, 5000);* ```*/attachAlertPopup(alert: Omit<ICellAlert, 'location'>): IDisposable;+/*** Attach a DOM popup to the current range.- * @param alert The alert to attach- * @returns The disposable object to detach the alert.+ * @param {IFCanvasPopup} alert The alert to attach+ * @returns {Nullable<IDisposable>} The disposable object to detach the alert.* @example* ```ts- let sheet = univerAPI.getActiveWorkbook().getActiveSheet();- let range = sheet.getRange(2, 2, 3, 3);- univerAPI.getActiveWorkbook().setActiveRange(range);-- univerAPI.getComponentManager().register(- 'myPopup',- () => React.createElement('div', {- style: {- background: 'red',- fontSize: '14px'- }- }, 'Custom Popup')- );- let disposable = range.attachRangePopup({- componentKey: 'myPopup',- direction: 'top' // 'vertical' | 'horizontal' | 'top' | 'right' | 'left' | 'bottom' | 'bottom-center' | 'top-center';- });+ * // Register a custom popup component+ * univerAPI.registerComponent(+ * 'myPopup',+ * () => React.createElement('div', {+ * style: {+ * background: 'red',+ * fontSize: '14px'+ * }+ * }, 'Custom Popup')+ * );+ *+ * // Attach the popup to the range C3:E5+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * const fWorksheet = fWorkbook.getActiveSheet();+ * const fRange = fWorksheet.getRange('C3:E5');+ * const disposable = fRange.attachRangePopup({+ * componentKey: 'myPopup',+ * direction: 'top' // 'vertical' | 'horizontal' | 'top' | 'right' | 'left' | 'bottom' | 'bottom-center' | 'top-center'+ * });* ```*/attachRangePopup(popup: IFCanvasPopup): Nullable<IDisposable>;/**- * Highlight the range with the specified style and primary cell.- * @param style - style for highlight range.- * @param primary - primary cell for highlight range.+ * 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.+ * @returns {IDisposable} The disposable object to remove the highlight.* @example* ```ts- * let sheet = univerAPI.getActiveWorkbook().getActiveSheet();- * let range = sheet.getRange(2, 2, 3, 3);- * range.highlight({ stroke: 'red' }, { startRow: 2, startColumn: 2 });+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * const fWorksheet = fWorkbook.getActiveSheet();+ *+ * // Highlight the range C3:E5 with default style+ * const fRange = fWorksheet.getRange('C3:E5');+ * fRange.highlight();+ *+ * // Highlight the range C7:E9 with custom style+ * const fRange2 = fWorksheet.getRange('C7:E9');+ * const disposable = fRange2.highlight({ stroke: 'red', fill: 'yellow' });+ *+ * // Remove the range C7:E9 highlight after 5 seconds+ * setTimeout(() => {+ * disposable.dispose();+ * }, 5000);* ```*/highlight(style?: Nullable<Partial<ISelectionStyle>>, primary?: Nullable<ISelectionCell>): IDisposable;diff --git a/packages/sheets-ui/src/facade/f-sheet-hooks.ts b/packages/sheets-ui/src/facade/f-sheet-hooks.tsindex 1fb6f5d38c..3e5299003e 100644--- a/packages/sheets-ui/src/facade/f-sheet-hooks.ts+++ b/packages/sheets-ui/src/facade/f-sheet-hooks.ts@@ -27,6 +27,7 @@ import { FSheetHooks } from '@univerjs/sheets/facade';export interface IFSheetHooksUIMixin {/*** The onCellPointerMove event is fired when a pointer changes coordinates.+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.CellPointerMove, (params) => {})` instead* @param {function(Nullable<IHoverCellPosition>): void} callback - function that will be called when the event is fired* @returns {IDisposable} A disposable object that can be used to unsubscribe from the event* @example@@ -38,6 +39,7 @@ export interface IFSheetHooksUIMixin {/*** The onCellPointerOver event is fired when a pointer is moved into a cell's hit test boundaries.+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.CellHover, (params) => {})` instead* @param {function(Nullable<IHoverCellPosition>): void} callback - function that will be called when the event is fired* @returns {IDisposable} A disposable object that can be used to unsubscribe from the event* @example@@ -49,6 +51,7 @@ export interface IFSheetHooksUIMixin {/*** The onCellDragOver event is fired when an element or text selection is being dragged into a cell's hit test boundaries.+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.DragOver, (params) => {})` instead* @param {function (Nullable<IDragCellPosition>): void} callback Callback function that will be called when the event is fired* @returns {IDisposable} A disposable object that can be used to unsubscribe from the event* @example@@ -60,6 +63,7 @@ export interface IFSheetHooksUIMixin {/*** The onCellDrop event is fired when an element or text selection is being dropped on the cell.+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.Drop, (params) => {})` instead* @param {function(Nullable<IDragCellPosition>): void} callback Callback function that will be called when the event is fired* @returns {IDisposable} A disposable object that can be used to unsubscribe from the event* @example@@ -94,6 +98,7 @@ export interface IFSheetHooksUIMixin {/*** The onBeforeCellEdit event is fired before a cell is edited.+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.BeforeSheetEditStart, (params) => {})` instead* @param callback Callback function that will be called when the event is fired* @returns A disposable object that can be used to unsubscribe from the event* @example@@ -105,6 +110,7 @@ export interface IFSheetHooksUIMixin {/*** The onAfterCellEdit event is fired after a cell is edited.+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.SheetEditEnded, (params) => {})` instead* @param callback Callback function that will be called when the event is fired* @returns A disposable object that can be used to unsubscribe from the event* @examplediff --git a/packages/sheets-ui/src/facade/f-univer.ts b/packages/sheets-ui/src/facade/f-univer.tsindex 26f97ea895..080f78ec9e 100644--- a/packages/sheets-ui/src/facade/f-univer.ts+++ b/packages/sheets-ui/src/facade/f-univer.ts@@ -29,7 +29,7 @@ import type {import type { CommandListenerSkeletonChange } from '@univerjs/sheets';import type { IEditorBridgeServiceVisibleParam, ISetZoomRatioCommandParams, ISheetPasteByShortKeyParams, IViewportScrollState } from '@univerjs/sheets-ui';import type { FRange } from '@univerjs/sheets/facade';-import type { IBeforeClipboardChangeParam, IBeforeClipboardPasteParam, IBeforeSheetEditEndEventParams, IBeforeSheetEditStartEventParams, ISheetEditChangingEventParams, ISheetEditEndedEventParams, ISheetEditStartedEventParams } from './f-event';+import type { IBeforeClipboardChangeParam, IBeforeClipboardPasteParam, IBeforeSheetEditEndEventParams, IBeforeSheetEditStartEventParams, ISheetEditChangingEventParams, ISheetEditEndedEventParams, ISheetEditStartedEventParams, ISheetZoomEvent } from './f-event';import { CanceledError, DisposableCollection, DOCS_NORMAL_EDITOR_UNIT_ID_KEY, ICommandService, ILogService, IUniverInstanceService, LifecycleService, LifecycleStages, RichTextValue, toDisposable, UniverInstanceType } from '@univerjs/core';import { FUniver } from '@univerjs/core/facade';import { RichTextEditingMutation } from '@univerjs/docs';@@ -266,11 +266,15 @@ export class FUniverSheetsUIMixin extends FUniver implements IFUniverSheetsUIMixif (!target) return;const { workbook, worksheet } = target;- this.fireEvent(this.Event.BeforeSheetZoomChange, {+ const eventParams: ISheetZoomEvent = {zoom: (commandInfo.params as ISetZoomRatioCommandParams).zoomRatio,workbook,worksheet,- });+ };+ this.fireEvent(this.Event.BeforeSheetZoomChange, eventParams);+ if (eventParams.cancel) {+ throw new CanceledError();+ }}));@@ -656,81 +660,45 @@ export class FUniverSheetsUIMixin extends FUniver implements IFUniverSheetsUIMix/*** @ignore*/- // eslint-disable-next-line max-lines-per-function+override _initialize(injector: Injector): void {this._initSheetUIEvent(injector);this._initObserverListener(injector);const commandService = injector.get(ICommandService);+this.registerEventHandler(this.Event.BeforeClipboardChange,- () => {- const disposableCollection = new DisposableCollection();- disposableCollection.add(- commandService.beforeCommandExecuted((commandInfo) => {- switch (commandInfo.id) {- case CopyCommand.id:- case CutCommand.id:- this._beforeClipboardChange();- break;- }- })- );-- return disposableCollection;- }+ () => commandService.beforeCommandExecuted((commandInfo) => {+ switch (commandInfo.id) {+ case CopyCommand.id:+ case CutCommand.id:+ this._beforeClipboardChange();+ break;+ }+ }));this.registerEventHandler(this.Event.ClipboardChanged,- () => {- const disposableCollection = new DisposableCollection();- disposableCollection.add(commandService.beforeCommandExecuted((commandInfo) => {- switch (commandInfo.id) {- case SheetPasteShortKeyCommand.id:- this._beforeClipboardPaste(commandInfo.params);- break;- }- }));-- disposableCollection.add(- commandService.beforeCommandExecuted(async (commandInfo) => {- switch (commandInfo.id) {- case PasteCommand.id:- await this._beforeClipboardPasteAsync();- break;- }- })- );- return disposableCollection;- }+ () => commandService.onCommandExecuted((commandInfo) => {+ switch (commandInfo.id) {+ case CopyCommand.id:+ case CutCommand.id:+ this._clipboardChanged();+ break;+ }+ }));- this.disposeWithMe(commandService.onCommandExecuted((commandInfo) => {- if (COMMAND_LISTENER_SKELETON_CHANGE.indexOf(commandInfo.id) > -1) {- const sheet = this.getActiveSheet();- if (!sheet) return;- const ranges = getSkeletonChangedEffectedRange(commandInfo, sheet.worksheet.getMaxColumns())- .map((range) => this.getWorkbook(range.unitId)?.getSheetBySheetId(range.subUnitId)?.getRange(range.range))- .filter(Boolean) as FRange[];- if (!ranges.length) return;-- this.fireEvent(this.Event.SheetSkeletonChanged, {- workbook: sheet.workbook,- worksheet: sheet.worksheet,- payload: commandInfo as CommandListenerSkeletonChange,- skeleton: sheet.worksheet.getSkeleton()!,- effectedRanges: ranges,- });- }- }));-this.registerEventHandler(- this.Event.ClipboardChanged,+ this.Event.BeforeClipboardPaste,() => commandService.beforeCommandExecuted((commandInfo) => {switch (commandInfo.id) {- case CopyCommand.id:- case CutCommand.id:- this._clipboardChanged();+ case SheetPasteShortKeyCommand.id:+ this._beforeClipboardPaste(commandInfo.params);+ break;+ case PasteCommand.id:+ this._beforeClipboardPasteAsync();break;}})@@ -738,7 +706,7 @@ export class FUniverSheetsUIMixin extends FUniver implements IFUniverSheetsUIMixthis.registerEventHandler(this.Event.ClipboardPasted,- () => commandService.beforeCommandExecuted((commandInfo) => {+ () => commandService.onCommandExecuted((commandInfo) => {switch (commandInfo.id) {case SheetPasteShortKeyCommand.id:this._clipboardPaste(commandInfo.params);@@ -750,7 +718,27 @@ export class FUniverSheetsUIMixin extends FUniver implements IFUniverSheetsUIMix}));- // async listeners+ this.registerEventHandler(+ this.Event.SheetSkeletonChanged,+ () => commandService.onCommandExecuted((commandInfo) => {+ if (COMMAND_LISTENER_SKELETON_CHANGE.indexOf(commandInfo.id) > -1) {+ const sheet = this.getActiveSheet();+ if (!sheet) return;+ const ranges = getSkeletonChangedEffectedRange(commandInfo, sheet.worksheet.getMaxColumns())+ .map((range) => this.getWorkbook(range.unitId)?.getSheetBySheetId(range.subUnitId)?.getRange(range.range))+ .filter(Boolean) as FRange[];+ if (!ranges.length) return;++ this.fireEvent(this.Event.SheetSkeletonChanged, {+ workbook: sheet.workbook,+ worksheet: sheet.worksheet,+ payload: commandInfo as CommandListenerSkeletonChange,+ skeleton: sheet.worksheet.getSkeleton()!,+ effectedRanges: ranges,+ });+ }+ })+ );}private _generateClipboardCopyParam(): IBeforeClipboardChangeParam | undefined {@@ -784,7 +772,7 @@ export class FUniverSheetsUIMixin extends FUniver implements IFUniverSheetsUIMixthis.fireEvent(this.Event.BeforeClipboardChange, eventParams);if (eventParams.cancel) {- throw new Error('Before clipboard change is canceled');+ throw new CanceledError();}}@@ -793,9 +781,6 @@ export class FUniverSheetsUIMixin extends FUniver implements IFUniverSheetsUIMixif (!eventParams) return;this.fireEvent(this.Event.ClipboardChanged, eventParams);- if (eventParams.cancel) {- throw new Error('Clipboard changed is canceled');- }}private _generateClipboardPasteParam(params?: ISheetPasteByShortKeyParams): IBeforeClipboardPasteParam | undefined {@@ -852,7 +837,7 @@ export class FUniverSheetsUIMixin extends FUniver implements IFUniverSheetsUIMixif (!eventParams) return;this.fireEvent(this.Event.BeforeClipboardPaste, eventParams);if (eventParams.cancel) {- throw new Error('Before clipboard paste is canceled');+ throw new CanceledError();}}@@ -861,7 +846,7 @@ export class FUniverSheetsUIMixin extends FUniver implements IFUniverSheetsUIMixif (!eventParams) return;this.fireEvent(this.Event.ClipboardPasted, eventParams);if (eventParams.cancel) {- throw new Error('Clipboard pasted is canceled');+ throw new CanceledError();}}@@ -875,7 +860,7 @@ export class FUniverSheetsUIMixin extends FUniver implements IFUniverSheetsUIMixif (!eventParams) return;this.fireEvent(this.Event.BeforeClipboardPaste, eventParams);if (eventParams.cancel) {- throw new Error('Before clipboard paste is canceled');+ throw new CanceledError();}}@@ -889,7 +874,7 @@ export class FUniverSheetsUIMixin extends FUniver implements IFUniverSheetsUIMixif (!eventParams) return;this.fireEvent(this.Event.ClipboardPasted, eventParams);if (eventParams.cancel) {- throw new Error('Clipboard pasted is canceled');+ throw new CanceledError();}}diff --git a/packages/sheets-ui/src/facade/f-workbook.ts b/packages/sheets-ui/src/facade/f-workbook.tsindex aefef6c7ce..19b9865cad 100644--- a/packages/sheets-ui/src/facade/f-workbook.ts+++ b/packages/sheets-ui/src/facade/f-workbook.ts@@ -18,12 +18,13 @@ import type { IDisposable, Nullable } from '@univerjs/core';import type { IMouseEvent, IPointerEvent, RenderManagerService } from '@univerjs/engine-render';import type { ICellPosWithEvent, IDragCellPosition, IEditorBridgeServiceVisibleParam, IHoverRichTextInfo, IHoverRichTextPosition, IScrollState, SheetSelectionRenderService } from '@univerjs/sheets-ui';+import type { IDialogPartMethodOptions, ISidebarMethodOptions } from '@univerjs/ui';import type { ICellEventParam } from './f-event';import { awaitTime, ICommandService, ILogService, toDisposable } from '@univerjs/core';import { DeviceInputEventType, IRenderManagerService } from '@univerjs/engine-render';import { DragManagerService, HoverManagerService, ISheetSelectionRenderService, SetCellEditVisibleOperation, SheetScrollManagerService } from '@univerjs/sheets-ui';import { FWorkbook } from '@univerjs/sheets/facade';-import { type IDialogPartMethodOptions, IDialogService, type ISidebarMethodOptions, ISidebarService, KeyCode } from '@univerjs/ui';+import { IDialogService, ISidebarService, KeyCode } from '@univerjs/ui';import { filter } from 'rxjs';/**@@ -32,57 +33,107 @@ import { filter } from 'rxjs';export interface IFWorkbookSheetsUIMixin {/*** Open a sidebar.- * @deprecated- * @param params the sidebar options- * @returns the disposable object+ * @deprecated use `univerAPI.openSidebar` instead+ * @param {ISidebarMethodOptions} params the sidebar options+ * @returns {IDisposable} the disposable object+ * @example+ * ```ts+ * univerAPI.openSidebar({+ * id: 'mock-sidebar-id',+ * width: 300,+ * header: {+ * label: 'Sidebar Header',+ * },+ * children: {+ * label: 'Sidebar Content',+ * },+ * footer: {+ * label: 'Sidebar Footer',+ * },+ * onClose: () => {+ * console.log('Sidebar closed')+ * },+ * });+ * ```*/openSiderbar(params: ISidebarMethodOptions): IDisposable;/*** Open a dialog.- * @deprecated- * @param dialog the dialog options- * @returns the disposable object+ * @deprecated use `univerAPI.openDialog` instead+ * @param {IDialogPartMethodOptions} dialog the dialog options+ * @returns {IDisposable} the disposable object+ * @example+ * ```ts+ * import { Button } from '@univerjs/design';+ *+ * univerAPI.openDialog({+ * id: 'mock-dialog-id',+ * width: 500,+ * title: {+ * label: 'Dialog Title',+ * },+ * children: {+ * label: 'Dialog Content',+ * },+ * footer: {+ * title: (+ * <>+ * <Button onClick={() => { console.log('Cancel clicked') }}>Cancel</Button>+ * <Button type="primary" onClick={() => { console.log('Confirm clicked') }} style={{marginLeft: '10px'}}>Confirm</Button>+ * </>+ * )+ * },+ * draggable: true,+ * mask: true,+ * maskClosable: true,+ * });+ * ```*/openDialog(dialog: IDialogPartMethodOptions): IDisposable;/**- * @deprecated use `univerAPI.addEvent(univerAPI.Event.CellClick, () => {})` instead+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.CellClicked, (params) => {})` instead*/onCellClick(callback: (cell: IHoverRichTextInfo) => void): IDisposable;/**- * @deprecated use `univerAPI.addEvent(univerAPI.Event.CellHover, () => {})` instead+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.CellHover, (params) => {})` instead*/onCellHover(callback: (cell: IHoverRichTextPosition) => void): IDisposable;/**- * @deprecated use `univerAPI.addEvent(univerAPI.Event.CellPointerMove, () => {})` instead+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.CellPointerMove, (params) => {})` instead*/onCellPointerMove(callback: (cell: ICellPosWithEvent, event: IPointerEvent | IMouseEvent) => void): IDisposable;+/**- * @deprecated use `univerAPI.addEvent(univerAPI.Event.CellPointerDown, () => {})` instead+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.CellPointerDown, (params) => {})` instead*/onCellPointerDown(callback: (cell: ICellPosWithEvent) => void): IDisposable;+/**- * @deprecated use `univerAPI.addEvent(univerAPI.Event.CellPointerUp, () => {})` instead+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.CellPointerUp, (params) => {})` instead*/onCellPointerUp(callback: (cell: ICellPosWithEvent) => void): IDisposable;+/**- * @deprecated use `univerAPI.addEvent(univerAPI.Event.DragOver, () => {})` instead+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.DragOver, (params) => {})` instead*/onDragOver(callback: (cell: IDragCellPosition) => void): IDisposable;+/**- * @deprecated use `univerAPI.addEvent(univerAPI.Event.Drop, () => {})` instead+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.Drop, (params) => {})` instead*/onDrop(callback: (cell: IDragCellPosition) => void): IDisposable;/**- * Start the editing process- * @returns A boolean value+ * Start the editing process of the current active cell+ * @returns {boolean} Whether the editing process is started successfully* @example* ```ts- * univerAPI.getActiveWorkbook().startEditing();+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * fWorkbook.startEditing();* ```*/startEditing(): boolean;@@ -94,58 +145,77 @@ export interface IFWorkbookSheetsUIMixin {/*** @async- * End the editing process+ * End the editing process of the current active cell* @param {boolean} save - Whether to save the changes, default is true- * @returns {Promise<boolean>} A promise that resolves to a boolean value+ * @returns {Promise<boolean>} Whether the editing process is ended successfully* @example* ```ts- * await univerAPI.getActiveWorkbook().endEditingAsync(false);+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * await fWorkbook.endEditingAsync(false);* ```*/endEditingAsync(save?: boolean): Promise<boolean>;- /*++ /*** Get scroll state of specified sheet.+ * @param {string} sheetId - sheet id* @returns {IScrollState} scroll state* @example* ``` ts- * univerAPI.getActiveWorkbook().getScrollStateBySheetId($sheetId)+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * const fWorksheet = fWorkbook.getActiveSheet();+ *+ * // scroll to cell D10+ * fWorksheet.scrollToCell(9, 3);+ *+ * // get scroll state+ * const scrollState = fWorkbook.getScrollStateBySheetId(fWorksheet.getSheetId());+ * const { offsetX, offsetY, sheetViewStartRow, sheetViewStartColumn } = scrollState;+ * console.log(scrollState); // sheetViewStartRow: 9, sheetViewStartColumn: 3, offsetX: 0, offsetY: 0* ```*/getScrollStateBySheetId(sheetId: string): Nullable<IScrollState>;/*** Disable selection. After disabled, there would be no response for selection.- * @returns {FWorkbook} FWorkbook instance+ * @returns {FWorkbook} FWorkbook instance for chaining* @example* ```ts- * univerAPI.getActiveWorkbook().disableSelection();+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * fWorkbook.disableSelection();* ```*/disableSelection(): FWorkbook;/*** Enable selection. After this you can select range.+ * @returns {FWorkbook} FWorkbook instance for chaining* @example* ```ts- * univerAPI.getActiveWorkbook().enableSelection();+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * fWorkbook.enableSelection();* ```*/enableSelection(): FWorkbook;/*** Set selection invisible, Unlike disableSelection, selection still works, you just can not see them.+ * @returns {FWorkbook} FWorkbook instance for chaining* @example* ```ts- * univerAPI.getActiveWorkbook().transparentSelection();+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * fWorkbook.transparentSelection();* ```*/transparentSelection(): FWorkbook;/*** Set selection visible.+ * @returns {FWorkbook} FWorkbook instance for chaining* @example* ```ts- * univerAPI.getActiveWorkbook().showSelection();+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * fWorkbook.showSelection();* ```*/showSelection(): FWorkbook;diff --git a/packages/sheets-ui/src/facade/f-worksheet.ts b/packages/sheets-ui/src/facade/f-worksheet.tsindex 48048a8f6f..3a14002329 100644--- a/packages/sheets-ui/src/facade/f-worksheet.ts+++ b/packages/sheets-ui/src/facade/f-worksheet.ts@@ -20,7 +20,7 @@ import type { IColumnsHeaderCfgParam, IRowsHeaderCfgParam, RenderComponentType,import type { IScrollState, IViewportScrollState } from '@univerjs/sheets-ui';import { ICommandService, toDisposable } from '@univerjs/core';import { IRenderManagerService, SHEET_VIEWPORT_KEY, sheetContentViewportKeys } from '@univerjs/engine-render';-import { ChangeZoomRatioCommand, SetColumnHeaderHeightCommand, SetRowHeaderWidthCommand, SetWorksheetColAutoWidthCommand, SHEET_VIEW_KEY, SheetScrollManagerService, SheetSkeletonManagerService, SheetsScrollRenderController } from '@univerjs/sheets-ui';+import { SetColumnHeaderHeightCommand, SetRowHeaderWidthCommand, SetWorksheetColAutoWidthCommand, SetZoomRatioCommand, SHEET_VIEW_KEY, SheetScrollManagerService, SheetSkeletonManagerService, SheetsScrollRenderController } from '@univerjs/sheets-ui';import { FWorksheet } from '@univerjs/sheets/facade';/**@@ -29,25 +29,36 @@ import { FWorksheet } from '@univerjs/sheets/facade';export interface IFWorksheetSkeletonMixin {/*** Refresh the canvas.+ * @returns {FWorksheet} The FWorksheet instance for chaining.+ * @example+ * ```ts+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * const fWorksheet = fWorkbook.getActiveSheet();+ * fWorksheet.refreshCanvas();+ * ```*/refreshCanvas(): FWorksheet;+/*** Set zoom ratio of the worksheet.- * @param {number} zoomRatio The zoom ratio to set.It should be in the range of 10 to 400.- * @returns True if the command was successful, false otherwise.+ * @param {number} zoomRatio The zoom ratio to set.It should be in the range of 0.1 to 4.0.+ * @returns {FWorksheet} The FWorksheet instance for chaining.* @example* ```ts* const fWorkbook = univerAPI.getActiveWorkbook();* const fWorksheet = fWorkbook.getActiveSheet();- * fWorksheet.zoom(200);+ *+ * // Set zoom ratio to 200%+ * fWorksheet.zoom(2);* const zoomRatio = fWorksheet.getZoom();- * console.log(zoomRatio); // 200+ * console.log(zoomRatio); // 2* ```*/zoom(zoomRatio: number): FWorksheet;+/*** Get the zoom ratio of the worksheet.- * @returns The zoom ratio of the worksheet.+ * @returns {number} The zoom ratio of the worksheet.* @example* ```ts* const fWorkbook = univerAPI.getActiveWorkbook();@@ -62,10 +73,12 @@ export interface IFWorksheetSkeletonMixin {* Return visible range, sum view range of 4 viewports.* @returns {IRange} - visible range* @example- * ``` ts+ * ```ts* const fWorkbook = univerAPI.getActiveWorkbook();* const fWorksheet = fWorkbook.getActiveSheet();* const visibleRange = fWorksheet.getVisibleRange();+ * console.log(visibleRange);+ * console.log(fWorksheet.getRange(visibleRange).getA1Notation());* ```*/getVisibleRange(): IRange;@@ -75,10 +88,17 @@ export interface IFWorksheetSkeletonMixin {* Based on the limitations of viewport and the number of rows and columns, you can only scroll to the maximum scrollable range.* @param {number} row - Cell row index* @param {number} column - Cell column index- * @returns {FWorksheet} - Current worksheet+ * @returns {FWorksheet} - The FWorksheet instance for chaining.* @example- * ``` ts- * univerAPI.getActiveWorkbook().getActiveSheet().scrollToCell(1, 1);+ * ```ts+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * const fWorksheet = fWorkbook.getActiveSheet();+ *+ * // Scroll to cell D10+ * const fRange = fWorksheet.getRange('D10');+ * const row = fRange.getRow();+ * const column = fRange.getColumn();+ * fWorksheet.scrollToCell(row, column);* ```*/scrollToCell(row: number, column: number): FWorksheet;@@ -87,8 +107,20 @@ export interface IFWorksheetSkeletonMixin {* Get scroll state of current sheet.* @returns {IScrollState} curr scroll state* @example- * ``` ts- * univerAPI.getActiveWorkbook().getActiveSheet().getScrollState()+ * ```ts+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * const fWorksheet = fWorkbook.getActiveSheet();+ *+ * // Scroll to cell D10+ * const fRange = fWorksheet.getRange('D10');+ * const row = fRange.getRow();+ * const column = fRange.getColumn();+ * fWorksheet.scrollToCell(row, column);+ *+ * // Get scroll state+ * const scrollState = fWorksheet.getScrollState();+ * const { offsetX, offsetY, sheetViewStartColumn, sheetViewStartRow } = scrollState;+ * console.log(scrollState); // sheetViewStartRow: 9, sheetViewStartColumn: 3, offsetX: 0, offsetY: 0* ```*/getScrollState(): IScrollState;@@ -107,13 +139,16 @@ export interface IFWorksheetSkeletonMixin {getSkeleton(): Nullable<SpreadsheetSkeleton>;/**- * Set the given column width to fix-content.- * @param {number} columnPosition - Column position+ * Set the column width to auto width.+ * @param {number} columnPosition - Column position index* @param {number} numColumn - Number of columns+ * @returns {FWorksheet} - The FWorksheet instance for chaining.* @example* ```ts* const fWorkbook = univerAPI.getActiveWorkbook();* const fWorksheet = fWorkbook.getActiveSheet();+ *+ * // Set A:C columns to auto width* fWorksheet.setColumnAutoWidth(0, 3);* ```*/@@ -173,31 +208,34 @@ export interface IFWorksheetSkeletonMixin {/*** Set column height for column header.- * @param height+ * @param {number} height - The height to set.+ * @returns {FWorksheet} - The FWorksheet instance for chaining.* @example* ```ts- const sheet = univerAPI.getActiveWorkbook().getActiveSheet();- sheet.setColumnHeaderHeight(100);+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * const fWorksheet = fWorkbook.getActiveSheet();+ * fWorksheet.setColumnHeaderHeight(100);* ```*/setColumnHeaderHeight(height: number): FWorksheet;/*** Set column height for column header.- * @param width+ * @param {number} width - The width to set.+ * @returns {FWorksheet} - The FWorksheet instance for chaining.* @example* ```ts- const sheet = univerAPI.getActiveWorkbook().getActiveSheet();- sheet.setRowHeaderWidth(100);+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * const fWorksheet = fWorkbook.getActiveSheet();+ * fWorksheet.setRowHeaderWidth(100);* ```*/setRowHeaderWidth(width: number): FWorksheet;/**- * @deprecated use `univerAPI.addEvent(univerAPI.Event.Scroll, () => {})` instead+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.Scroll, (params) => {})` instead*/onScroll(callback: (params: Nullable<IViewportScrollState>) => void): IDisposable;-}export class FWorksheetSkeletonMixin extends FWorksheet implements IFWorksheetSkeletonMixin {@@ -225,10 +263,11 @@ export class FWorksheetSkeletonMixin extends FWorksheet implements IFWorksheetSkoverride zoom(zoomRatio: number): FWorksheet {const commandService = this._injector.get(ICommandService);- commandService.syncExecuteCommand(ChangeZoomRatioCommand.id, {+ const _zoomRatio = Math.min(Math.max(zoomRatio, 0.1), 4);+ commandService.executeCommand(SetZoomRatioCommand.id, {unitId: this._workbook.getUnitId(),subUnitId: this._worksheet.getSheetId(),- zoomRatio,+ zoomRatio: _zoomRatio,});return this;}diff --git a/packages/sheets-zen-editor/src/facade/f-workbook.ts b/packages/sheets-zen-editor/src/facade/f-workbook.tsindex 0e45958523..fb10e29009 100644--- a/packages/sheets-zen-editor/src/facade/f-workbook.ts+++ b/packages/sheets-zen-editor/src/facade/f-workbook.ts@@ -24,10 +24,12 @@ import { FWorkbook } from '@univerjs/sheets/facade';export interface IFWorkbookSheetsZenEditorMixin {/*** Start the zen editing process- * @returns A promise that resolves to a boolean indicating whether the zen editing process was started successfully.+ * @returns {Promise<boolean>} A promise that resolves to a boolean indicating whether the zen editing process was started successfully.* @example* ```ts- * univerAPI.getActiveWorkbook().startZenEditingAsync();+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * const success = await fWorkbook.startZenEditingAsync();+ * console.log(success);* ```*/startZenEditingAsync(): Promise<boolean>;@@ -36,10 +38,12 @@ export interface IFWorkbookSheetsZenEditorMixin {* End the zen editing process* @async* @param {boolean} save - Whether to save the changes, default is true- * @returns A promise that resolves to a boolean indicating whether the zen editing process was ended successfully.+ * @returns {Promise<boolean>} A promise that resolves to a boolean indicating whether the zen editing process was ended successfully.* @example* ```ts- * univerAPI.getActiveWorkbook().endZenEditingAsync(false);+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * const success = await fWorkbook.endZenEditingAsync(false);+ * console.log(success);* ```*/endZenEditingAsync(save?: boolean): Promise<boolean>;diff --git a/packages/ui/src/facade/f-enum.ts b/packages/ui/src/facade/f-enum.tsindex b884a7956b..0aeefae6cc 100644--- a/packages/ui/src/facade/f-enum.ts+++ b/packages/ui/src/facade/f-enum.ts@@ -15,13 +15,21 @@*/import { FEnum } from '@univerjs/core/facade';-import { BuiltInUIPart } from '@univerjs/ui';+import { BuiltInUIPart, KeyCode } from '@univerjs/ui';/*** @ignore*/interface IFUIEnumMixin {+ /**+ * Built-in UI parts.+ */get BuiltInUIPart(): typeof BuiltInUIPart;++ /**+ * Key codes.+ */+ get KeyCode(): typeof KeyCode;}/**@@ -31,6 +39,10 @@ export class FUIEnum extends FEnum implements IFUIEnumMixin {override get BuiltInUIPart(): typeof BuiltInUIPart {return BuiltInUIPart;};++ override get KeyCode(): typeof KeyCode {+ return KeyCode;+ }}FEnum.extend(FUIEnum);diff --git a/packages/ui/src/facade/f-hooks.ts b/packages/ui/src/facade/f-hooks.tsindex b90122c9ae..fa802823f3 100644--- a/packages/ui/src/facade/f-hooks.ts+++ b/packages/ui/src/facade/f-hooks.ts@@ -25,20 +25,15 @@ import { CopyCommand, PasteCommand, SheetPasteShortKeyCommandName } from '@univeexport interface IFHooksSheetsUIMixin {/*** The onBeforeCopy event is fired before a copy operation is performed.+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.BeforeClipboardChange, (params) => {})` instead* @param callback Callback function that will be called when the event is fired* @returns A disposable object that can be used to unsubscribe from the event*/onBeforeCopy(callback: () => void): IDisposable;- /**- * The onBeforeCopy event is fired before a copy operation is performed.- * @param callback Callback function that will be called when the event is fired- * @returns A disposable object that can be used to unsubscribe from the event- */- onBeforePaste(callback: () => void): IDisposable;-/*** The onCopy event is fired after a copy operation is performed.+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.ClipboardChanged, (params) => {})` instead* @param callback Callback function that will be called when the event is fired* @returns A disposable object that can be used to unsubscribe from the event*/@@ -46,6 +41,7 @@ export interface IFHooksSheetsUIMixin {/*** The onBeforePaste event is fired before a paste operation is performed.+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.BeforeClipboardPaste, (params) => {})` instead* @param callback Callback function that will be called when the event is fired* @returns A disposable object that can be used to unsubscribe from the event*/@@ -53,6 +49,7 @@ export interface IFHooksSheetsUIMixin {/*** The onPaste event is fired after a paste operation is performed.+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.ClipboardPasted, (params) => {})` instead* @param callback Callback function that will be called when the event is fired* @returns A disposable object that can be used to unsubscribe from the event*/diff --git a/packages/ui/src/facade/f-menu-builder.ts b/packages/ui/src/facade/f-menu-builder.tsindex b78fefbf99..3ff244cae5 100644--- a/packages/ui/src/facade/f-menu-builder.ts+++ b/packages/ui/src/facade/f-menu-builder.ts@@ -101,14 +101,18 @@ abstract class FMenuBase extends FBase {* univerAPI.createMenu({* id: 'custom-menu-id-1',* title: 'Custom Menu 1',- * action: () => {},+ * action: () => {+ * console.log('Custom Menu 1 clicked');+ * },* }).appendTo('contextMenu.others');** // This menu item will only appear on the `contextMenu.others` section on the main area.* univerAPI.createMenu({* id: 'custom-menu-id-2',* title: 'Custom Menu 2',- * action: () => { console.log(123); },+ * action: () => {+ * console.log('Custom Menu 2 clicked');+ * },* }).appendTo(['contextMenu.mainArea', 'contextMenu.others']);* ```*/@@ -249,6 +253,35 @@ export class FSubmenu extends FMenuBase {* Add a menu to the submenu. It can be a {@link FMenu} or a {@link FSubmenu}.* @param {FMenu | FSubmenu} submenu - Menu to add to the submenu.* @returns {FSubmenu} The FSubmenu itself for chaining calls.+ * @example+ * ```typescript+ * // Create two leaf menus.+ * const menu1 = univerAPI.createMenu({+ * id: 'submenu-nested-1',+ * title: 'Item 1',+ * action: () => {+ * console.log('Item 1 clicked');+ * }+ * });+ * const menu2 = univerAPI.createMenu({+ * id: 'submenu-nested-2',+ * title: 'Item 2',+ * action: () => {+ * console.log('Item 2 clicked');+ * }+ * });+ *+ * // Add the leaf menus to a submenu.+ * const submenu = univerAPI.createSubmenu({ id: 'submenu-nested', title: 'Nested Submenu' })+ * .addSubmenu(menu1)+ * .addSeparator()+ * .addSubmenu(menu2);+ *+ * // Create a root submenu append to the `contextMenu.others` section.+ * univerAPI.createSubmenu({ id: 'custom-submenu', title: 'Custom Submenu' })+ * .addSubmenu(submenu)+ * .appendTo('contextMenu.others');+ * ```*/addSubmenu(submenu: FMenu | FSubmenu): this {this._submenus.push(submenu);@@ -258,6 +291,32 @@ export class FSubmenu extends FMenuBase {/*** Add a separator to the submenu.* @returns {FSubmenu} The FSubmenu itself for chaining calls.+ * @example+ * ```typescript+ * // Create two leaf menus.+ * const menu1 = univerAPI.createMenu({+ * id: 'submenu-nested-1',+ * title: 'Item 1',+ * action: () => {+ * console.log('Item 1 clicked');+ * }+ * });+ * const menu2 = univerAPI.createMenu({+ * id: 'submenu-nested-2',+ * title: 'Item 2',+ * action: () => {+ * console.log('Item 2 clicked');+ * }+ * });+ *+ * // Add the leaf menus to a submenu and add a separator between them.+ * // Append the submenu to the `contextMenu.others` section.+ * univerAPI.createSubmenu({ id: 'submenu-nested', title: 'Nested Submenu' })+ * .addSubmenu(menu1)+ * .addSeparator()+ * .addSubmenu(menu2)+ * .appendTo('contextMenu.others');+ * ```*/addSeparator(): this {this._menuByGroups.push(this._submenus);diff --git a/packages/ui/src/facade/f-shortcut.ts b/packages/ui/src/facade/f-shortcut.tsindex 34e871ab7a..b7bf2cd410 100644--- a/packages/ui/src/facade/f-shortcut.ts+++ b/packages/ui/src/facade/f-shortcut.ts@@ -14,10 +14,11 @@* limitations under the License.*/-import type { IDisposable } from '@univerjs/core';+import type { IDisposable, Workbook } from '@univerjs/core';import type { IShortcutItem } from '@univerjs/ui';-import { Inject, Injector } from '@univerjs/core';+import { Inject, Injector, IUniverInstanceService, UniverInstanceType } from '@univerjs/core';import { FBase } from '@univerjs/core/facade';+import { IRenderManagerService } from '@univerjs/engine-render';import { IShortcutService } from '@univerjs/ui';/**@@ -29,6 +30,8 @@ export class FShortcut extends FBase {constructor(@Inject(Injector) protected readonly _injector: Injector,+ @Inject(IRenderManagerService) private _renderManagerService: IRenderManagerService,+ @IUniverInstanceService protected readonly _univerInstanceService: IUniverInstanceService,@IShortcutService protected readonly _shortcutService: IShortcutService) {super();@@ -67,6 +70,54 @@ export class FShortcut extends FBase {return this;}+ /**+ * Trigger shortcut of Univer by a KeyboardEvent and return the matched shortcut item.+ * @param {KeyboardEvent} e - The KeyboardEvent to trigger.+ * @returns {IShortcutItem<object> | undefined} The matched shortcut item.+ *+ * @example+ * ```typescript+ * // Assum the current sheet is empty sheet.+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * const fWorksheet = fWorkbook.getActiveSheet();+ * const fRange = fWorksheet.getRange('A1');+ *+ * // Set A1 cell active and set value to 'Hello Univer'.+ * fRange.activate();+ * fRange.setValue('Hello Univer');+ * console.log(fRange.getCellStyle().bold); // false+ *+ * // Set A1 cell bold by shortcut.+ * const fShortcut = univerAPI.getShortcut();+ * const pseudoEvent = new KeyboardEvent('keydown', {+ * key: 'b',+ * ctrlKey: true,+ * keyCode: univerAPI.Enum.KeyCode.B+ * });+ * const ifShortcutItem = fShortcut.triggerShortcut(pseudoEvent);+ * if (ifShortcutItem) {+ * const commandId = ifShortcutItem.id;+ * console.log(fRange.getCellStyle().bold); // true+ * }+ * ```+ */+ triggerShortcut(e: KeyboardEvent): IShortcutItem<object> | undefined {+ const workbook = this._univerInstanceService.getCurrentUnitForType<Workbook>(UniverInstanceType.UNIVER_SHEET);+ if (!workbook) {+ return;+ }++ const renderUnit = this._renderManagerService.getRenderById(workbook.getUnitId());+ if (!renderUnit) {+ return;+ }++ const canvas = renderUnit.engine.getCanvasElement();+ canvas.dispatchEvent(e);++ return this._shortcutService.dispatch(e);+ }+/*** Dispatch a KeyboardEvent to the shortcut service and return the matched shortcut item.* @param {KeyboardEvent} e - The KeyboardEvent to dispatch.diff --git a/packages/ui/src/facade/f-univer.ts b/packages/ui/src/facade/f-univer.tsindex ae5f776948..8a9c1f20cc 100644--- a/packages/ui/src/facade/f-univer.ts+++ b/packages/ui/src/facade/f-univer.ts@@ -30,127 +30,323 @@ import { FShortcut } from './f-shortcut';export interface IFUniverUIMixin {/*** Return the URL of the current page.- * @returns the [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL) object+ * @returns {URL} the [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL) object+ * @example+ * ```ts+ * console.log(univerAPI.getURL());+ * ```*/getURL(): URL;+/*** Get the Shortcut handler to interact with Univer's shortcut functionalities.+ * @returns the {@link FShortcut} object+ * @example+ * ```ts+ * const fShortcut = univerAPI.getShortcut();+ *+ * // Disable shortcuts of Univer+ * fShortcut.disableShortcut();+ *+ * // Enable shortcuts of Univer+ * fShortcut.enableShortcut();+ *+ * // Trigger a shortcut+ * const fWorkbook = univerAPI.getActiveWorkbook();+ * const fWorksheet = fWorkbook.getActiveSheet();+ * const fRange = fWorksheet.getRange('A1');+ * fRange.activate();+ * fRange.setValue('Hello Univer');+ * console.log(fRange.getCellStyle().bold); // false+ * const pseudoEvent = new KeyboardEvent('keydown', {+ * key: 'b',+ * ctrlKey: true,+ * keyCode: univerAPI.Enum.KeyCode.B+ * });+ * const ifShortcutItem = fShortcut.triggerShortcut(pseudoEvent);+ * if (ifShortcutItem) {+ * const commandId = ifShortcutItem.id;+ * console.log(fRange.getCellStyle().bold); // true+ * }+ * ```*/getShortcut(): FShortcut;+/*** Copy the current selected content of the currently focused unit into your system clipboard.*/copy(): Promise<boolean>;+/*** Paste into the current selected position of the currently focused unit from your system clipboard.+ * ```*/paste(): Promise<boolean>;+/*** Create a menu build object. You can insert new menus into the UI.* @param {IFacadeMenuItem} menuItem the menu item+ * @returns the {@link FMenu} object* @example* ```ts+ * // Univer Icon can be viewed at https://univer.ai/en-US/icons+ * import { SmileSingle } from '@univerjs/icons'+ *+ * // Create a custom menu with an univer icon+ * univerAPI.registerComponent('custom-menu-icon', SmileSingle);+ * univerAPI.createMenu({+ * id: 'custom-menu',+ * icon: 'custom-menu-icon',+ * title: 'Custom Menu',+ * tooltip: 'Custom Menu Tooltip',+ * action: () => {+ * console.log('Custom Menu Clicked');+ * },+ * }).appendTo('ribbon.start.others');+ *+ * // Or+ * // Create a custom menu with an image icon+ * univerAPI.registerComponent('custom-menu-icon', () => {+ * return <img src="https://avatars.githubusercontent.com/u/61444807?s=48&v=4" alt="" style={{ width: '16px', height: '16px' }} />;+ * });* univerAPI.createMenu({* id: 'custom-menu',+ * icon: 'custom-menu-icon',* title: 'Custom Menu',- * action: () => {},+ * tooltip: 'Custom Menu Tooltip',+ * action: () => {+ * console.log('Custom Menu Clicked');+ * },+ * }).appendTo('ribbon.start.others');+ *+ * // Or+ * // Create a custom menu without an icon+ * univerAPI.createMenu({+ * id: 'custom-menu',+ * title: 'Custom Menu',+ * tooltip: 'Custom Menu Tooltip',+ * action: () => {+ * console.log('Custom Menu Clicked');+ * },* }).appendTo('ribbon.start.others');* ```- * @returns the {@link FMenu} object*/createMenu(menuItem: IFacadeMenuItem): FMenu;+/*** Create a menu that contains submenus, and later you can append this menu and its submenus to the UI.- * @param submenuItem the submenu item+ * @param {IFacadeSubmenuItem} submenuItem the submenu item+ * @returns the {@link FSubmenu} object* @example* ```ts+ * // Create two leaf menus.+ * const menu1 = univerAPI.createMenu({+ * id: 'submenu-nested-1',+ * title: 'Item 1',+ * action: () => {+ * console.log('Item 1 clicked');+ * }+ * });+ * const menu2 = univerAPI.createMenu({+ * id: 'submenu-nested-2',+ * title: 'Item 2',+ * action: () => {+ * console.log('Item 2 clicked');+ * }+ * });+ *+ * // Add the leaf menus to a submenu.+ * const submenu = univerAPI.createSubmenu({ id: 'submenu-nested', title: 'Nested Submenu' })+ * .addSubmenu(menu1)+ * .addSeparator()+ * .addSubmenu(menu2);+ *+ * // Create a root submenu append to the `contextMenu.others` section.* univerAPI.createSubmenu({ id: 'custom-submenu', title: 'Custom Submenu' })- * .addSubmenu(univerAPI.createSubmenu({ id: 'submenu-nested', title: 'Nested Submenu' })- * .addSubmenu(univerAPI.createMenu({ id: 'submenu-nested-1', title: 'Item 1', action: () => {} }))- * .addSeparator()- * .addSubmenu(univerAPI.createMenu({ id: 'submenu-nested-2', title: 'Item 2', action: () => {} }))- * )+ * .addSubmenu(submenu)* .appendTo('contextMenu.others');* ```- * @returns the {@link FSubmenu} object*/createSubmenu(submenuItem: IFacadeSubmenuItem): FSubmenu;+/*** Open a sidebar.- * @deprecated Please use `openSidebar` instead.- * @param params the sidebar options- * @returns the disposable object+ * @deprecated Please use `univerAPI.openSidebar` instead.+ * @param {ISidebarMethodOptions} params the sidebar options+ * @returns {IDisposable} the disposable object*/openSiderbar(params: ISidebarMethodOptions): IDisposable;+/*** Open a sidebar.- * @deprecated Please use `openSidebar` instead.- * @param params the sidebar options- * @returns the disposable object+ * @param {ISidebarMethodOptions} params the sidebar options+ * @returns {IDisposable} the disposable object+ * @example+ * ```ts+ * univerAPI.openSidebar({+ * id: 'mock-sidebar-id',+ * width: 300,+ * header: {+ * label: 'Sidebar Header',+ * },+ * children: {+ * label: 'Sidebar Content',+ * },+ * footer: {+ * label: 'Sidebar Footer',+ * },+ * onClose: () => {+ * console.log('Sidebar closed')+ * },+ * });+ * ```*/openSidebar(params: ISidebarMethodOptions): IDisposable;+/*** Open a dialog.- * @param dialog the dialog options- * @returns the disposable object+ * @param {IDialogPartMethodOptions} dialog the dialog options+ * @returns {IDisposable} the disposable object+ * @example+ * ```ts+ * import { Button } from '@univerjs/design';+ *+ * univerAPI.openDialog({+ * id: 'mock-dialog-id',+ * width: 500,+ * title: {+ * label: 'Dialog Title',+ * },+ * children: {+ * label: 'Dialog Content',+ * },+ * footer: {+ * title: (+ * <>+ * <Button onClick={() => { console.log('Cancel clicked') }}>Cancel</Button>+ * <Button type="primary" onClick={() => { console.log('Confirm clicked') }} style={{marginLeft: '10px'}}>Confirm</Button>+ * </>+ * )+ * },+ * draggable: true,+ * mask: true,+ * maskClosable: true,+ * });+ * ```*/openDialog(dialog: IDialogPartMethodOptions): IDisposable;+/*** Get the component manager- * @returns The component manager+ * @returns {ComponentManager} The component manager+ * @example+ * ```ts+ * const componentManager = univerAPI.getComponentManager();+ * console.log(componentManager);+ * ```*/getComponentManager(): ComponentManager;+/*** Show a message.+ * @returns {FUniver} the {@link FUniver} instance for chaining* @example* ```ts- * const message = univerAPI.showMessage({ key: 'my-message', content: 'Warning', duration: 0 });- *- * someAction().then(() => message.dispose());+ * univerAPI.showMessage({+ * content: 'Success',+ * type: 'success',+ * duration: 3000,+ * });* ```*/- showMessage(options: IMessageProps): void;+ showMessage(options: IMessageProps): FUniver;/*** Set the visibility of a built-in UI part.- * @param key the built-in UI part- * @param visible the visibility- * @returns the {@link FUniver} object+ * @param {BuiltInUIPart} key the built-in UI part+ * @param {boolean} visible the visibility+ * @returns the {@link FUniver} instance for chaining* example* ```ts- * univerAPI.setUIVisible(BuiltInUIPart.HEADER, false);+ * // Hide header, footer, and toolbar+ * univerAPI.setUIVisible(univerAPI.Enum.BuiltInUIPart.HEADER, false)+ * .setUIVisible(univerAPI.Enum.BuiltInUIPart.FOOTER, false)+ * .setUIVisible(univerAPI.Enum.BuiltInUIPart.TOOLBAR, false);+ *+ * // Show in 3 seconds+ * setTimeout(() => {+ * univerAPI.setUIVisible(univerAPI.Enum.BuiltInUIPart.HEADER, true)+ * .setUIVisible(univerAPI.Enum.BuiltInUIPart.FOOTER, true)+ * .setUIVisible(univerAPI.Enum.BuiltInUIPart.TOOLBAR, true);+ * }, 3000);* ```*/setUIVisible(key: BuiltInUIPart, visible: boolean): FUniver;/*** Get the visibility of a built-in UI part.- * @param key the built-in UI part- * @returns the visibility- * example+ * @param {BuiltInUIPart} key the built-in UI part+ * @returns {boolean} the visibility+ * @example* ```ts- * univerAPI.isUIVisible(BuiltInUIPart.HEADER);+ * // Hide header+ * univerAPI.setUIVisible(univerAPI.Enum.BuiltInUIPart.HEADER, false);+ * console.log(univerAPI.isUIVisible(univerAPI.Enum.BuiltInUIPart.HEADER)); // false* ```*/isUIVisible(key: BuiltInUIPart): boolean;/**- * register an component to a built-in UI part- * @param key the built-in UI part+ * Register an component to a built-in UI part+ * @param {BuiltInUIPart} key the built-in UI part* @param component the react component* @example* ```ts- * univerAPI.registerUIPart(BuiltInUIPart.CUSTOM_HEADER, () => React.createElement('h1', null, 'Custom Header'));+ * univerAPI.registerUIPart(univerAPI.Enum.BuiltInUIPart.CUSTOM_HEADER, () => React.createElement('h1', null, 'Custom Header'));* ```*/registerUIPart(key: BuiltInUIPart, component: any): IDisposable;/**- * register an component.- * @param component+ * Register an component.+ * @param {string} name - The name of the component.+ * @param {ComponentType} component - The component.+ * @param {IComponentOptions} [options] - The options of the component.+ * @returns {IDisposable} The disposable object.* @example* ```ts- * univerAPI.registerComponent('my-comp', () => React.createElement('h1', null, 'Custom Header'));+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();+ *+ * // Register a range loading component+ * const RangeLoading = () => {+ * const divStyle = {+ * width: '100%',+ * height: '100%',+ * backgroundColor: '#fff',+ * border: '1px solid #ccc',+ * boxSizing: 'border-box' as const,+ * display: 'flex',+ * justifyContent: 'center',+ * alignItems: 'center',+ * textAlign: 'center' as const,+ * transformOrigin: 'top left',+ * };+ *+ * return (+ * <div style={divStyle}>+ * Loading...+ * </div>+ * );+ * };+ * univerAPI.registerComponent('RangeLoading', RangeLoading);+ *+ * // Add the range loading component covering the range A1:C3+ * const range = fWorksheet.getRange('A1:C3');+ * const disposeable = fWorksheet.addFloatDomToRange(range, { componentKey: 'RangeLoading' }, {}, 'myRangeLoading');+ *+ * setTimeout(() => {+ * disposeable?.dispose();+ * }, 2000);* ```*/registerComponent(name: string, component: ComponentType, options?: IComponentOptions): IDisposable;@@ -158,7 +354,7 @@ export interface IFUniverUIMixin {/*** Set a unit as the current unit and render a unit in the workbench's main area. If you have multiple units in Univer,* you should call this method to render the unit.- * @param unitId Unit to be rendered.+ * @param {string} unitId Unit to be rendered.** @example* Let's assume you have created two units, `unit1` and `unit2`. Univer is rendering `unit1` and you want todiff --git a/packages/watermark/src/facade/f-univer.ts b/packages/watermark/src/facade/f-univer.tsindex ad0d75e043..19c8f704a0 100644--- a/packages/watermark/src/facade/f-univer.ts+++ b/packages/watermark/src/facade/f-univer.ts@@ -25,13 +25,35 @@ import { WatermarkImageBaseConfig, WatermarkService, WatermarkTextBaseConfig } fexport interface IFUniverWatermarkMixin {/*** Adds a watermark to the unit. Supports both text and image watermarks based on the specified type.- * @param {IWatermarkTypeEnum.Text | IWatermarkTypeEnum.Image} type - The type of watermark to add. Can be either 'Text' or 'Image'.- * @param {ITextWatermarkConfig | IImageWatermarkConfig} config - The configuration object for the watermark.- * - If the type is 'Text', the config should follow the ITextWatermarkConfig interface.- * - If the type is 'Image', the config should follow the IImageWatermarkConfig interface.+ * @param {IWatermarkTypeEnum.Text} type - The type of watermark to add is Text.+ * @param {ITextWatermarkConfig} config - The configuration object for the text type watermark.+ * @returns {FUniver} The {@link FUniver} instance for chaining.* @throws {Error} Throws an error if the watermark type is unknown.+ * @example+ * ```ts+ * univerAPI.addWatermark('text', {+ * content: 'Univer',+ * fontSize: 20,+ * repeat: true,+ * });+ * ```*/addWatermark(type: IWatermarkTypeEnum.Text, config: ITextWatermarkConfig): FUniver;+ /**+ * Adds a watermark to the unit. Supports both text and image watermarks based on the specified type.+ * @param {IWatermarkTypeEnum.Image} type - The type of watermark to add is Image.+ * @param {IImageWatermarkConfig} config - The configuration object for the image type watermark.+ * @returns {FUniver} The {@link FUniver} instance for chaining.+ * @throws {Error} Throws an error if the watermark type is unknown.+ * @example+ * ```ts+ * univerAPI.addWatermark('image', {+ * url: 'https://avatars.githubusercontent.com/u/61444807?s=48&v=4',+ * width: 100,+ * height: 100,+ * });+ * ```+ */addWatermark(type: IWatermarkTypeEnum.Image, config: IImageWatermarkConfig): FUniver;addWatermark(type: IWatermarkTypeEnum.Text | IWatermarkTypeEnum.Image,@@ -40,8 +62,12 @@ export interface IFUniverWatermarkMixin {/*** Deletes the currently applied watermark from the unit.- ** This function retrieves the watermark service and invokes the method to remove any existing watermark configuration.+ * @returns {FUniver} The {@link FUniver} instance for chaining.+ * @example+ * ```ts+ * univerAPI.deleteWatermark();+ * ```*/deleteWatermark(): FUniver;}