diff --git a/docz/docs/07-csf/02-cell.md b/docz/docs/07-csf/02-cell.md index 1cf55d53..081c2c16 100644 --- a/docz/docs/07-csf/02-cell.md +++ b/docz/docs/07-csf/02-cell.md @@ -20,7 +20,7 @@ Cell objects are plain JS objects with keys and values following the convention: | `D` | if true, array formula is dynamic (if applicable) | | | **Other Cell Properties** ([More Info](./features)) | | `l` | cell hyperlink and tooltip ([More Info](./features/hyperlinks)) | -| `c` | cell comments ([More Info](./features#cell-comments)) | +| `c` | cell comments ([More Info](./features/comments)) | | `r` | rich text encoding (if applicable) | | `h` | HTML rendering of the rich text (if applicable) | | `s` | the style/theme of the cell (if applicable) | diff --git a/docz/docs/07-csf/07-features/04-comments.md b/docz/docs/07-csf/07-features/04-comments.md new file mode 100644 index 00000000..5e9a5eef --- /dev/null +++ b/docz/docs/07-csf/07-features/04-comments.md @@ -0,0 +1,160 @@ +--- +sidebar_position: 4 +--- + +# Cell Comments + +
+ Format Support (click to show) + +**Simple Notes/Comments**: XLSX/M, XLSB, BIFF8 XLS (read only), XLML, ODS (read only) + +**Threaded Comments**: XLSX/M, XLSB (read only) + +
+ +## Basic Structure + +Cell comments are objects stored in the `c` array of cell objects. + +The comment content is split into parts based on the comment author. + +The `a` field of each comment part is the author of the comment and the `t` +field is the plain text representation. + +For example, the following snippet appends a cell comment into cell `A1`: + +```js +var cell = ws["A1"]; + +/* create comment array if it does not exist */ +if(!cell.c) ws.A1.c = []; + +/* create a comment part */ +var comment_part = { + a:"SheetJS", + t:"I'm a little comment, short and stout!" +}; + +/* Add comment part to the comment array */ +cell.c.push(comment_part); +``` + +:::note XLSB Author limits + +XLSB enforces a 54 character limit on the Author name. Names longer than 54 +characters may cause issues with other formats. + +::: + +
Live Example (click to hide) + +```jsx live +function SheetJSComments1() { + return (); +} +``` + +
+ +## Visibility + +To mark a comment as normally hidden, set the `hidden` property: + +```js +if(!cell.c) cell.c = []; +// highlight-next-line +cell.c.hidden = true; +cell.c.push({a:"SheetJS", t:"This comment will be hidden"}); +``` + +
Live Example (click to hide) + +```jsx live +function SheetJSComments2() { + return (); +} + +``` + +
+ +## Threaded Comments + +Introduced in Excel 365, threaded comments are plain text comment snippets with +author metadata and parent references. They are supported in XLSX and XLSB. + +To mark a comment as threaded, each comment part must have a true `T` property: + +```js +if(!cell.c) cell.c = []; + +var part1 = { + a:"SheetJS", + t:"This is threaded", +// highlight-next-line + T: true +}; +cell.c.push(part1); + +var part2 = { + a:"JSSheet", + t:"This is also threaded", +}; +// The next line uses Object Spread syntax to add T: true +// highlight-next-line +cell.c.push({ ...part2, T: true}); +``` + +There is no Active Directory or Office 365 metadata associated with authors. + +
Live Example (click to hide) + +```jsx live +function SheetJSComments2() { + return (); +} + +``` + +
diff --git a/docz/docs/07-csf/07-features/index.md b/docz/docs/07-csf/07-features/index.md index b6a72c46..b6919daa 100644 --- a/docz/docs/07-csf/07-features/index.md +++ b/docz/docs/07-csf/07-features/index.md @@ -215,63 +215,6 @@ functions accept the `dateNF` option to override the interpretation of that specific format string. -## Cell Comments - -
- Format Support (click to show) - -**Simple Notes/Comments**: XLSX/M, XLSB, BIFF8 XLS (read only), XLML, ODS (read only) - -**Threaded Comments**: XLSX/M, XLSB (read only) - -
- -Cell comments are objects stored in the `c` array of cell objects. The actual -contents of the comment are split into blocks based on the comment author. The -`a` field of each comment object is the author of the comment and the `t` field -is the plain text representation. - -For example, the following snippet appends a cell comment into cell `A1`: - -```js -if(!ws.A1.c) ws.A1.c = []; -ws.A1.c.push({a:"SheetJS", t:"I'm a little comment, short and stout!"}); -``` - -Note: XLSB enforces a 54 character limit on the Author name. Names longer than -54 characters may cause issues with other formats. - -To mark a comment as normally hidden, set the `hidden` property: - -```js -if(!ws.A1.c) ws.A1.c = []; -ws.A1.c.push({a:"SheetJS", t:"This comment is visible"}); - -if(!ws.A2.c) ws.A2.c = []; -ws.A2.c.hidden = true; -ws.A2.c.push({a:"SheetJS", t:"This comment will be hidden"}); -``` - - -_Threaded Comments_ - -Introduced in Excel 365, threaded comments are plain text comment snippets with -author metadata and parent references. They are supported in XLSX and XLSB. - -To mark a comment as threaded, each comment part must have a true `T` property: - -```js -if(!ws.A1.c) ws.A1.c = []; -ws.A1.c.push({a:"SheetJS", t:"This is not threaded"}); - -if(!ws.A2.c) ws.A2.c = []; -ws.A2.c.hidden = true; -ws.A2.c.push({a:"SheetJS", t:"This is threaded", T: true}); -ws.A2.c.push({a:"JSSheet", t:"This is also threaded", T: true}); -``` - -There is no Active Directory or Office 365 metadata associated with authors in a thread. - ## Sheet Visibility