使用 Excel JavaScript API 处理注释

项目
04/07/2023

本文介绍如何使用 Excel JavaScript API 在工作簿中添加、读取、修改和删除注释。有关注释功能的详细信息，请参阅在 Excel 中插入批注和注释一文。

在 Excel JavaScript API 中，注释包括单个初始注释和连接的线程讨论。它与单个单元格绑定。查看工作簿且具有足够权限的任何人都可以回复批注。 Comment 对象将这些答复存储为 CommentReply 对象。应将注释视为线程，并且线程必须有一个特殊条目作为起点。

一个 Excel 批注，标记为“注释”，并带有两个答复，标记为“Comment.答复[0]”和“Comment.replies[1]。

工作簿中的注释由 Workbook.comments 属性跟踪。这包括由用户创建的批注以及由加载项创建的批注。 Workbook.comments 属性是一个包含一系列 Comment 对象的 CommentCollection 对象。还可以在工作表级别访问批注。本文中的示例使用工作簿级别的注释，但可以轻松修改它们以使用 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 属性，后者是一个包含 CommentReply 对象的 CommentReplyCollection 对象。若要向批注添加回复，请使用 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 对象创建带提及的注释。使用CommentRichContent包含一个或多个提及的调用 CommentCollection.add ，并将指定 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 注释事件处理程序。检测到注释事件时，使用此事件处理程序检索有关添加、更改或删除的批注的数据。该 onChanged 事件还处理注释答复添加、更改和删除。

当同时执行多个添加、更改或删除操作时，每个注释事件只会触发一次。所有 CommentAddedEventArgs、 CommentChangedEventArgs 和 CommentDeletedEventArgs 对象都包含注释 ID 数组，用于将事件操作映射回注释集合。

有关注册事件处理程序、处理事件和删除事件处理程序的其他信息，请参阅使用 Excel JavaScript API 处理事件一文。

注释添加事件

将 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 对象提供注释 ID，以防加载项正在管理单个注释。

下面的示例演示如何注册事件处理程序， 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}`);
    });
}