Работа с комментариями с помощью API JavaScript для Excel

В этой статье описывается добавление, чтение, изменение и удаление комментариев в книге с помощью API JavaScript для Excel. Дополнительные сведения о функции комментариев см. в статье Вставка комментариев и заметок в Excel .

В API JavaScript для Excel комментарий включает как один начальный комментарий, так и связанное обсуждение потока. Он привязан к отдельной ячейке. Любой пользователь, просматривающий книгу с достаточными разрешениями, может ответить на комментарий. Объект Comment сохраняет эти ответы как объекты CommentReply . Комментарий следует рассматривать как поток, и поток должен иметь специальную запись в качестве отправной точки.

Комментарии в книге отслеживаются свойством Workbook.comments . Это касается примечаний, созданных пользователями, а также примечаний, созданных вашей надстройкой. Свойство Workbook.comments является объектом CommentCollection, содержащим коллекцию объектов Comment. Комментарии также доступны на уровне листа . Примеры в этой статье работают с комментариями на уровне книги, но их можно легко изменить для использования Worksheet.comments свойства .

Добавление примечаний

Используйте метод для CommentCollection.add добавления комментариев в книгу. Этот метод принимает до трех параметров:

• cellAddress: ячейка, в которой добавляется комментарий. Это может быть строка или объект Range . Диапазон должен быть одной ячейкой.
• content: содержимое комментария. Используйте строку для примечаний в виде обычного текста. Используйте объект CommentRichContent для комментариев с упоминаниями.
• contentType: перечисление ContentType , указывающее тип содержимого. Значение по умолчанию — ContentType.plain.

В следующем примере кода добавляется примечание в ячейку 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();
});

Примечание.

Комментарии, добавленные надстройкой, приписываются текущему пользователю этой надстройки.

Добавление ответов на комментарии

Объект Comment — это поток комментариев, содержащий ноль или больше ответов. Объекты Comment содержат свойство replies, являющееся коллекцией CommentReplyCollection, содержащей объекты CommentReply. Чтобы добавить ответ на примечание, используйте метод CommentReplyCollection.add, передающий текст ответа. Ответы отображаются в порядке их добавления. Они также относятся к текущему пользователю надстройки.

В следующем примере кода добавляется ответ к первому примечанию в книге.

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

Изменение примечаний

Чтобы изменить примечание или ответ на примечание, настройте его свойство Comment.content или CommentReply.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();
});

Изменение ответов на комментарии

Чтобы изменить ответ на комментарий, задайте его CommentReply.content свойство.

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

Удалять комментарии.

Чтобы удалить комментарий, Comment.delete используйте метод . При удалении комментария также удаляются ответы, связанные с этим комментарием.

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

Удаление ответов примечаний

Чтобы удалить ответ на комментарий, используйте CommentReply.delete метод .

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

Разрешение потоков комментариев

Поток комментариев имеет настраиваемое логическое значение , чтобы указать, resolvedразрешено ли оно. Значение true означает, что поток комментариев разрешен. Значение false означает, что поток комментариев является новым или вновь открытым.

await Excel.run(async (context) => {
    // Resolve the first comment thread in the workbook.
    context.workbook.comments.getItemAt(0).resolved = true;
    await context.sync();
});

Ответы на комментарии имеют свойство только resolved для чтения. Его значение всегда равно значению остальной части потока.

Метаданные комментариев

Каждое примечание содержит метаданные о его создании, например автора и дату создания. Автором примечаний, созданных вашей надстройкой, считается текущий пользователь.

В следующем примере показано, как отобразить электронную почту автора, имя автора и дату создания примечания в ячейке 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})`);
});

Метаданные ответа примечания

Ответы на комментарии хранят те же типы метаданных, что и исходный комментарий.

В следующем примере показано, как отобразить адрес электронной почты автора, его имя и дату создания последнего ответа на комментарий в 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();
});

Упоминания

Упоминания используются для добавления тегов к коллегам в комментарий. При этом им будут отправлены уведомления о содержимом вашего комментария. Надстройка может создавать эти упоминания от вашего имени.

Комментарии с упоминаниями необходимо создавать с помощью объектов CommentRichContent . Вызовите CommentCollection.add с CommentRichContent одним или несколькими упоминаниями и укажите ContentType.mention в contentType качестве параметра. Строка content также должна быть отформатирована, чтобы вставить упоминание в текст. Формат упоминания: <at id="{replyIndex}">{mentionName}</at>.

Примечание.

В настоящее время в качестве текста ссылки на упоминание можно использовать только точное имя упоминания. Поддержка сокращенных версий имени будет добавлена позже.

В следующем примере показан комментарий с одним упоминанием.

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

Закомментировать события

Ваша надстройка может прослушивать добавление комментариев, изменения и удаления. События комментариев происходят в объекте CommentCollection . Чтобы прослушать события комментариев, зарегистрируйте onAddedобработчик событий , onChangedили onDeleted comment. При обнаружении события комментария используйте этот обработчик событий для получения данных о добавленном, измененном или удаленном примечании. Это onChanged событие также обрабатывает добавление, изменения и удаления примечаний.

Каждое событие комментария активируется только один раз, когда одновременно выполняется несколько добавлений, изменений или удалений. Все объекты CommentAddedEventArgs, CommentChangedEventArgs и CommentDeletedEventArgs содержат массивы идентификаторов комментариев для сопоставления действий событий с коллекциями комментариев.

Дополнительные сведения о регистрации обработчиков событий, обработке событий и удалении обработчиков событий см. в статье Работа с событиями с помощью API JavaScript для Excel .

События добавления комментариев

Событие onAdded активируется при добавлении одного или нескольких новых комментариев в коллекцию комментариев. Это событие не активируется при добавлении ответов в поток комментариев (сведения о событиях ответа примечания см. в разделе События изменения примечания).

В следующем примере показано, как зарегистрировать onAdded обработчик событий, а затем использовать CommentAddedEventArgs объект для получения commentDetails массива добавленного комментария.

Примечание.

Этот пример работает только при добавлении одного комментария.

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

Закомментируйте события изменений

Событие примечания onChanged активируется в следующих сценариях.

• Содержимое комментария обновляется.
• Поток примечаний разрешается.
• Снова открывается поток комментариев.
• Ответ добавляется в поток комментариев.
• Ответ обновляется в потоке комментариев.
• Ответ удаляется в потоке комментариев.

В следующем примере показано, как зарегистрировать onChanged обработчик событий, а затем использовать CommentChangedEventArgs объект для получения commentDetails массива измененного комментария.

Примечание.

Этот пример работает только при изменении одного комментария.

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

События удаления комментариев

Событие onDeleted активируется при удалении комментария из коллекции комментариев. После удаления комментария его метаданные больше не будут доступны. Объект CommentDeletedEventArgs предоставляет идентификаторы комментариев, если ваша надстройка управляет отдельными комментариями.

В следующем примере показано, как зарегистрировать onDeleted обработчик событий, а затем использовать CommentDeletedEventArgs объект для получения commentDetails массива удаленного комментария.

Примечание.

Этот пример работает только при удалении одного комментария.

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

См. также

• Объектная модель JavaScript для Excel в надстройках Office
• Работа с книгами с использованием API JavaScript для Excel
• Работа с событиями при помощи API JavaScript для Excel
• Вставка примечаний и заметок в Excel