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 im Artikel Einfügen von Kommentaren und Notizen in Excel .

In der Excel-JavaScript-API enthält ein Kommentar sowohl den einzelnen ersten Kommentar als auch den verbundenen Diskussionsthread. Sie ist an eine einzelne Zelle gebunden. Jeder, 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.

Kommentare in 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 sind auch auf Arbeitsblattebene zugänglich. Die Beispiele in diesem Artikel funktionieren mit Kommentaren auf Arbeitsmappenebene, können jedoch problemlos 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 benötigt 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 A2ein 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

Von einem Add-In hinzugefügte Kommentare 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();
});

Bearbeiten von Kommentaren

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

Kommentarantworten bearbeiten

Um eine Kommentarantwort zu bearbeiten, legen Sie deren 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();
});

Kommentarantworten löschen

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 verfügt über einen konfigurierbaren booleschen Wert , um anzugeben, resolvedob er aufgelöst wurde. Der Wert true bedeutet, dass der Kommentarthread aufgelöst wird. Der Wert 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 schreibgeschützte resolved Eigenschaft auf. Sein 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})`);
});

Metadaten für Kommentarantworten

Kommentarantworten speichern dieselben Metadatentypen wie der ursprüngliche Kommentar.

Im folgenden Beispiel wird gezeigt, wie die E-Mail-Adresse des Autors, der Name des Autors und das Erstellungsdatum der letzten Kommentarantwort unter A2 angezeigt werden.

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 einem auf, CommentRichContent das eine oder mehrere Erwähnungen enthält, und geben Sie als contentType Parameter anContentType.mention. 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 verkürzte Versionen eines Namens wird später hinzugefügt.

Das folgende Beispiel zeigt einen Kommentar mit einer einzelnen 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. Um auf Kommentarereignisse zu lauschen, registrieren Sie den onAddedKommentarereignishandler , onChangedoder onDeleted . Wenn ein Kommentarereignis erkannt wird, verwenden Sie diesen Ereignishandler, um Daten zum 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 Ergänzungen, Änderungen oder Löschungen gleichzeitig ausgeführt werden. Alle Objekte CommentAddedEventArgs, CommentChangedEventArgs und CommentDeletedEventArgs enthalten Arrays von Kommentar-IDs, um die Ereignisaktionen den Kommentarauflistungen 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 .

Ereignisse zum Hinzufügen von Kommentaren

Das onAdded Ereignis wird ausgelöst, wenn der Kommentarauflistung ein oder mehrere neue Kommentare hinzugefügt werden. Dieses Ereignis wird nicht ausgelöst, wenn Antworten 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.
• Eine Antwort wird einem Kommentarthread 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();
    });
}

Ereignisse zum Löschen von Kommentaren

Das onDeleted Ereignis wird ausgelöst, wenn ein Kommentar aus der Kommentarauflistung gelöscht wird. Nachdem ein Kommentar gelöscht wurde, sind seine 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}`);
    });
}

Siehe auch

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