Gerenciar comentários em suplementos do Excel usando a API JavaScript do Excel

Este artigo mostra como criar comentários encadeados em células específicas, respondê-los, editá-los ou excluí-los, resolver conversas, ler metadados do autor, adicionar menções e responder a eventos de comentários usando a API JavaScript do Excel.

Na API JavaScript do Excel, um comentário é um thread que começa com um comentário e pode incluir respostas. Cada thread está vinculado a uma única célula. Se você precisar de um comportamento de anotação herdado em vez de discussões encadeadas, consulte Trabalhar com anotações usando a API JavaScript do Excel.

O que você pode fazer com os comentários

Use as APIs de comentários do Excel para:

• Adicione um novo thread de comentário a uma célula.
• Adicione, edite e exclua respostas em um thread existente.
• Resolver ou reabrir um tópico.
• Leia os metadados do autor e da criação.
• Crie comentários que incluam menções.
• Ouça comentários, adicione, altere e exclua eventos.

Entender o modelo de objeto de comentário

A Workbook.comments propriedade rastreia comentários em uma pasta de trabalho. Essa propriedade retorna um CommentCollection que contém comentários criados pelo usuário e comentários criados pelo seu suplemento. Você também pode acessar comentários no nível da planilha por meio da Worksheet.comments propriedade.

Um objeto Comment representa o thread completo de uma única célula. As respostas nesse thread são armazenadas como objetos CommentReply na coleção do replies comentário.

Adicionar thread de comentários

Use CommentCollection.add para iniciar uma conversa encadeada em uma célula. O método aceita até três parâmetros:

• cellAddress: a célula em que você adiciona o comentário. Esse parâmetro pode ser uma cadeia de caracteres ou um objeto Range . O intervalo deve ser uma única célula.
• content: O texto do comentário. Use uma cadeia de caracteres para comentários de texto sem formatação. Use um objeto CommentRichContent para comentários que incluam menções.
• contentType: um valor ContentType que especifica o tipo de conteúdo. O padrão é ContentType.plain.

O exemplo a seguir inicia um thread de revisão na célula A2. Observe que os comentários criados pelo suplemento são atribuídos ao usuário atual.

await Excel.run(async (context) => {
    const comments = context.workbook.comments;
    comments.add("MyWorksheet!A2", "Please confirm the Q2 revenue total.");
    await context.sync();
});

Adicionar respostas a um thread de comentários

Use CommentReplyCollection.add quando o suplemento precisar continuar uma discussão existente. As respostas são exibidas na ordem em que são adicionadas e também são atribuídas ao usuário atual.

O exemplo a seguir adiciona uma resposta ao thread na célula A2.

await Excel.run(async (context) => {
    const comment = context.workbook.comments.getItemByCell("MyWorksheet!A2");
    comment.replies.add("Thanks for the reminder!");
    await context.sync();
});

Editar threads de comentários

Atualize Comment.content para alterar a primeira entrada em um thread. Atualize CommentReply.content para alterar uma resposta específica.

O exemplo a seguir atualiza o comentário principal na célula A2.

await Excel.run(async (context) => {
    const comment = context.workbook.comments.getItemByCell("MyWorksheet!A2");
    comment.content = "Please confirm the Q2 revenue total before we publish this workbook.";
    await context.sync();
});

Editar uma resposta

Use esse padrão quando o suplemento precisar revisar uma resposta anterior no thread.

await Excel.run(async (context) => {
    const comment = context.workbook.comments.getItemByCell("MyWorksheet!A2");
    const reply = comment.replies.getItemAt(0);

    reply.content = "Thanks. I rechecked the total and it is correct.";
    await context.sync();
});

Excluir threads de comentários

Use Comment.delete() para remover um thread inteiro de uma célula. Excluir um comentário também exclui todas as respostas nesse tópico.

await Excel.run(async (context) => {
    const comment = context.workbook.comments.getItemByCell("MyWorksheet!A2");
    comment.delete();
    await context.sync();
});

Excluir uma resposta

Use CommentReply.delete() quando precisar remover uma única resposta, mas mantenha o restante do thread.

await Excel.run(async (context) => {
    const comment = context.workbook.comments.getItemByCell("MyWorksheet!A2");
    const reply = comment.replies.getItemAt(0);

    reply.delete();
    await context.sync();
});

Resolver e reabrir threads de comentários

Use a Comment.resolved propriedade para controlar se uma discussão ainda precisa de atenção. Defina o valor como true para resolver o tópico ou para false reabri-lo. CommentReply.resolved é somente leitura e sempre corresponde ao estado do thread pai.

O exemplo a seguir resolve o thread na célula A2.

await Excel.run(async (context) => {
    const comment = context.workbook.comments.getItemByCell("MyWorksheet!A2");
    comment.resolved = true;
    await context.sync();
});

Ler metadados de comentários

Cada comentário armazena metadados como o autor e a data de criação. Os comentários criados pelo seu suplemento são de autoria do usuário atual.

O exemplo a seguir registra o e-mail do autor, o nome do autor e a data de criação do comentário na célula A2.

await Excel.run(async (context) => {
    const comment = context.workbook.comments.getItemByCell("MyWorksheet!A2");

    comment.load(["authorEmail", "authorName", "creationDate"]);
    await context.sync();

    console.log(`${comment.creationDate.toDateString()}: ${comment.authorName} (${comment.authorEmail})`);
});

Metadados de resposta de leitura

As respostas armazenam os mesmos metadados do comentário inicial. O exemplo a seguir obtém a resposta mais recente no thread na célula A2 e registra suas informações de autor.

await Excel.run(async (context) => {
    const comment = context.workbook.comments.getItemByCell("MyWorksheet!A2");
    const replyCount = comment.replies.getCount();
    await context.sync();

    if (replyCount.value === 0) {
        console.log("The thread has no replies.");
        return;
    }

    const reply = comment.replies.getItemAt(replyCount.value - 1);
    reply.load(["authorEmail", "authorName", "creationDate"]);
    await context.sync();

    console.log(`Latest reply: ${reply.creationDate.toDateString()}: ${reply.authorName} (${reply.authorEmail})`);
});

Mencionar usuários

Use menções quando o suplemento precisar marcar um colega em um comentário e disparar uma notificação por email. Para criar um comentário com menções, chame CommentCollection.add com um objeto CommentRichContent e defina o contentType parâmetro como ContentType.mention.

Formate cada menção na richContent cadeia de caracteres como <at id="{replyIndex}">{mentionName}</at>.

Atualmente, apenas o nome exato da menção pode ser usado como texto do link de menção. O suporte para versões abreviadas de um nome será adicionado posteriormente.

O exemplo a seguir adiciona um comentário com uma única menção à célula A1.

await Excel.run(async (context) => {
    const mention = {
        email: "kakri@contoso.com",
        id: 0,
        name: "Kate Kristensen"
    };

    const commentBody = {
        mentions: [mention],
        richContent: `<at id="0">${mention.name}</at> Can you review the forecast?`
    };

    // An `InvalidArgument` error is thrown if the range contains multiple cells.
    context.workbook.comments.add("MyWorksheet!A1", commentBody, Excel.ContentType.mention);
    await context.sync();
});

Manipular eventos de comentários

Use eventos de comentários quando o suplemento precisar reagir às discussões à medida que os usuários atualizam uma pasta de trabalho. Eventos de comentário ocorrem no CommentCollection objeto.

Registrar manipuladores para:

• onAdded Quando um novo thread de comentário é criado.
• onChanged Quando um comentário ou resposta é adicionado, editado, excluído, resolvido ou reaberto.
• onDeleted Quando um thread de comentário é excluído.

Se uma operação afetar vários comentários, os argumentos do evento conterão vários itens em commentDetails. Os exemplos a seguir usam o primeiro item apenas para maior clareza. Para obter diretrizes gerais sobre eventos, consulte Trabalhar com eventos usando a API JavaScript do Excel.

Lidar com eventos de adição de comentários

O onAdded evento é acionado quando um ou mais comentários são adicionados à coleção. Ele não é acionado quando uma resposta é adicionada a um thread existente.

await Excel.run(async (context) => {
    const comments = context.workbook.worksheets.getActiveWorksheet().comments;

    comments.onAdded.add(commentAdded);
    await context.sync();
});

async function commentAdded(event) {
    await Excel.run(async (context) => {
        const addedComment = context.workbook.comments.getItem(event.commentDetails[0].commentId);
        addedComment.load(["content", "authorName"]);
        await context.sync();

        console.log(`A comment was added. ID: ${event.commentDetails[0].commentId}. Content: ${addedComment.content}. Author: ${addedComment.authorName}`);
    });
}

Manipular eventos de alteração de comentário

O onChanged evento é acionado quando:

• O conteúdo de um comentário é atualizado.
• Um thread de comentários foi resolvido.
• Um thread de comentários é reaberto.
• Uma resposta é adicionada a um thread de comentários.
• Uma resposta é atualizada em um thread de comentários.
• Uma resposta é excluída de um thread de comentários.

await Excel.run(async (context) => {
    const comments = context.workbook.worksheets.getActiveWorksheet().comments;

    comments.onChanged.add(commentChanged);
    await context.sync();
});

async function commentChanged(event) {
    await Excel.run(async (context) => {
        const changedComment = context.workbook.comments.getItem(event.commentDetails[0].commentId);
        changedComment.load(["content", "authorName"]);
        await context.sync();

        console.log(`A comment was changed. ID: ${event.commentDetails[0].commentId}. Content: ${changedComment.content}. Author: ${changedComment.authorName}`);
    });
}

Manipular eventos de exclusão de comentários

O onDeleted evento é acionado quando um comentário é excluído da coleção. Depois que um comentário é excluído, seus metadados não estão mais disponíveis. Use as IDs se CommentDeletedEventArgs.commentDetails o suplemento precisar acompanhar os threads excluídos.

await Excel.run(async (context) => {
    const comments = context.workbook.worksheets.getActiveWorksheet().comments;

    comments.onDeleted.add(commentDeleted);
    await context.sync();
});

async function commentDeleted(event) {
    console.log(`A comment was deleted. ID: ${event.commentDetails[0].commentId}`);
}

Confira também

• Principais conceitos de modelo de objeto do Excel para Suplementos do Office
• Gerenciar pastas de trabalho do Excel com a API JavaScript do Excel
• Trabalhar com eventos usando a API JavaScript do Excel
• Trabalhar com anotações usando a API JavaScript do Excel
• Coautoria em suplementos do Excel
• Inserir comentários e anotações no Excel