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.

Playground

Live preview

Preset Mode

Installation

npm install @univerjs/preset-sheets-note

Usage

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

npm install @univerjs/sheets-note @univerjs/sheets-note-ui

Usage

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.

import '@univerjs/sheets-note/facade'

Get Annotations

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

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.

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.

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.

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 C1
const fRange = fWorksheet.getRange('C1')
fRange.deleteNote()

Event Listeners

Complete event type definitions can be found in the Events.

Event Name	Description
`SheetNoteAdd`	Triggered after adding an annotation
`SheetNoteDelete`	Triggered after deleting an annotation
`SheetNoteUpdate`	Triggered after updating an annotation
`SheetNoteShow`	Triggered when an annotation is shown
`SheetNoteHide`	Triggered when an annotation is hidden
`BeforeSheetNoteAdd`	Triggered before adding an annotation
`BeforeSheetNoteDelete`	Triggered before deleting an annotation
`BeforeSheetNoteUpdate`	Triggered before updating an annotation
`BeforeSheetNoteShow`	Triggered before showing an annotation
`BeforeSheetNoteHide`	Triggered before hiding an annotation

Event Listener Examples

// Triggered after adding an annotation
const disposable = univerAPI.addEvent(univerAPI.Event.SheetNoteAdd, (params) => {
  const { workbook, worksheet, row, col, note } = params
})

// Remove event listener using `disposable.dispose()`

// Triggered before removing an annotation, can be canceled
const 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()`

Table of Contents