Skip to content
Agent Sheet SDK

Comments

A comment is an array stored in the cell’s c property. Each entry has a (author) and either t (plain text) or R (rich-text runs). Extra properties go on the array itself:

Property Meaning
hidden true shows the comment only on hover
["!pos"] position and size (see below)
s style; only { fgColor } (the note’s fill) is used

utils.cell_add_comment(cell, text, author) appends a plain comment.

const XLSX = require("@agent-sheet/wasm");
const ws = XLSX.utils.aoa_to_sheet([["a"], ["b"]]);
XLSX.utils.cell_add_comment(ws.A2, "simple note", "Me");
const comment = [{ a: "Me", R: [{ t: "s", v: "plain " }, { t: "s", v: "bold", s: { bold: true } }] }];
comment.hidden = true;
comment.s = { fgColor: { rgb: "FFFF00" } };
ws.A1.c = comment;
const wb = XLSX.utils.book_new();
XLSX.utils.book_append_sheet(wb, ws, "S");
const back = XLSX.read(XLSX.write(wb, { type: "buffer", bookType: "xlsx", cellStyles: true }), { cellStyles: true });
console.log(back.Sheets.S.A1.c[0].t, back.Sheets.S.A1.c.hidden, back.Sheets.S.A2.c[0].a);
Output
plain bold true Me

Comment position

Section titled “Comment position”

!pos has three shapes:

  • Absolute: { x, y, w, h }. The pixel offset of the upper-left corner and the size.
  • Anchored to a cell: { r, c, x, y, w, h }. r and c are the zero-based row and column of the anchor. x and y are pixel offsets inside it. To put a note to the right of cell (r, c), use { r, c: c + 1, x: 0, y: 0, w: 456, h: 123 }.
  • Two corners: { r, c, x, y, R, C, X, Y }. The upper-left cell and offset, and the lower-right cell and offset.

All three shapes are written to the file. When read back, !pos can retain a cell anchor or two-corner form, with missing offsets filled as zero. Pixel dimensions may be adjusted by the file’s coordinate units. The example below returns the two-corner form, including zero offsets.

const XLSX = require("@agent-sheet/wasm");
const ws = XLSX.utils.aoa_to_sheet([["a"]]);
const c = [{ a: "Ann", t: "hello" }];
c["!pos"] = { c: 3, r: 4, C: 3, R: 4, X: 200, Y: 100 };
ws.A1.c = c;
const wb = XLSX.utils.book_new();
XLSX.utils.book_append_sheet(wb, ws, "S");
const back = XLSX.read(XLSX.write(wb, { type: "buffer", bookType: "xlsx" }), { cellStyles: true });
console.log(JSON.stringify(back.Sheets.S.A1.c["!pos"]));
Output
{"c":3,"x":0,"r":4,"y":0,"C":3,"X":200,"R":4,"Y":100}