Excel.CommentCollection class
Represents a collection of comment objects that are part of the workbook.
- Extends
Remarks
Properties
| context | The request context associated with the object. This connects the add-in's process to the Office host application's process. |
| items | Gets the loaded child items in this collection. |
Methods
| add(cell |
Creates a new comment with the given content on the given cell. An |
| add(cell |
Creates a new comment with the given content on the given cell. An |
| get |
Gets the number of comments in the collection. |
| get |
Gets a comment from the collection based on its ID. |
| get |
Gets a comment from the collection based on its position. |
| get |
Gets the comment from the specified cell. If there is no comment in the cell, an error is thrown. |
| get |
Gets the comment to which the given reply is connected. |
| get |
Gets a comment from the collection based on its ID. If the comment object does not exist, then this method returns an object with its |
| load(options) | Queues up a command to load the specified properties of the object. You must call |
| load(property |
Queues up a command to load the specified properties of the object. You must call |
| load(property |
Queues up a command to load the specified properties of the object. You must call |
| toJSON() | Overrides the JavaScript |
Events
| on |
Occurs when the comments are added. |
| on |
Occurs when comments or replies in a comment collection are changed, including when replies are deleted. |
| on |
Occurs when comments are deleted in the comment collection. |
Property Details
context
The request context associated with the object. This connects the add-in's process to the Office host application's process.
context: RequestContext;Property Value
items
Gets the loaded child items in this collection.
readonly items: Excel.Comment[];Property Value
Method Details
add(cellAddress, content, contentType)
Creates a new comment with the given content on the given cell. An InvalidArgument error is thrown if the provided range is larger than one cell.
add(cellAddress: Range | string, content: CommentRichContent | string, contentType?: Excel.ContentType): Excel.Comment;Parameters
- cellAddress
-
Excel.Range | string
The cell to which the comment is added. This can be a Range object or a string. If it's a string, it must contain the full address, including the sheet name. An InvalidArgument error is thrown if the provided range is larger than one cell.
- content
-
Excel.CommentRichContent | string
The comment's content. This can be either a string or CommentRichContent object. Strings are used for plain text. CommentRichContent objects allow for other comment features, such as mentions. [Api set: ExcelApi 1.10 for string, 1.11 for CommentRichContent object]
- contentType
- Excel.ContentType
Optional. The type of content contained within the comment. The default value is enum ContentType.Plain. [Api set: ExcelApi 1.10 for Enum ContentType.Plain, 1.11 for Enum ContentType.Mention]
Returns
Remarks
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/12-comment/comment-basics.yaml
await Excel.run(async (context) => {
const sheet = context.workbook.worksheets.getItem("Comments");
// Note that an InvalidArgument error will be thrown if multiple cells passed to `comment.add`.
sheet.comments.add("A2", "TODO: add data.");
await context.sync();
});
add(cellAddress, content, contentTypeString)
Creates a new comment with the given content on the given cell. An InvalidArgument error is thrown if the provided range is larger than one cell.
add(cellAddress: Range | string, content: CommentRichContent | string, contentTypeString?: "Plain" | "Mention"): Excel.Comment;Parameters
- cellAddress
-
Excel.Range | string
The cell to which the comment is added. This can be a Range object or a string. If it's a string, it must contain the full address, including the sheet name. An InvalidArgument error is thrown if the provided range is larger than one cell.
- content
-
Excel.CommentRichContent | string
The comment's content. This can be either a string or CommentRichContent object. Strings are used for plain text. CommentRichContent objects allow for other comment features, such as mentions. [Api set: ExcelApi 1.10 for string, 1.11 for CommentRichContent object]
- contentTypeString
-
"Plain" | "Mention"
Optional. The type of content contained within the comment. The default value is enum ContentType.Plain. [Api set: ExcelApi 1.10 for Enum ContentType.Plain, 1.11 for Enum ContentType.Mention]
Returns
Remarks
getCount()
Gets the number of comments in the collection.
getCount(): OfficeExtension.ClientResult<number>;Returns
OfficeExtension.ClientResult<number>
Remarks
getItem(commentId)
Gets a comment from the collection based on its ID.
getItem(commentId: string): Excel.Comment;Parameters
- commentId
-
string
The identifier for the comment.
Returns
Remarks
getItemAt(index)
Gets a comment from the collection based on its position.
getItemAt(index: number): Excel.Comment;Parameters
- index
-
number
Index value of the object to be retrieved. Zero-indexed.
Returns
Remarks
getItemByCell(cellAddress)
Gets the comment from the specified cell. If there is no comment in the cell, an error is thrown.
getItemByCell(cellAddress: Range | string): Excel.Comment;Parameters
- cellAddress
-
Excel.Range | string
The cell which the comment is on. This can be a Range object or a string. If it's a string, it must contain the full address, including the sheet name. An InvalidArgument error is thrown if the provided range is larger than one cell.
Returns
Remarks
getItemByReplyId(replyId)
Gets the comment to which the given reply is connected.
getItemByReplyId(replyId: string): Excel.Comment;Parameters
- replyId
-
string
The identifier of comment reply.
Returns
Remarks
getItemOrNullObject(commentId)
Gets a comment from the collection based on its ID. If the comment object does not exist, then this method returns an object with its isNullObject property set to true. For further information, see *OrNullObject methods and properties.
getItemOrNullObject(commentId: string): Excel.Comment;Parameters
- commentId
-
string
The identifier for the comment.
Returns
Remarks
load(options)
Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.
load(options?: Excel.Interfaces.CommentCollectionLoadOptions & Excel.Interfaces.CollectionLoadOptions): Excel.CommentCollection;Parameters
Provides options for which properties of the object to load.
Returns
load(propertyNames)
Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.
load(propertyNames?: string | string[]): Excel.CommentCollection;Parameters
- propertyNames
-
string | string[]
A comma-delimited string or an array of strings that specify the properties to load.
Returns
load(propertyNamesAndPaths)
Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.
load(propertyNamesAndPaths?: OfficeExtension.LoadOption): Excel.CommentCollection;Parameters
- propertyNamesAndPaths
- OfficeExtension.LoadOption
propertyNamesAndPaths.select is a comma-delimited string that specifies the properties to load, and propertyNamesAndPaths.expand is a comma-delimited string that specifies the navigation properties to load.
Returns
toJSON()
Overrides the JavaScript toJSON() method in order to provide more useful output when an API object is passed to JSON.stringify(). (JSON.stringify, in turn, calls the toJSON method of the object that is passed to it.) Whereas the original Excel.CommentCollection object is an API object, the toJSON method returns a plain JavaScript object (typed as Excel.Interfaces.CommentCollectionData) that contains an "items" array with shallow copies of any loaded properties from the collection's items.
toJSON(): Excel.Interfaces.CommentCollectionData;Returns
Event Details
onAdded
Occurs when the comments are added.
readonly onAdded: OfficeExtension.EventHandlers<Excel.CommentAddedEventArgs>;Event Type
Remarks
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-comment-event-handler.yaml
await Excel.run(async (context) => {
const comments = context.workbook.worksheets.getActiveWorksheet().comments;
// Register the onAdded, onChanged, and onDeleted comment event handlers.
comments.onAdded.add(commentAdded);
comments.onChanged.add(commentChanged);
comments.onDeleted.add(commentDeleted);
await context.sync();
console.log("Added event handlers for when comments are added, changed, or deleted.");
});
...
async function commentAdded(event: Excel.CommentAddedEventArgs) {
// Retrieve the added comment using the comment ID.
// Note: This function assumes only a single comment is added at a time.
await Excel.run(async (context) => {
const addedComment = context.workbook.comments.getItem(event.commentDetails[0].commentId);
// Load the added comment's data.
addedComment.load(["content", "authorName", "creationDate"]);
await context.sync();
// Print out the added comment's data.
console.log(`A comment was added:`);
console.log(` ID: ${event.commentDetails[0].commentId}`);
console.log(` Comment content:${addedComment.content}`);
console.log(` Comment author:${addedComment.authorName}`);
console.log(` Creation date:${addedComment.creationDate}`);
});
}
onChanged
Occurs when comments or replies in a comment collection are changed, including when replies are deleted.
readonly onChanged: OfficeExtension.EventHandlers<Excel.CommentChangedEventArgs>;Event Type
Remarks
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-comment-event-handler.yaml
await Excel.run(async (context) => {
const comments = context.workbook.worksheets.getActiveWorksheet().comments;
// Register the onAdded, onChanged, and onDeleted comment event handlers.
comments.onAdded.add(commentAdded);
comments.onChanged.add(commentChanged);
comments.onDeleted.add(commentDeleted);
await context.sync();
console.log("Added event handlers for when comments are added, changed, or deleted.");
});
...
async function commentChanged(event: Excel.CommentChangedEventArgs) {
// Retrieve the changed comment using the comment ID.
// Note: This function assumes only a single comment is changed at a time.
await Excel.run(async (context) => {
const changedComment = context.workbook.comments.getItem(event.commentDetails[0].commentId);
// Load the changed comment's data.
changedComment.load(["content", "authorName", "creationDate"]);
await context.sync();
// Print out the changed comment's data.
console.log(`A comment was changed:`);
console.log(` ID: ${event.commentDetails[0].commentId}`);
console.log(` Updated comment content: ${changedComment.content}`);
console.log(` Comment author: ${changedComment.authorName}`);
console.log(` Creation date: ${changedComment.creationDate}`);
});
}
onDeleted
Occurs when comments are deleted in the comment collection.
readonly onDeleted: OfficeExtension.EventHandlers<Excel.CommentDeletedEventArgs>;Event Type
Remarks
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-comment-event-handler.yaml
await Excel.run(async (context) => {
const comments = context.workbook.worksheets.getActiveWorksheet().comments;
// Register the onAdded, onChanged, and onDeleted comment event handlers.
comments.onAdded.add(commentAdded);
comments.onChanged.add(commentChanged);
comments.onDeleted.add(commentDeleted);
await context.sync();
console.log("Added event handlers for when comments are added, changed, or deleted.");
});
...
async function commentDeleted(event: Excel.CommentDeletedEventArgs) {
// Print out the deleted comment's ID.
// Note: This function assumes only a single comment is deleted at a time.
await Excel.run(async (context) => {
console.log(`A comment was deleted:`);
console.log(` ID: ${event.commentDetails[0].commentId}`);
});
}
Office Add-ins