Skip to Content
🎉 Univer 0.6.0 is released.Read more →
GuidesUniver SheetsFeaturesThread Comment

Thread Comment 0.2.10+

Facade APIHas Paid PlanUniver ServerUniver on Node.jsPreset
✅-Optional-UniverSheetsThreadCommentPreset

The Comment plugin provides the ability to comment or annotate cells.

This feature includes the following plugin packages:

Presets Installation

import { createUniver, defaultTheme, LocaleType, merge } from '@univerjs/presets';
import { UniverSheetsCorePreset } from '@univerjs/presets/preset-sheets-core';
import UniverPresetSheetsCoreEnUS from '@univerjs/presets/preset-sheets-core/locales/en-US';
import { UniverSheetsThreadCommentPreset } from '@univerjs/presets/preset-sheets-thread-comment';
import UniverPresetSheetsThreadCommentEnUS from '@univerjs/presets/preset-sheets-thread-comment/locales/en-US';
 
import '@univerjs/presets/lib/styles/preset-sheets-thread-comment.css'
 
const { univerAPI } = createUniver({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: merge(
      {},
      UniverPresetSheetsCoreEnUS,
      UniverPresetSheetsThreadCommentEnUS 
    ),
  },
  theme: defaultTheme,
  collaboration: true,
  presets: [
    UniverSheetsCorePreset(),
    UniverSheetsThreadCommentPreset({ collaboration: true }),
  ],
});

If you are using Univer’s collaboration feature and want the collaboration feature to manage comment information, you need to provide configuration:

- UniverSheetsThreadCommentPreset(),
+ UniverSheetsThreadCommentPreset({ collaboration: true }),

Piecemeal Installation

npm install @univerjs/sheets-thread-comment @univerjs/sheets-thread-comment-ui @univerjs/thread-comment @univerjs/thread-comment-ui
import { LocaleType, merge, Univer } from '@univerjs/core';
import { defaultTheme } from "@univerjs/design";
import { UniverThreadCommentPlugin } from '@univerjs/thread-comment';
import { UniverThreadCommentUIPlugin } from '@univerjs/thread-comment-ui';
import { UniverSheetsThreadCommentPlugin } from '@univerjs/sheets-thread-comment';
import { UniverSheetsThreadCommentUIPlugin } from '@univerjs/sheets-thread-comment-ui';
import ThreadCommentUIEnUS from '@univerjs/thread-comment-ui/locale/en-US';
import SheetsThreadCommentUIEnUS from '@univerjs/sheets-thread-comment-ui/locale/en-US';
 
import '@univerjs/thread-comment-ui/lib/index.css';
 
import '@univerjs/sheets-thread-comment/facade';
 
const univer = new Univer({
  theme: defaultTheme,
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: merge(
      ThreadCommentUIEnUS,
      SheetsThreadCommentUIEnUS
    ),
  },
});
 
univer.registerPlugin(UniverThreadCommentPlugin);
univer.registerPlugin(UniverThreadCommentUIPlugin);
univer.registerPlugin(UniverSheetsThreadCommentPlugin);
univer.registerPlugin(UniverSheetsThreadCommentUIPlugin);

If you use the collaboration plugin at the same time, you need to do the following:

npm install @univerjs-pro/thread-comment-datasource
import { UniverThreadCommentDataSourcePlugin } from '@univerjs-pro/thread-comment-datasource';
 
univer.registerPlugin(UniverThreadCommentDataSourcePlugin);

Facade API

To get full definition of facade api, please refer to FacadeAPI 

Add / Clear cell comment

Add / Clear the comment to the start cell in the current range.

const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
 
// comment only attch to single cell, if range is A1:J10 equal A1
const range = worksheet.getRange(0, 0, 1, 1);
 
// add comment to empty cell
await range.addComment({
  dataStream: 'hello world\r\n',
});
 
// reply to current comment
await range.addComment({
  dataStream: 'reply\r\n',
});
 
// clear comment
await range.clearComment();

Get cell comment

Get the comment of the start cell in the current range and return an FThreadComment object, or null if there is no comment.

const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
 
// comment only attch to single cell, if range is A1:J10 equal A1
const range = worksheet.getRange(0, 0, 1, 1);
 
// get comment
const comment = range.getComment();
console.log(comment);

Create comment

Use univerAPI.newTheadComment() to create a new comment builder.

const comment = univerAPI.newTheadComment()
  .setContent(univerAPI.newRichText().insertText('hello world'))
  .build();

Update / Delete / Resolve comment

// update content
await comment?.updateAsync(univerAPI.newRichText().insertText('hello world222'));
 
// delete comment
await comment?.deleteAsync();
 
// resolve comment
await comment?.resolveAsync(true);

Get comment replies list

Returns an array of FThreadComment objects.

// get replies
const replies = comment?.getReplies();
console.log(replies);
 
// get range of this comment
console.log(comment?.getRange());
 
// reply to comment
const reply = univerAPI.newTheadComment()
  .setContent(univerAPI.newRichText().insertText('hello world'));
await comment?.replyAsync(reply);

Get comment content

// get rich text content
const richText = comment?.getRichText();

Events

The comment module provides a series of events for monitoring comment additions, updates, deletions, and resolution status changes. All events can be listened to using univerAPI.addEvent().

Comment Add Events

  • univerAPI.Event.SheetThreadCommentAdd: Triggered after a comment is added
  • univerAPI.Event.BeforeSheetThreadCommentAdd: Triggered before a comment is added
// Listen for before comment add event
univerAPI.addEvent(univerAPI.Event.BeforeSheetThreadCommentAdd, (event) => {
    const { comment, workbook, worksheet, row, col } = event;
    console.log('About to add comment:', { row, col, comment });
    // Return false to prevent comment addition
    return true;
});
 
// Listen for comment added event
univerAPI.addEvent(univerAPI.Event.SheetThreadCommentAdd, (event) => {
    const { comment, workbook, worksheet, row, col } = event;
    console.log('Comment added:', { row, col, comment });
});

Comment Update Events

  • univerAPI.Event.SheetThreadCommentUpdate: Triggered after a comment is updated
  • univerAPI.Event.BeforeSheetThreadCommentUpdate: Triggered before a comment is updated
// Listen for before comment update event
univerAPI.addEvent(univerAPI.Event.BeforeSheetThreadCommentUpdate, (event) => {
    const { comment, workbook, worksheet, row, col, newContent } = event;
    console.log('About to update comment:', { row, col, comment, newContent });
    // Return false to prevent comment update
    return true;
});
 
// Listen for comment updated event
univerAPI.addEvent(univerAPI.Event.SheetThreadCommentUpdate, (event) => {
    const { comment, workbook, worksheet, row, col } = event;
    console.log('Comment updated:', { row, col, comment });
});

Comment Deletion Events

  • univerAPI.Event.SheetThreadCommentDelete: Triggered after a comment is deleted
  • univerAPI.Event.BeforeSheetThreadCommentDelete: Triggered before a comment is deleted
// Listen for before comment delete event
univerAPI.addEvent(univerAPI.Event.BeforeSheetThreadCommentDelete, (event) => {
    const { comment, workbook, worksheet, row, col } = event;
    console.log('About to delete comment:', { row, col, comment });
    // Return false to prevent comment deletion
    return true;
});
 
// Listen for comment deleted event
univerAPI.addEvent(univerAPI.Event.SheetThreadCommentDelete, (event) => {
    const { commentId, workbook, worksheet } = event;
    console.log('Comment deleted:', commentId);
});

Comment Resolution Events

  • univerAPI.Event.SheetThreadCommentResolve: Triggered after a comment’s resolution status changes
  • univerAPI.Event.BeforeSheetThreadCommentResolve: Triggered before a comment’s resolution status changes
// Listen for before comment resolve event
univerAPI.addEvent(univerAPI.Event.BeforeSheetThreadCommentResolve, (event) => {
    const { comment, workbook, worksheet, row, col, resolved } = event;
    console.log('About to change comment resolution status:', { row, col, resolved });
    // Return false to prevent status change
    return true;
});
 
// Listen for comment resolved event
univerAPI.addEvent(univerAPI.Event.SheetThreadCommentResolve, (event) => {
    const { comment, workbook, worksheet, row, col, resolved } = event;
    console.log('Comment resolution status changed:', { row, col, resolved });
});

Each event includes the following common parameters:

  • workbook: Current workbook instance
  • worksheet: Current worksheet instance
  • row: Row index of the comment
  • col: Column index of the comment
  • comment: Comment object (deletion event only includes commentId)

Special parameters:

  • BeforeSheetThreadCommentUpdate event includes newContent: New comment content (RichTextValue type)
  • SheetThreadCommentResolve and BeforeSheetThreadCommentResolve events include resolved: Comment resolution status

All event callbacks with the Before prefix can return false to prevent the corresponding operation.

Was this page helpful?
Last updated on
ChartsProFind & Replace