Arbeiten mit Kommentaren mithilfe der Excel JavaScript-API

In diesem Artikel wird beschrieben, wie Sie Kommentare in einer Arbeitsmappe mit der Excel JavaScript-API hinzufügen, lesen, ändern und entfernen. Weitere Informationen zur Kommentarfunktion finden Sie unter "Einfügen von Kommentaren und Notizen" in Excel Artikel.

In der Excel JavaScript-API enthält ein Kommentar sowohl den einzelnen anfänglichen Kommentar als auch die Diskussion mit dem verbundenen Thread. Sie ist an eine einzelne Zelle gebunden. Jeder Benutzer, der die Arbeitsmappe mit ausreichenden Berechtigungen anzeigt, kann auf einen Kommentar antworten. Ein Comment - Objekt speichert diese Antworten als CommentReply -Objekte. Sie sollten einen Kommentar als Thread betrachten und dass ein Thread einen speziellen Eintrag als Ausgangspunkt haben muss.

Ein Excel Kommentar mit der Bezeichnung "Kommentar" mit zwei Antworten mit der Bezeichnung "Comment.replies[0]" und "Comment.replies[1].

Kommentare innerhalb einer Arbeitsmappe werden von der Workbook.comments Eigenschaft nachverfolgt. Dies umfasst von Benutzern erstellte Kommentare und auch Kommentare, die von Ihrem Add-in erstellt wurden. Die Eigenschaft Workbook.comments ist ein CommentCollection-Objekt, das eine Sammlung von Comment-Objekten enthält. Kommentare können auch auf Arbeitsblattebene abgerufen werden. Die Beispiele in diesem Artikel arbeiten mit Kommentaren auf Arbeitsmappenebene, können jedoch einfach geändert werden, um die Worksheet.comments Eigenschaft zu verwenden.

Kommentare hinzufügen

Verwenden Sie die CommentCollection.add Methode, um einer Arbeitsmappe Kommentare hinzuzufügen. Diese Methode akzeptiert bis zu drei Parameter:

  • cellAddress: Die Zelle, in der der Kommentar hinzugefügt wird. Dies kann entweder eine Zeichenfolge oder ein Range-Objekt sein. Der Bereich muss eine einzelne Zelle sein.
  • content: Der Inhalt des Kommentars. Verwenden Sie eine Zeichenfolge für Nur-Text-Kommentare. Verwenden Sie ein CommentRichContent -Objekt für Kommentare mit Erwähnungen.
  • contentType: Eine ContentType-Enumeration , die den Inhaltstyp angibt. Der Standardwert ist ContentType.plain.

Im folgenden Codebeispiel wird Zelle A2 ein Kommentar hinzugefügt.

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

Hinweis

Kommentare, die von einem Add-In hinzugefügt werden, werden dem aktuellen Benutzer dieses Add-Ins zugeordnet.

Hinzufügen von Kommentarantworten

Ein Comment Objekt ist ein Kommentarthread, der null oder mehr Antworten enthält. Comment-Objekte besitzen eine replies-Eigenschaft, bei der es sich um eine CommentReplyCollection handelt, die CommentReply-Objekte enthält. Wenn Sie eine Antwort auf einen Kommentar hinzufügen möchten, verwenden Sie die CommentReplyCollection.add-Methode, und geben Sie den Text der Antwort weiter. Antworten werden in der Reihenfolge angezeigt, in der Sie hinzugefügt wurden. Sie werden auch dem aktuellen Benutzer des Add-Ins zugeordnet.

Im folgenden Codebeispiel wird eine Antwort zum ersten Kommentar im Arbeitsblatts hinzugefügt.

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

Kommentare bearbeiten

Um einen Kommentar oder eine Antwort auf einen Kommentar zu bearbeiten, legen Sie deren Comment.content- oder CommentReply.content-Eigenschaft fest.

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

Bearbeiten von Kommentarantworten

Um eine Kommentarantwort zu bearbeiten, legen Sie ihre CommentReply.content Eigenschaft fest.

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

Kommentare löschen

Verwenden Sie die Comment.delete Methode, um einen Kommentar zu löschen. Durch das Löschen eines Kommentars werden auch die Antworten gelöscht, die diesem Kommentar zugeordnet sind.

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

Löschen von Kommentarantworten

Verwenden Sie die CommentReply.delete Methode, um eine Kommentarantwort zu löschen.

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

Auflösen von Kommentarthreads

Ein Kommentarthread hat einen konfigurierbaren booleschen Wert, um anzugeben, resolvedob er aufgelöst wurde. Ein Wert, der true bedeutet, dass der Kommentarthread aufgelöst wird. Ein Wert, der false bedeutet, dass der Kommentarthread entweder neu oder erneut geöffnet ist.

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

Kommentarantworten weisen eine readonly-Eigenschaft resolved auf. Der Wert ist immer gleich dem Wert des restlichen Threads.

Kommentarmetadaten

Jeder Kommentar enthält Metadaten seiner Erstellung, z. B. den Autor und das Erstellungsdatum. Von Ihrem Add-In erstellte Kommentare werden als vom aktuellen Benutzer verfasst betrachtet.

Das folgende Beispiel zeigt, wie Sie E-Mail-Adresse des Autors, der Name des Autors und das Erstellungsdatum eines Kommentars in A2 anzeigen.

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

Kommentarantwortmetadaten

Kommentarantworten speichern die gleichen Metadatentypen wie der ursprüngliche Kommentar.

Das folgende Beispiel zeigt, wie sie die E-Mail, den Namen des Autors und das Erstellungsdatum der letzten Kommentarantwort bei A2 anzeigen.

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

Erwähnungen

Erwähnungen werden verwendet, um Kollegen in einem Kommentar zu markieren. Dadurch werden ihnen Benachrichtigungen mit dem Inhalt Ihres Kommentars gesendet. Ihr Add-In kann diese Erwähnungen in Ihrem Namen erstellen.

Kommentare mit Erwähnungen müssen mit CommentRichContent-Objekten erstellt werden. Rufen Sie CommentCollection.add mit einer CommentRichContent oder mehreren Erwähnungen auf und geben Sie ContentType.mention als Parameter an contentType . Die content Zeichenfolge muss auch formatiert werden, um die Erwähnung in den Text einzufügen. Das Format für eine Erwähnung lautet: <at id="{replyIndex}">{mentionName}</at>.

Hinweis

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

Das folgende Beispiel zeigt einen Kommentar mit einer einzigen Erwähnung.

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

Kommentarereignisse

Ihr Add-In kann auf Ergänzungen, Änderungen und Löschungen von Kommentaren lauschen. Kommentarereignisse treten für das CommentCollection Objekt auf. Registrieren Sie zum Überwachen von Kommentarereignissen den onAddedEreignishandler , onChangedoder onDeleted den Kommentarereignishandler. Wenn ein Kommentarereignis erkannt wird, verwenden Sie diesen Ereignishandler, um Daten über den hinzugefügten, geänderten oder gelöschten Kommentar abzurufen. Das onChanged Ereignis behandelt auch Ergänzungen, Änderungen und Löschungen von Kommentarantworten.

Jedes Kommentarereignis wird nur einmal ausgelöst, wenn mehrere Hinzufügungen, Änderungen oder Löschungen gleichzeitig ausgeführt werden. Alle CommentAddedEventArgs-, CommentChangedEventArgs- und CommentDeletedEventArgs-Objekte enthalten Arrays von Kommentar-IDs, um die Ereignisaktionen den Kommentarsammlungen zuzuordnen.

Weitere Informationen zum Registrieren von Ereignishandlern, zum Behandeln von Ereignissen und zum Entfernen von Ereignishandlern finden Sie im Artikel "Arbeiten mit Ereignissen mithilfe der Excel JavaScript-API".

Kommentarzufügungsereignisse

Das onAdded Ereignis wird ausgelöst, wenn der Kommentarsammlung ein oder mehrere neue Kommentare hinzugefügt werden. Dieses Ereignis wird nicht ausgelöst, wenn Antworten zu einem Kommentarthread hinzugefügt werden (weitere Informationen zu Kommentarantwortereignissen finden Sie unter "Kommentaränderungsereignisse ").

Das folgende Beispiel zeigt, wie Sie den onAdded Ereignishandler registrieren und dann das CommentAddedEventArgs Objekt verwenden, um das commentDetails Array des hinzugefügten Kommentars abzurufen.

Hinweis

Dieses Beispiel funktioniert nur, wenn ein einzelner Kommentar hinzugefügt wird.

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

Kommentaränderungsereignisse

Das onChanged Kommentarereignis wird in den folgenden Szenarien ausgelöst.

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

Das folgende Beispiel zeigt, wie Sie den onChanged Ereignishandler registrieren und dann das CommentChangedEventArgs Objekt verwenden, um das commentDetails Array des geänderten Kommentars abzurufen.

Hinweis

Dieses Beispiel funktioniert nur, wenn ein einzelner Kommentar geändert wird.

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

Kommentarlöschungsereignisse

Das onDeleted Ereignis wird ausgelöst, wenn ein Kommentar aus der Kommentarsammlung gelöscht wird. Nachdem ein Kommentar gelöscht wurde, sind die Metadaten nicht mehr verfügbar. Das CommentDeletedEventArgs-Objekt stellt Kommentar-IDs bereit, falls Ihr Add-In einzelne Kommentare verwaltet.

Das folgende Beispiel zeigt, wie Sie den onDeleted Ereignishandler registrieren und dann das CommentDeletedEventArgs Objekt verwenden, um das commentDetails Array des gelöschten Kommentars abzurufen.

Hinweis

Dieses Beispiel funktioniert nur, wenn ein einzelner Kommentar gelöscht wird.

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

Weitere Informationen