Trabalhar com comentários usando a API JavaScript do Excel
Este artigo descreve como adicionar, ler, modificar e remover comentários em uma pasta de trabalho com a API JavaScript do Excel. Você pode saber mais sobre o recurso de comentário no artigo Inserir comentários e anotações no Excel .
Na API JavaScript do Excel, um comentário inclui o comentário inicial único e a discussão em thread conectada. Ele está ligado a uma célula individual. Qualquer pessoa que exibir a pasta de trabalho com permissões suficientes pode responder a um comentário. Um objeto Comment armazena essas respostas como objetos CommentReply . Você deve considerar um comentário como um thread e que um thread deve ter uma entrada especial como o ponto de partida.
Os comentários em uma pasta de trabalho são acompanhados pela Workbook.comments propriedade. Isso inclui comentários criados por usuários e comentários criados por seu suplemento. A propriedade Workbook.comments é um objeto CommentCollection que contém um conjunto de objetos Comentário. Os comentários também estão acessíveis no nível da planilha . Os exemplos neste artigo funcionam com comentários no nível da pasta de trabalho, mas podem ser facilmente modificados para usar a Worksheet.comments propriedade.
Adicionar comentários
Use o CommentCollection.add método para adicionar comentários a uma pasta de trabalho. Esse método leva até três parâmetros:
cellAddress: a célula em que o comentário é adicionado. Isso pode ser uma cadeia de caracteres ou um objeto Range . O intervalo deve ser uma única célula.content: o conteúdo do comentário. Use uma cadeia de caracteres para comentários de texto simples. Use um objeto CommentRichContent para comentários com menções.contentType: um enumeração ContentType que especifica o tipo de conteúdo. O valor padrão éContentType.plain.
O exemplo a seguir adiciona um comentário à célula A2.
await Excel.run(async (context) => {
// Add a comment to A2 on the "MyWorksheet" worksheet.
let comments = context.workbook.comments;
// Note that an InvalidArgument error will be thrown if multiple cells passed to `Comment.add`.
comments.add("MyWorksheet!A2", "TODO: add data.");
await context.sync();
});
Observação
Os comentários adicionados por um suplemento são atribuídos ao usuário atual desse suplemento.
Adicionar respostas de comentário
Um Comment objeto é um thread de comentário que contém zero ou mais respostas. os objetos Comment têm uma propriedade replies, que é CommentReplyCollection que contém objetos CommentReply. Para adicionar uma resposta a um comentário, use o método CommentReplyCollection.add, passando o texto da resposta. As respostas são exibidas na ordem em que são adicionadas. Eles também são atribuídos ao usuário atual do suplemento.
O exemplo a seguir adiciona uma resposta ao primeiro comentário da pasta de trabalho.
await Excel.run(async (context) => {
// Get the first comment added to the workbook.
let comment = context.workbook.comments.getItemAt(0);
comment.replies.add("Thanks for the reminder!");
await context.sync();
});
Editar comentários
Para editar um comentário ou uma resposta de comentário, defina uma propriedadeComment.content e uma propriedadeCommentReply.content.
await Excel.run(async (context) => {
// Edit the first comment in the workbook.
let comment = context.workbook.comments.getItemAt(0);
comment.content = "PLEASE add headers here.";
await context.sync();
});
Editar respostas de comentário
Para editar uma resposta de comentário, defina sua CommentReply.content propriedade.
await Excel.run(async (context) => {
// Edit the first comment reply on the first comment in the workbook.
let comment = context.workbook.comments.getItemAt(0);
let reply = comment.replies.getItemAt(0);
reply.content = "Never mind";
await context.sync();
});
Excluir comentários
Para excluir um comentário, use o Comment.delete método. Excluir um comentário também exclui as respostas associadas a esse comentário.
await Excel.run(async (context) => {
// Delete the comment thread at A2 on the "MyWorksheet" worksheet.
context.workbook.comments.getItemByCell("MyWorksheet!A2").delete();
await context.sync();
});
Excluir respostas de comentário
Para excluir uma resposta de comentário, use o CommentReply.delete método.
await Excel.run(async (context) => {
// Delete the first comment reply from this worksheet's first comment.
let comment = context.workbook.comments.getItemAt(0);
comment.replies.getItemAt(0).delete();
await context.sync();
});
Resolver threads de comentários
Um thread de comentário tem um valor booliano configurável, resolved, para indicar se ele está resolvido. Um valor de true significa que o thread de comentário foi resolvido. Um valor de false significa que o thread de comentário é novo ou reaberto.
await Excel.run(async (context) => {
// Resolve the first comment thread in the workbook.
context.workbook.comments.getItemAt(0).resolved = true;
await context.sync();
});
As respostas de comentário têm uma propriedade somente resolved leitura. Seu valor é sempre igual ao do restante do thread.
Metadados de comentário
Cada comentário contém metadados sobre a criação, como o autor e a data de criação. Os comentários criados por seu suplemento são considerados criados pelo usuário atual.
O exemplo a seguir mostra como exibir o email do autor, o nome do autor e a data de criação de um comentário em A2.
await Excel.run(async (context) => {
// Get the comment at cell A2 in the "MyWorksheet" worksheet.
let comment = context.workbook.comments.getItemByCell("MyWorksheet!A2");
// Load and print the following values.
comment.load(["authorEmail", "authorName", "creationDate"]);
await context.sync();
console.log(`${comment.creationDate.toDateString()}: ${comment.authorName} (${comment.authorEmail})`);
});
Metadados de resposta de comentário
As respostas de comentário armazenam os mesmos tipos de metadados que o comentário inicial.
O exemplo a seguir mostra como exibir o email do autor, o nome do autor e a data de criação da resposta de comentário mais recente no A2.
await Excel.run(async (context) => {
// Get the comment at cell A2 in the "MyWorksheet" worksheet.
let comment = context.workbook.comments.getItemByCell("MyWorksheet!A2");
let replyCount = comment.replies.getCount();
// Sync to get the current number of comment replies.
await context.sync();
// Get the last comment reply in the comment thread.
let reply = comment.replies.getItemAt(replyCount.value - 1);
reply.load(["authorEmail", "authorName", "creationDate"]);
// Sync to load the reply metadata to print.
await context.sync();
console.log(`Latest reply: ${reply.creationDate.toDateString()}: ${reply.authorName} ${reply.authorEmail})`);
await context.sync();
});
Menções
As menções são usadas para marcar colegas em um comentário. Isso envia notificações com o conteúdo do seu comentário. Seu suplemento pode criar essas menções em seu nome.
Comentários com menções precisam ser criados com objetos CommentRichContent . Chame CommentCollection.add com uma CommentRichContent que contenha uma ou mais menções e especifique ContentType.mention como o contentType parâmetro. A content cadeia de caracteres também precisa ser formatada para inserir a menção no texto. O formato para uma menção é: <at id="{replyIndex}">{mentionName}</at>.
Observação
Atualmente, apenas o nome exato da menção pode ser usado como o texto do link de menção. O suporte para versões abreviadas de um nome será adicionado posteriormente.
O exemplo a seguir mostra um comentário com uma única menção.
await Excel.run(async (context) => {
// Add an "@mention" for "Kate Kristensen" to cell A1 in the "MyWorksheet" worksheet.
let mention = {
email: "kakri@contoso.com",
id: 0,
name: "Kate Kristensen"
};
// This will tag the mention's name using the '@' syntax.
// They will be notified via email.
let commentBody = {
mentions: [mention],
richContent: '<at id="0">' + mention.name + "</at> - Can you take a look?"
};
// Note that an InvalidArgument error will be thrown if multiple cells passed to `comment.add`.
context.workbook.comments.add("MyWorksheet!A1", commentBody, Excel.ContentType.mention);
await context.sync();
});
Eventos de comentário
Seu suplemento pode ouvir adições de comentários, alterações e exclusões. Eventos de comentário ocorrem no CommentCollection objeto. Para ouvir os eventos de comentário, registre o onAddedmanipulador de eventos , onChangedou onDeleted comente. Quando um evento de comentário for detectado, use esse manipulador de eventos para recuperar dados sobre o comentário adicionado, alterado ou excluído. O onChanged evento também lida com adições de resposta de comentários, alterações e exclusões.
Cada evento de comentário é disparado apenas uma vez quando várias adições, alterações ou exclusões são executadas ao mesmo tempo. Todos os objetos CommentAddedEventArgs, CommentChangedEventArgs e CommentDeletedEventArgs contêm matrizes de IDs de comentário para mapear as ações de evento de volta às coleções de comentários.
Consulte o artigo Trabalhar com Eventos usando a API JavaScript do Excel para obter informações adicionais sobre como registrar manipuladores de eventos, lidar com eventos e remover manipuladores de eventos.
Eventos de adição de comentários
O onAdded evento é disparado quando um ou mais novos comentários são adicionados à coleção de comentários. Esse evento não é disparado quando as respostas são adicionadas a um thread de comentários (confira Eventos de alteração de comentário para saber mais sobre eventos de resposta a comentários).
O exemplo a seguir mostra como registrar o onAdded manipulador de eventos e, em seguida, usar o CommentAddedEventArgs objeto para recuperar a commentDetails matriz do comentário adicionado.
Observação
Esse exemplo só funciona quando um único comentário é adicionado.
await Excel.run(async (context) => {
let comments = context.workbook.worksheets.getActiveWorksheet().comments;
// Register the onAdded comment event handler.
comments.onAdded.add(commentAdded);
await context.sync();
});
async function commentAdded() {
await Excel.run(async (context) => {
// Retrieve the added comment using the comment ID.
// Note: This method assumes only a single comment is added at a time.
let addedComment = context.workbook.comments.getItem(event.commentDetails[0].commentId);
// Load the added comment's data.
addedComment.load(["content", "authorName"]);
await context.sync();
// Print out the added comment's data.
console.log(`A comment was added. ID: ${event.commentDetails[0].commentId}. Comment content:${addedComment.content}. Comment author:${addedComment.authorName}`);
await context.sync();
});
}
Eventos de alteração de comentário
O onChanged evento de comentário é disparado nos cenários a seguir.
- O conteúdo de um comentário é atualizado.
- Um thread de comentário é resolvido.
- Um thread de comentários é reaberto.
- Uma resposta é adicionada a um thread de comentário.
- Uma resposta é atualizada em um thread de comentário.
- Uma resposta é excluída em um thread de comentário.
O exemplo a seguir mostra como registrar o onChanged manipulador de eventos e, em seguida, usar o CommentChangedEventArgs objeto para recuperar a commentDetails matriz do comentário alterado.
Observação
Esse exemplo só funciona quando um único comentário é alterado.
await Excel.run(async (context) => {
let comments = context.workbook.worksheets.getActiveWorksheet().comments;
// Register the onChanged comment event handler.
comments.onChanged.add(commentChanged);
await context.sync();
});
async function commentChanged() {
await Excel.run(async (context) => {
// Retrieve the changed comment using the comment ID.
// Note: This method assumes only a single comment is changed at a time.
let changedComment = context.workbook.comments.getItem(event.commentDetails[0].commentId);
// Load the changed comment's data.
changedComment.load(["content", "authorName"]);
await context.sync();
// Print out the changed comment's data.
console.log(`A comment was changed. ID: ${event.commentDetails[0].commentId}. Updated comment content: ${changedComment.content}. Comment author: ${changedComment.authorName}`);
await context.sync();
});
}
Eventos de exclusão de comentários
O onDeleted evento é disparado quando um comentário é excluído da coleção de comentários. Depois que um comentário é excluído, seus metadados não estão mais disponíveis. O objeto CommentDeletedEventArgs fornece IDs de comentário, caso seu suplemento esteja gerenciando comentários individuais.
O exemplo a seguir mostra como registrar o onDeleted manipulador de eventos e, em seguida, usar o CommentDeletedEventArgs objeto para recuperar a commentDetails matriz do comentário excluído.
Observação
Esse exemplo só funciona quando um único comentário é excluído.
await Excel.run(async (context) => {
let comments = context.workbook.worksheets.getActiveWorksheet().comments;
// Register the onDeleted comment event handler.
comments.onDeleted.add(commentDeleted);
await context.sync();
});
async function commentDeleted() {
await Excel.run(async (context) => {
// Print out the deleted comment's ID.
// Note: This method assumes only a single comment is deleted at a time.
console.log(`A comment was deleted. ID: ${event.commentDetails[0].commentId}`);
});
}