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();
});

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>.

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.

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.

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.

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}`);
    });
}

Confira também

• Modelo de objeto JavaScript do Excel em Suplementos do Office
• Trabalhar com pastas de trabalho usando a API JavaScript do Excel
• Trabalhar com eventos usando a API JavaScript do Excel
• Inserir comentários e anotações no Excel