NotesManager

Manages cell notes (the legacy “comments” feature in older Excel versions, still present alongside threaded comments in the JSF / OOXML formats) on a workbook’s sheets. Access via workbook.notes.

Notes are stored on individual cells; a sheet may have at most one note per cell. get* methods return defensive copies, so mutating the result does not affect the workbook’s stored state --- changes must go through update / delete to take effect.

Methods

add()

add(sheetName, note): Note;

Add a new note to a cell on the given sheet.

Parameters

sheetName

string

note

Note

Returns

Note

the created Note (defensive copy)

Throws

if the sheet does not exist

Throws

if ref is not a valid cell reference

Throws

if text is empty

Throws

if author is empty

Throws

if a note already exists on the target cell

---

delete()

delete(sheetName, ref): void;

Delete a note from the given sheet.

Parameters

sheetName

string

ref

string

Returns

void

Throws

if the sheet does not exist

Throws

if no note exists at the given ref

---

get()

get(sheetName): Note[];

Get all notes on the given sheet.

Copies are returned to prevent external mutation of the sheet’s notes.

Parameters

sheetName

string

name of the sheet

Returns

Note[]

Throws

if the sheet does not exist

---

getByCell()

getByCell(sheetName, ref): Note | undefined;

Get the note attached to a specific cell on the given sheet.

Parameters

sheetName

string

name of the sheet

ref

string

cell reference in A1 notation

Returns

Note | undefined

the note (defensive copy) or undefined if no note exists

Throws

if the sheet does not exist

---

update()

update(
   sheetName,
   ref,
   updates): void;

Update an existing note on the given sheet. Only provided fields are updated; omitted fields are left unchanged. ref itself is not changed by this API; cell moves are handled by updateAnnotationRefs.

Parameters

sheetName

string

ref

string

updates

Partial<Pick<Note, "text" | "author">>

Returns

void

Throws

if the sheet does not exist

Throws

if ref is not a valid cell reference

Throws

if no note exists at the given ref