@univerjs/sheets-thread-comment 0.5.3 → 0.5.4

package/lib/types/facade/f-event.d.ts

@@ -0,0 +1,247 @@
+import { IEventBase, RichTextValue, FEventName } from '@univerjs/core';
+import { FWorkbook, FWorksheet } from '@univerjs/sheets/facade';
+import { FTheadCommentItem, FThreadComment } from './f-thread-comment';
+interface ICommentEventMixin {
+    /**
+     * Event fired after comment added
+     * @see {@link ISheetCommentAddEvent}
+     * @example
+     * ```ts
+     * univerAPI.addEventListener(CommentEvent.CommentAdded, (event) => {
+     *     const { comment, workbook, worksheet, row, col } = event;
+     *     console.log(event);
+     * });
+     * ```
+     */
+    readonly CommentAdded: 'CommentAdded';
+    /**
+     * Event fired before comment added
+     * @see {@link IBeforeSheetCommentAddEvent}
+     * @example
+     * ```ts
+     * univerAPI.addEventListener(CommentEvent.BeforeCommentAdd, (event) => {
+     *     const { comment, workbook, worksheet, row, col } = event;
+     *     console.log(event);
+     * });
+     * ```
+     */
+    readonly BeforeCommentAdd: 'BeforeCommentAdd';
+    /**
+     * Event fired after comment updated
+     * @see {@link ISheetCommentUpdateEvent}
+     * @example
+     * ```ts
+     * univerAPI.addEventListener(CommentEvent.CommentUpdated, (event) => {
+     *     const { comment, workbook, worksheet, row, col } = event;
+     *     console.log(event);
+     * });
+     * ```
+     */
+    readonly CommentUpdated: 'CommentUpdated';
+    /**
+     * Event fired before comment update
+     * @see {@link IBeforeSheetCommentUpdateEvent}
+     * @example
+     * ```ts
+     * univerAPI.addEventListener(CommentEvent.BeforeCommentUpdate, (event) => {
+     *     const { comment, workbook, worksheet, row, col, newContent } = event;
+     *     console.log(event);
+     * });
+     * ```
+     */
+    readonly BeforeCommentUpdate: 'BeforeCommentUpdate';
+    /**
+     * Event fired after comment deleted
+     * @see {@link ISheetCommentDeleteEvent}
+     * @example
+     * ```ts
+     * univerAPI.addEventListener(CommentEvent.CommentDeleted, (event) => {
+     *     const { commentId, workbook, worksheet } = event;
+     *     console.log(event);
+     * });
+     * ```
+     */
+    readonly CommentDeleted: 'CommentDeleted';
+    /**
+     * Event fired before comment delete
+     * @see {@link IBeforeSheetCommentDeleteEvent}
+     * @example
+     * ```ts
+     * univerAPI.addEventListener(CommentEvent.BeforeCommentDeleted, (event) => {
+     *     const { commentId, workbook, worksheet } = event;
+     *     console.log(event);
+     * });
+     * ```
+     */
+    readonly BeforeCommentDeleted: 'BeforeCommentDeleted';
+    /**
+     * 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);
+     * });
+     * ```
+     */
+    readonly CommentResolved: 'CommentResolved';
+    /**
+     * Event fired before comment resolve
+     * @see {@link ISheetCommentResolveEvent}
+     * @example
+     * ```ts
+     * univerAPI.addEventListener(CommentEvent.BeforeCommentResolve, (event) => {
+     *     const { comment, row, col, resolved, workbook, worksheet } = event;
+     *     console.log(event);
+     * });
+     * ```
+     */
+    readonly BeforeCommentResolve: 'BeforeCommentResolve';
+}
+export declare class FCommentEvent extends FEventName {
+    get CommentAdded(): 'CommentAdded';
+    get BeforeCommentAdd(): 'BeforeCommentAdd';
+    get CommentUpdated(): 'CommentUpdated';
+    get BeforeCommentUpdate(): 'BeforeCommentUpdate';
+    get CommentDeleted(): 'CommentDeleted';
+    get BeforeCommentDeleted(): 'BeforeCommentDeleted';
+    get CommentResolved(): 'CommentResolved';
+    get BeforeCommentResolve(): 'BeforeCommentResolve';
+}
+/**
+ * Event interface triggered after a comment is added to a sheet
+ * @interface ISheetCommentAddEvent
+ * @augments {IEventBase}
+ */
+export interface ISheetCommentAddEvent extends IEventBase {
+    /** The workbook instance */
+    workbook: FWorkbook;
+    /** The worksheet where the comment is added */
+    worksheet: FWorksheet;
+    /** Row index of the comment */
+    row: number;
+    /** Column index of the comment */
+    col: number;
+    /** The added comment object */
+    comment: FThreadComment;
+}
+/**
+ * Event interface triggered before a comment is added to a sheet
+ * @interface IBeforeSheetCommentAddEvent
+ * @augments {IEventBase}
+ */
+export interface IBeforeSheetCommentAddEvent extends IEventBase {
+    /** The workbook instance */
+    workbook: FWorkbook;
+    /** The worksheet where the comment will be added */
+    worksheet: FWorksheet;
+    /** Row index for the new comment */
+    row: number;
+    /** Column index for the new comment */
+    col: number;
+    /** The comment item to be added */
+    comment: FTheadCommentItem;
+}
+/**
+ * Event interface triggered after a comment is updated in a sheet
+ * @interface ISheetCommentUpdateEvent
+ * @augments {IEventBase}
+ */
+export interface ISheetCommentUpdateEvent extends IEventBase {
+    /** The workbook instance */
+    workbook: FWorkbook;
+    /** The worksheet containing the updated comment */
+    worksheet: FWorksheet;
+    /** Row index of the comment */
+    row: number;
+    /** Column index of the comment */
+    col: number;
+    /** The updated comment object */
+    comment: FThreadComment;
+}
+/**
+ * Event interface triggered before a comment is updated in a sheet
+ * @interface IBeforeSheetCommentUpdateEvent
+ * @augments {IEventBase}
+ */
+export interface IBeforeSheetCommentUpdateEvent extends IEventBase {
+    /** The workbook instance */
+    workbook: FWorkbook;
+    /** The worksheet containing the comment */
+    worksheet: FWorksheet;
+    /** Row index of the comment */
+    row: number;
+    /** Column index of the comment */
+    col: number;
+    /** The current comment object */
+    comment: FThreadComment;
+    /** The new content to replace the existing comment */
+    newContent: RichTextValue;
+}
+/**
+ * Event interface triggered before a comment is deleted from a sheet
+ * @interface IBeforeSheetCommentDeleteEvent
+ * @augments {IEventBase}
+ */
+export interface IBeforeSheetCommentDeleteEvent extends IEventBase {
+    /** The workbook instance */
+    workbook: FWorkbook;
+    /** The worksheet containing the comment */
+    worksheet: FWorksheet;
+    /** Row index of the comment */
+    row: number;
+    /** Column index of the comment */
+    col: number;
+    /** The comment to be deleted */
+    comment: FThreadComment;
+}
+/**
+ * Event interface triggered after a comment is deleted from a sheet
+ * @interface ISheetCommentDeleteEvent
+ * @augments {IEventBase}
+ */
+export interface ISheetCommentDeleteEvent extends IEventBase {
+    /** The workbook instance */
+    workbook: FWorkbook;
+    /** The worksheet that contained the comment */
+    worksheet: FWorksheet;
+    /** The ID of the deleted comment */
+    commentId: string;
+}
+/**
+ * Event interface triggered when a comment's resolve status changes
+ * @interface ISheetCommentResolveEvent
+ * @augments {IEventBase}
+ */
+export interface ISheetCommentResolveEvent extends IEventBase {
+    /** The workbook instance */
+    workbook: FWorkbook;
+    /** The worksheet containing the comment */
+    worksheet: FWorksheet;
+    /** Row index of the comment */
+    row: number;
+    /** Column index of the comment */
+    col: number;
+    /** The comment object */
+    comment: FThreadComment;
+    /** The new resolve status */
+    resolved: boolean;
+}
+export interface ISheetCommentEventConfig {
+    BeforeCommentAdd: IBeforeSheetCommentAddEvent;
+    CommentAdded: ISheetCommentAddEvent;
+    BeforeCommentUpdate: IBeforeSheetCommentUpdateEvent;
+    CommentUpdated: ISheetCommentUpdateEvent;
+    BeforeCommentDeleted: IBeforeSheetCommentDeleteEvent;
+    CommentDeleted: ISheetCommentDeleteEvent;
+    BeforeCommentResolve: ISheetCommentResolveEvent;
+    CommentResolved: ISheetCommentResolveEvent;
+}
+declare module '@univerjs/core' {
+    interface FEventName extends ICommentEventMixin {
+    }
+    interface IEventParamConfig extends ISheetCommentEventConfig {
+    }
+}
+export {};

package/lib/types/facade/f-range.d.ts

@@ -1,28 +1,40 @@
 import { IDocumentBody, Nullable } from '@univerjs/core';
 import { FRange } from '@univerjs/sheets/facade';
-import { FThreadComment } from './f-thread-comment';
+import { FTheadCommentBuilder, FThreadComment } from './f-thread-comment';
 export interface IFRangeCommentMixin {
     /**
      * Get the comment of the start cell in the current range.
      * @returns The comment of the start cell in the current range. If the cell does not have a comment, return `null`.
      */
     getComment(): Nullable<FThreadComment>;
+    /**
+     * Get the comments in the current range.
+     * @returns {FThreadComment[]} The comments in the current range.
+     */
+    getComments(): FThreadComment[];
     /**
      * Add a comment to the start cell in the current range.
      * @param content The content of the comment.
      * @returns Whether the comment is added successfully.
      */
-    addComment(this: FRange, content: IDocumentBody): Promise<boolean>;
+    addComment(content: IDocumentBody | FTheadCommentBuilder): Promise<boolean>;
     /**
      * Clear the comment of the start cell in the current range.
      * @returns Whether the comment is cleared successfully.
      */
     clearComment(): Promise<boolean>;
+    /**
+     * Clear all of the comments in the current range.
+     * @returns Whether the comments are cleared successfully.
+     */
+    clearComments(): Promise<boolean>;
 }
 export declare class FRangeCommentMixin extends FRange implements IFRangeCommentMixin {
     getComment(): Nullable<FThreadComment>;
-    addComment(content: IDocumentBody): Promise<boolean>;
+    getComments(): FThreadComment[];
+    addComment(content: IDocumentBody | FTheadCommentBuilder): Promise<boolean>;
     clearComment(): Promise<boolean>;
+    clearComments(): Promise<boolean>;
 }
 declare module '@univerjs/sheets/facade' {
     interface FRange extends IFRangeCommentMixin {

package/lib/types/facade/f-thread-comment.d.ts

@@ -1,7 +1,162 @@
-import { IDocumentBody, ICommandService, Injector, IUniverInstanceService } from '@univerjs/core';
+import { IDocumentBody, ICommandService, Injector, IUniverInstanceService, RichTextValue, UserManagerService } from '@univerjs/core';
 import { IBaseComment, IThreadComment } from '@univerjs/thread-comment';
-import { FRange } from '@univerjs/sheets/facade';
 import { SheetsThreadCommentModel } from '@univerjs/sheets-thread-comment';
+import { FRange } from '@univerjs/sheets/facade';
+export declare class FTheadCommentItem {
+    protected _comment: IThreadComment;
+    /**
+     * Create a new FTheadCommentItem
+     * @param {IThreadComment|undefined} comment The comment
+     * @returns {FTheadCommentItem} A new instance of FTheadCommentItem
+     * @example
+     * ```ts
+     * const comment = univerAPI.newTheadComment();
+     * ```
+     */
+    static create(comment?: IThreadComment): FTheadCommentItem;
+    constructor(comment?: IThreadComment);
+    /**
+     * Get the person id of the comment
+     * @returns {string} The person id of the comment
+     * @example
+     * ```ts
+     * const comment = univerAPI.getActiveWorkbook()
+     *  .getSheetById(sheetId)
+     *  .getCommentById(commentId);
+     * const personId = comment.personId;
+     * ```
+     */
+    get personId(): string;
+    /**
+     * Get the date time of the comment
+     * @returns {string} The date time of the comment
+     * @example
+     * ```ts
+     * const comment = univerAPI.getActiveWorkbook()
+     *  .getSheetById(sheetId)
+     *  .getCommentById(commentId);
+     * const dateTime = comment.dateTime;
+     * ```
+     */
+    get dateTime(): string;
+    /**
+     * Get the content of the comment
+     * @returns {RichTextValue} The content of the comment
+     * @example
+     * ```ts
+     * const comment = univerAPI.getActiveWorkbook()
+     *  .getSheetById(sheetId)
+     *  .getCommentById(commentId);
+     * const content = comment.content;
+     * ```
+     */
+    get content(): RichTextValue;
+    /**
+     * Get the id of the comment
+     * @returns {string} The id of the comment
+     * @example
+     * ```ts
+     * const comment = univerAPI.getActiveWorkbook()
+     *  .getSheetById(sheetId)
+     *  .getCommentById(commentId);
+     * const id = comment.id;
+     * ```
+     */
+    get id(): string;
+    /**
+     * Get the thread id of the comment
+     * @returns {string} The thread id of the comment
+     * @example
+     * ```ts
+     * const comment = univerAPI.getActiveWorkbook()
+     *  .getSheetById(sheetId)
+     *  .getCommentById(commentId);
+     * const threadId = comment.threadId;
+     * ```
+     */
+    get threadId(): string;
+    /**
+     * Copy the comment
+     * @returns {FTheadCommentBuilder} The comment builder
+     * @example
+     * ```ts
+     * const comment = univerAPI.getActiveWorkbook()
+     *  .getSheetById(sheetId)
+     *  .getCommentById(commentId);
+     * const newComment = comment.copy();
+     * ```
+     */
+    copy(): FTheadCommentBuilder;
+}
+export declare class FTheadCommentBuilder extends FTheadCommentItem {
+    static create(comment?: IThreadComment): FTheadCommentBuilder;
+    /**
+     * Set the content of the comment
+     * @param {IDocumentBody | RichTextValue} content The content of the comment
+     * @returns {FTheadCommentBuilder} The comment builder
+     * @example
+     * ```ts
+     * const comment = univerAPI.newTheadComment()
+     *  .setContent(univerAPI.newRichText().insertText('hello zhangsan'));
+     * ```
+     */
+    setContent(content: IDocumentBody | RichTextValue): FTheadCommentBuilder;
+    /**
+     * Set the person id of the comment
+     * @param {string} userId The person id of the comment
+     * @returns {FTheadCommentBuilder} The comment builder
+     * @example
+     * ```ts
+     * const comment = univerAPI.newTheadComment()
+     *  .setPersonId('123');
+     * ```
+     */
+    setPersonId(userId: string): FTheadCommentBuilder;
+    /**
+     * Set the date time of the comment
+     * @param {Date} date The date time of the comment
+     * @returns {FTheadCommentBuilder} The comment builder
+     * @example
+     * ```ts
+     * const comment = univerAPI.newTheadComment()
+     *  .setDateTime(new Date());
+     * ```
+     */
+    setDateTime(date: Date): FTheadCommentBuilder;
+    /**
+     * Set the id of the comment
+     * @param {string} id The id of the comment
+     * @returns {FTheadCommentBuilder} The comment builder
+     * @example
+     * ```ts
+     * const comment = univerAPI.newTheadComment()
+     *  .setId('123');
+     * ```
+     */
+    setId(id: string): FTheadCommentBuilder;
+    /**
+     * Set the thread id of the comment
+     * @param {string} threadId The thread id of the comment
+     * @returns {FTheadCommentBuilder} The comment builder
+     * @example
+     * ```ts
+     * const comment = univerAPI.newTheadComment()
+     *  .setThreadId('123');
+     * ```
+     */
+    setThreadId(threadId: string): FTheadCommentBuilder;
+    /**
+     * Build the comment
+     * @returns {IThreadComment} The comment
+     * @example
+     * ```ts
+     * const comment = univerAPI.newTheadComment()
+     *  .setContent(univerAPI.newRichText().insertText('hello zhangsan'))
+     *  .build();
+     * ```
+     */
+    build(): IThreadComment;
+}
 export declare class FThreadComment {
     private readonly _thread;
     private readonly _parent;
@@ -9,48 +164,140 @@ export declare class FThreadComment {
     private readonly _commandService;
     private readonly _univerInstanceService;
     private readonly _threadCommentModel;
-    constructor(_thread: IThreadComment | IBaseComment, _parent: IThreadComment | undefined, _injector: Injector, _commandService: ICommandService, _univerInstanceService: IUniverInstanceService, _threadCommentModel: SheetsThreadCommentModel);
+    private readonly _userManagerService;
+    constructor(_thread: IThreadComment | IBaseComment, _parent: IThreadComment | undefined, _injector: Injector, _commandService: ICommandService, _univerInstanceService: IUniverInstanceService, _threadCommentModel: SheetsThreadCommentModel, _userManagerService: UserManagerService);
     private _getRef;
     /**
      * Whether the comment is a root comment
      * @returns Whether the comment is a root comment
+     * @example
+     * ```ts
+     * const comment = univerAPI.getActiveWorkbook()
+     *  .getSheetById(sheetId)
+     *  .getCommentById(commentId);
+     * const isRoot = comment.getIsRoot();
+     * ```
      */
     getIsRoot(): boolean;
     /**
      * Get the comment data
      * @returns The comment data
+     * @example
+     * ```ts
+     * const comment = univerAPI.getActiveWorkbook()
+     *  .getSheetById(sheetId)
+     *  .getCommentById(commentId);
+     * const commentData = comment.getCommentData();
+     * ```
      */
     getCommentData(): IBaseComment;
     /**
      * Get the replies of the comment
      * @returns the replies of the comment
+     * @example
+     * ```ts
+     * const comment = univerAPI.getActiveWorkbook()
+     *  .getSheetById(sheetId)
+     *  .getCommentById(commentId);
+     * const replies = comment.getReplies();
+     * ```
      */
     getReplies(): FThreadComment[] | undefined;
     /**
      * Get the range of the comment
      * @returns The range of the comment
+     * @example
+     * ```ts
+     * const comment = univerAPI.getActiveWorkbook()
+     *  .getSheetById(sheetId)
+     *  .getCommentById(commentId);
+     * const range = comment.getRange();
+     * ```
      */
     getRange(): FRange | null;
     /**
-     * Get the content of the comment
-     * @returns The content of the comment
+     * @deprecated use `getRichText` as instead
      */
     getContent(): IDocumentBody;
+    /**
+     * Get the rich text of the comment
+     * @returns {RichTextValue} The rich text of the comment
+     * @example
+     * ```ts
+     * const comment = univerAPI.getActiveWorkbook()
+     *  .getSheetById(sheetId)
+     *  .getCommentById(commentId);
+     * const richText = comment.getRichText();
+     * ```
+     */
+    getRichText(): RichTextValue;
     /**
      * Delete the comment and it's replies
-     * @returns success or not
+     * @returns {Promise<boolean>} success or not
+     * @example
+     * ```ts
+     * const comment = univerAPI.getActiveWorkbook()
+     *  .getSheetById(sheetId)
+     *  .getCommentById(commentId);
+     * const success = await comment.deleteAsync();
+     * ```
+     */
+    deleteAsync(): Promise<boolean>;
+    /**
+     * @deprecated use `deleteAsync` as instead.
      */
     delete(): Promise<boolean>;
+    /**
+     * @param content
+     * @deprecated use `updateAsync` as instead
+     */
+    update(content: IDocumentBody): Promise<boolean>;
     /**
      * Update the comment content
      * @param content The new content of the comment
      * @returns success or not
+     * @example
+     * ```ts
+     * const comment = univerAPI.getActiveWorkbook()
+     *  .getSheetById(sheetId)
+     *  .getCommentById(commentId);
+     * const success = await comment.updateAsync(univerAPI.newRichText().insertText('hello zhangsan'));
+     * ```
      */
-    update(content: IDocumentBody): Promise<boolean>;
+    updateAsync(content: IDocumentBody | RichTextValue): Promise<boolean>;
+    /**
+     * @param resolved
+     * @deprecated use `resolveAsync` as instead
+     */
+    resolve(resolved?: boolean): Promise<boolean>;
     /**
      * Resolve the comment
      * @param resolved Whether the comment is resolved
      * @returns success or not
+     * @example
+     * ```ts
+     * const comment = univerAPI.getActiveWorkbook()
+     *  .getSheetById(sheetId)
+     *  .getCommentById(commentId);
+     * const success = await comment.resolveAsync(true);
+     * ```
      */
-    resolve(resolved?: boolean): Promise<boolean>;
+    resolveAsync(resolved?: boolean): Promise<boolean>;
+    /**
+     * Reply to the comment
+     * @param comment The comment to reply to
+     * @returns success or not
+     * @example
+     * ```ts
+     * const comment = univerAPI.getActiveWorkbook()
+     *  .getSheetById(sheetId)
+     *  .getCommentById(commentId);
+     *
+     * const reply = univerAPI.newTheadComment()
+     *  .setContent(univerAPI.newRichText().insertText('hello zhangsan'));
+     *
+     * const success = await comment.replyAsync(reply);
+     * ```
+     */
+    replyAsync(comment: FTheadCommentBuilder): Promise<boolean>;
 }

package/lib/types/facade/f-univer.d.ts

@@ -0,0 +1,41 @@
+import { IDisposable, Injector, FUniver } from '@univerjs/core';
+import { IThreadComment } from '@univerjs/thread-comment';
+import { ISheetCommentAddEvent, ISheetCommentDeleteEvent, ISheetCommentResolveEvent, ISheetCommentUpdateEvent } from './f-event';
+import { FTheadCommentBuilder } from './f-thread-comment';
+export interface IFUniverCommentMixin {
+    /**
+     * @deprecated use `univerAPI.addEvent(univerAPI.event.CommentAdded, () => {})` as instead
+     */
+    onCommentAdded(callback: (event: ISheetCommentAddEvent) => void): IDisposable;
+    /**
+     * @deprecated use `univerAPI.addEvent(univerAPI.event.CommentUpdated, () => {})` as instead
+     */
+    onCommentUpdated(callback: (event: ISheetCommentUpdateEvent) => void): IDisposable;
+    /**
+     * @deprecated use `univerAPI.addEvent(univerAPI.event.CommentDeleted, () => {})` as instead
+     */
+    onCommentDeleted(callback: (event: ISheetCommentDeleteEvent) => void): IDisposable;
+    /**
+     * @deprecated use `univerAPI.addEvent(univerAPI.event.CommentResolved, () => {})` as instead
+     */
+    onCommentResolved(callback: (event: ISheetCommentResolveEvent) => void): IDisposable;
+    /**
+     * create a new thread comment
+     * @return {FTheadCommentBuilder} thead comment builder
+     * @example
+     * ```ts
+     * const comment = univerAPI.newTheadComment().setContent(univerAPI.newRichText().insertText('hello zhangsan'));
+     * ```
+     */
+    newTheadComment(): FTheadCommentBuilder;
+}
+export declare class FUniverCommentMixin extends FUniver implements IFUniverCommentMixin {
+    private _handleCommentCommand;
+    private _handleBeforeCommentCommand;
+    _initialize(injector: Injector): void;
+    newTheadComment(comment?: IThreadComment): FTheadCommentBuilder;
+}
+declare module '@univerjs/core' {
+    interface FUniver extends IFUniverCommentMixin {
+    }
+}