Skip to content

Build your own AI office with Univer Office SDK. Bring editing, calculation, collaboration, and file processing into your product for people and AI agents. Built on an extensible open-source core.

docs(facade): supplement notes and example (#4713)

wpxp123456da83f66f93d8
diff --git a/examples/src/sheets/main.ts b/examples/src/sheets/main.ts
index 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);
});
// checked
diff --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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 IFUniverCommentMixin
col: 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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
* @example
diff --git a/packages/sheets-ui/src/facade/f-univer.ts b/packages/sheets-ui/src/facade/f-univer.ts
index 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 IFUniverSheetsUIMix
if (!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 IFUniverSheetsUIMix
this.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 IFUniverSheetsUIMix
this.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 IFUniverSheetsUIMix
if (!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 IFUniverSheetsUIMix
if (!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 IFUniverSheetsUIMix
if (!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 IFUniverSheetsUIMix
if (!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 IFUniverSheetsUIMix
if (!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.ts
index 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.ts
index 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 IFWorksheetSk
override 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.ts
index 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.ts
index 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.ts
index 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 '@unive
export 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.ts
index 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.ts
index 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.ts
index 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 to
diff --git a/packages/watermark/src/facade/f-univer.ts b/packages/watermark/src/facade/f-univer.ts
index 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 } f
export 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;
}