Web SDK

Annotations

Annotations functionality allows users to add comments in spreadsheet cells to record additional information or provide context. It supports various comment styles and operations, helping users better understand and collaborate on data.

Preview

Preset Mode

Installation

Shell
pnpm add @univerjs/preset-sheets-note

Usage

TypeScript
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'import UniverPresetSheetsCoreEnUS from '@univerjs/preset-sheets-core/locales/en-US'import { UniverSheetsNotePreset } from '@univerjs/preset-sheets-note'import UniverPresetSheetsNoteEnUS from '@univerjs/preset-sheets-note/locales/en-US'import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'import '@univerjs/preset-sheets-core/lib/index.css'import '@univerjs/preset-sheets-note/lib/index.css'const { univerAPI } = createUniver({  locale: LocaleType.EN_US,  locales: {    [LocaleType.EN_US]: mergeLocales(      UniverPresetSheetsCoreEnUS,      UniverPresetSheetsNoteEnUS,     ),  },  presets: [    UniverSheetsCorePreset(),    UniverSheetsNotePreset(),   ],})

Plugin Mode

Installation

Shell
pnpm add @univerjs/sheets-note @univerjs/sheets-note-ui

Usage

TypeScript
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'import { UniverSheetsNotePlugin } from '@univerjs/sheets-note'import { UniverSheetsNoteUIPlugin } from '@univerjs/sheets-note-ui'import SheetsNoteUIEnUS from '@univerjs/sheets-note-ui/locale/en-US'import '@univerjs/sheets-note-ui/lib/index.css'import '@univerjs/sheets-note/facade'const univer = new Univer({  locale: LocaleType.EN_US,  locales: {    [LocaleType.EN_US]: mergeLocales(      SheetsNoteUIEnUS,     ),  },})univer.registerPlugin(UniverSheetsNotePlugin)univer.registerPlugin(UniverSheetsNoteUIPlugin)

Facade API

Complete Facade API type definitions can be found in the FacadeAPI.

Importing

Plugin mode note

Only plugin mode requires manually importing the Facade package. Preset mode already includes the corresponding Facade package, so no extra import is needed.

TypeScript
import '@univerjs/sheets-note/facade'

Get Annotations

Using FWorksheet.getNotes to get all annotations in the worksheet.

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const notes = fWorksheet.getNotes()notes.forEach((item) => {  const { row, col, note } = item  console.log(`Cell ${fWorksheet.getRange(row, col).getA1Notation()} has note: ${note}`)})

Using FRange.getNote to get the annotation of the top-left cell in the range.

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const fRange = fWorksheet.getRange('A1:D10')const note = fRange.getNote()

Add or Update Annotations

Using FRange.createOrUpdateNote to create or update the annotation of the top-left cell in the range.

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const fRange = fWorksheet.getRange('A1')fRange.createOrUpdateNote({  note: 'This is an annotation',  width: 160,  height: 100,  show: true,})

Remove Annotations

Using FRange.deleteNote to remove the annotation of the top-left cell in the range.

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const notes = fWorksheet.getNotes()if (notes.length > 0) {  // Remove the first annotation in the worksheet  const { row, col } = notes[0]  fWorksheet.getRange(row, col).deleteNote()}// Remove the annotation in cell C1const fRange = fWorksheet.getRange('C1')fRange.deleteNote()

Event Listeners

Complete event type definitions can be found in the Events.

Event NameDescription
SheetNoteAddTriggered after adding an annotation
SheetNoteDeleteTriggered after deleting an annotation
SheetNoteUpdateTriggered after updating an annotation
SheetNoteShowTriggered when an annotation is shown
SheetNoteHideTriggered when an annotation is hidden
BeforeSheetNoteAddTriggered before adding an annotation
BeforeSheetNoteDeleteTriggered before deleting an annotation
BeforeSheetNoteUpdateTriggered before updating an annotation
BeforeSheetNoteShowTriggered before showing an annotation
BeforeSheetNoteHideTriggered before hiding an annotation
Event Listener Examples
TypeScript
// Triggered after adding an annotationconst disposable = univerAPI.addEvent(univerAPI.Event.SheetNoteAdd, (params) => {  const { workbook, worksheet, row, col, note } = params})// Remove event listener using `disposable.dispose()`
TypeScript
// Triggered before removing an annotation, can be canceledconst disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetNoteDelete, (params) => {  const { workbook, worksheet, row, col, oldNote } = params  // Cancel the annotation deletion operation  params.cancel = true})// Remove event listener using `disposable.dispose()`

How is this guide?

© 2026 DreamNum Co., Ltd.