Verwalten von Kommentaren in Excel-Add-Ins mithilfe der Excel-JavaScript-API

In diesem Artikel wird gezeigt, wie Sie mithilfe der Excel-JavaScript-API Threadkommentare für bestimmte Zellen erstellen, antworten, bearbeiten oder löschen, Unterhaltungen auflösen, Autorenmetadaten lesen, Erwähnungen hinzufügen und auf Kommentarereignisse reagieren.

In der Excel-JavaScript-API ist ein Kommentar ein Thread, der mit einem Kommentar beginnt und Antworten enthalten kann. Jeder Thread ist an eine einzelne Zelle gebunden. Wenn Sie ein Legacynotizverhalten anstelle von Diskussionsthreads benötigen, finden Sie weitere Informationen unter Arbeiten mit Notizen mithilfe der Excel-JavaScript-API.

Was Sie mit Kommentaren tun können

Verwenden Sie die Excel-Kommentar-APIs für Folgendes:

• Fügen Sie einer Zelle einen neuen Kommentarthread hinzu.
• Hinzufügen, Bearbeiten und Löschen von Antworten in einem vorhandenen Thread.
• Auflösen oder erneutes Öffnen eines Threads.
• Lesen von Autoren- und Erstellungsmetadaten.
• Erstellen Sie Kommentare, die Erwähnungen enthalten.
• Lauschen sie auf Ereignisse zum Hinzufügen, Ändern und Löschen von Kommentaren.

Grundlegendes zum Kommentarobjektmodell

Die Workbook.comments -Eigenschaft verfolgt Kommentare in einer Arbeitsmappe nach. Diese Eigenschaft gibt eine CommentCollection zurück, die sowohl vom Benutzer erstellte Kommentare als auch Kommentare enthält, die von Ihrem Add-In erstellt wurden. Sie können auch über Worksheet.comments die -Eigenschaft auf Kommentare auf Arbeitsblattebene zugreifen.

Ein Comment-Objekt stellt den vollständigen Thread für eine einzelne Zelle dar. Antworten in diesem Thread werden als CommentReply-Objekte in der Auflistung des Kommentars replies gespeichert.

Hinzufügen von Kommentarthreads

Verwenden Sie CommentCollection.add , um eine Konversationsthread in einer Zelle zu starten. Die -Methode akzeptiert bis zu drei Parameter:

• cellAddress: Die Zelle, in der Sie den Kommentar hinzufügen. Bei diesem Parameter kann es sich um eine Zeichenfolge oder ein Range-Objekt handeln. Der Bereich muss eine einzelne Zelle sein.
• content: Der Kommentartext. Verwenden Sie eine Zeichenfolge für Nur-Text-Kommentare. Verwenden Sie ein CommentRichContent-Objekt für Kommentare, die Erwähnungen enthalten.
• contentType: Ein ContentType-Wert , der den Inhaltstyp angibt. Der Standardwert lautet ContentType.plain.

Im folgenden Beispiel wird ein Überprüfungsthread für Zelle A2 gestartet. Beachten Sie, dass Kommentare, die ihr Add-In erstellt, dem aktuellen Benutzer zugeordnet werden.

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

Hinzufügen von Antworten zu einem Kommentarthread

Verwenden Sie CommentReplyCollection.add , wenn Ihr Add-In eine vorhandene Diskussion fortsetzen muss. Antworten werden in der Reihenfolge angezeigt, in der sie hinzugefügt werden, und sie werden auch dem aktuellen Benutzer zugeordnet.

Im folgenden Beispiel wird dem Thread in Zelle A2 eine Antwort hinzugefügt.

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

Kommentarthreads bearbeiten

Aktualisieren Sie Comment.content , um den ersten Eintrag in einem Thread zu ändern. Aktualisieren CommentReply.content Sie, um eine bestimmte Antwort zu ändern.

Im folgenden Beispiel wird der Hauptkommentar in Zelle A2 aktualisiert.

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

Bearbeiten einer Antwort

Verwenden Sie dieses Muster, wenn Ihr Add-In eine frühere Antwort im Thread überarbeiten muss.

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

Kommentarthreads löschen

Verwenden Sie Comment.delete() , um einen gesamten Thread aus einer Zelle zu entfernen. Durch das Löschen eines Kommentars werden auch alle Antworten in diesem Thread gelöscht.

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

Löschen einer Antwort

Verwenden Sie CommentReply.delete() , wenn Sie eine einzelne Antwort entfernen müssen, aber den Rest des Threads beibehalten.

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

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

Auflösen und erneutes Öffnen von Kommentarthreads

Verwenden Sie die Comment.resolved -Eigenschaft, um nachzuverfolgen, ob eine Diskussion noch Aufmerksamkeit benötigt. Legen Sie den Wert auf fest, um true den Thread aufzulösen, oder auf , false um ihn erneut zu öffnen. CommentReply.resolved ist schreibgeschützt und stimmt immer mit dem Zustand des übergeordneten Threads überein.

Im folgenden Beispiel wird der Thread in Zelle A2 aufgelöst.

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

Lesen von Kommentarmetadaten

Jeder Kommentar speichert Metadaten wie den Autor und das Erstellungsdatum. Von Ihrem Add-In erstellte Kommentare werden vom aktuellen Benutzer erstellt.

Im folgenden Beispiel werden die E-Mail-Adresse des Autors, der Name des Autors und das Erstellungsdatum für den Kommentar in Zelle A2 protokolliert.

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

Lesen von Antwortmetadaten

Antworten speichern die gleichen Metadaten wie der ursprüngliche Kommentar. Im folgenden Beispiel wird die neueste Antwort im Thread der Zelle A2 abgerufen und die zugehörigen Autoreninformationen protokolliert.

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

Benutzer erwähnen

Verwenden Sie Erwähnungen, wenn Ihr Add-In einen Kollegen in einem Kommentar markieren und eine E-Mail-Benachrichtigung auslösen muss. Um einen Kommentar mit Erwähnungen zu erstellen, rufen Sie CommentCollection.add mit einem CommentRichContent-Objekt auf, und legen Sie den contentType Parameter auf fest ContentType.mention.

Formatieren Sie jede Erwähnung in der richContent Zeichenfolge als <at id="{replyIndex}">{mentionName}</at>.

Derzeit kann nur der genaue Name des Erwähnung als Text des Erwähnung-Links verwendet werden. Unterstützung für verkürzte Versionen eines Namens wird später hinzugefügt.

Im folgenden Beispiel wird zelle A1 ein Kommentar mit einem einzelnen Erwähnung hinzugefügt.

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

Verarbeiten von Kommentarereignissen

Verwenden Sie Kommentarereignisse, wenn Ihr Add-In auf Diskussionen reagieren muss, wenn Benutzer eine Arbeitsmappe aktualisieren. Kommentarereignisse treten für das CommentCollection Objekt auf.

Registrieren von Handlern für:

• onAdded , wenn ein neuer Kommentarthread erstellt wird.
• onChanged wenn ein Kommentar oder eine Antwort hinzugefügt, bearbeitet, gelöscht, aufgelöst oder erneut geöffnet wird.
• onDeleted , wenn ein Kommentarthread gelöscht wird.

Wenn ein Vorgang mehrere Kommentare betrifft, enthalten die Ereignisargumente mehrere Elemente in commentDetails. In den folgenden Beispielen wird das erste Element nur aus Gründen der Übersichtlichkeit verwendet. Allgemeine Informationen zu Ereignissen finden Sie unter Arbeiten mit Ereignissen mithilfe der Excel-JavaScript-API.

Verarbeiten von Kommentarzugabeereignissen

Das onAdded -Ereignis wird ausgelöst, wenn der Auflistung mindestens ein Kommentar hinzugefügt wird. Sie wird nicht ausgelöst, wenn einem vorhandenen Thread eine Antwort hinzugefügt wird.

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

Behandeln von Kommentaränderungsereignissen

Das onChanged Ereignis wird ausgelöst, wenn:

• Der Inhalt eines Kommentars wird aktualisiert.
• Ein Kommentarthread wird aufgelöst.
• Ein Kommentarthread wird erneut geöffnet.
• Eine Antwort wird einem Kommentarthread hinzugefügt.
• Eine Antwort wird in einem Kommentarthread aktualisiert.
• Eine Antwort wird aus einem Kommentarthread gelöscht.

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

Behandeln von Löschereignissen für Kommentare

Das onDeleted Ereignis wird ausgelöst, wenn ein Kommentar aus der Auflistung gelöscht wird. Nachdem ein Kommentar gelöscht wurde, sind seine Metadaten nicht mehr verfügbar. Verwenden Sie die IDs in CommentDeletedEventArgs.commentDetails , wenn Ihr Add-In gelöschte Threads nachverfolgen muss.

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

Siehe auch

• Grundlegende Excel-Objektmodellkonzepte für Office-Add-Ins
• Verwalten von Excel-Arbeitsmappen mit der Excel-JavaScript-API
• Arbeiten mit Ereignissen mithilfe der Excel-JavaScript-API
• Arbeiten mit Notizen mithilfe der Excel-JavaScript-API
• Gemeinsame Dokumenterstellung in Excel-Add-Ins
• Einfügen von Kommentaren und Notizen in Excel