Partager via

Utiliser des commentaires à l’aide de l’API JavaScript Excel

  • Article

Cet article explique comment ajouter, lire, modifier et supprimer des commentaires dans un classeur avec l’API JavaScript Excel. Pour en savoir plus sur la fonctionnalité de commentaire, consultez l’article Insérer des commentaires et des notes dans Excel .

Dans l’API JavaScript Excel, un commentaire inclut à la fois le commentaire initial unique et la discussion threadée connectée. Il est lié à une cellule individuelle. Toute personne affichant le classeur avec des autorisations suffisantes peut répondre à un commentaire. Un objet Comment stocke ces réponses sous forme d’objets CommentReply . Vous devez considérer un commentaire comme un thread et qu’un thread doit avoir une entrée spéciale comme point de départ.

Un commentaire Excel, intitulé « Comment » avec deux réponses, intitulé « Comment.replies[0] » et « Comment.replies[1].

Les commentaires d’un classeur sont suivis par la Workbook.comments propriété . Cela inclut les commentaires créés par les utilisateurs ainsi que les commentaires créés par votre complément. La propriété Workbook.comments est un objet CommentCollection qui contient une collection d’objets Comment. Les commentaires sont également accessibles au niveau de la feuille de calcul . Les exemples de cet article fonctionnent avec des commentaires au niveau du classeur, mais ils peuvent être facilement modifiés pour utiliser la Worksheet.comments propriété .

Ajouter des commentaires

Utilisez la CommentCollection.add méthode pour ajouter des commentaires à un classeur. Cette méthode prend jusqu’à trois paramètres :

  • cellAddress: cellule dans laquelle le commentaire est ajouté. Il peut s’agir d’une chaîne ou d’un objet Range . La plage doit être une seule cellule.
  • content: contenu du commentaire. Utilisez une chaîne pour les commentaires en texte brut. Utilisez un objet CommentRichContent pour les commentaires avec des mentions.
  • contentType: énumération ContentType spécifiant le type de contenu. La valeur par défaut est ContentType.plain.

L’exemple de code suivant ajoute un commentaire à la cellule 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();
});

Remarque

Les commentaires ajoutés par un complément sont attribués à l’utilisateur actuel de ce complément.

Ajouter des réponses aux commentaires

Un Comment objet est un thread de commentaires qui contient zéro réponse ou plus. Les objets Comment ont une propriété replies, qui est une collection CommentReplyCollection contenant des objets CommentReply. Pour ajouter une réponse à un commentaire, utilisez la méthode CommentReplyCollection.add, en l’appliquant au texte de la réponse. Les réponses s’affichent dans l’ordre dans lequel elles sont ajoutées. Elles sont également attribuées à l’utilisateur actuel du complément.

L’exemple de code suivant ajoute une réponse au premier commentaire du classeur.

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

Modifier les commentaires

Pour modifier un commentaire ou une réponse à un commentaire, configurez sa propriété Comment.content ou 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();
});

Modifier les réponses aux commentaires

Pour modifier une réponse de commentaire, définissez sa CommentReply.content propriété.

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

Supprimer les commentaires

Pour supprimer un commentaire, utilisez la Comment.delete méthode . La suppression d’un commentaire supprime également les réponses associées à ce commentaire.

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

Supprimer les réponses aux commentaires

Pour supprimer une réponse de commentaire, utilisez la CommentReply.delete méthode .

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

Résoudre les threads de commentaires

Un thread de commentaire a une valeur booléenne configurable, resolved, pour indiquer s’il est résolu. Une valeur de signifie que le thread de true commentaire est résolu. Une valeur de signifie que le thread de false commentaire est nouveau ou rouvert.

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

Les réponses aux commentaires ont une propriété en lecture seule resolved . Sa valeur est toujours égale à celle du reste du thread.

Métadonnées de commentaire

Chaque commentaire contient des métadonnées concernant sa création, notamment l’auteur et la date de création. Les commentaires créés par votre complément sont considérés comme créés par l’utilisateur actuel.

L’exemple suivant montre comment afficher l’adresse e-mail et le nom de l’auteur, ainsi que la date de création d’un commentaire dans la cellule 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})`);
});

Métadonnées de réponse aux commentaires

Les réponses aux commentaires stockent les mêmes types de métadonnées que le commentaire initial.

L’exemple suivant montre comment afficher l’e-mail de l’auteur, le nom de l’auteur et la date de création de la dernière réponse au commentaire sur 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();
});

Mentions

Les mentions sont utilisées pour étiqueter des collègues dans un commentaire. Cela leur envoie des notifications avec le contenu de votre commentaire. Votre complément peut créer ces mentions en votre nom.

Les commentaires avec mentions doivent être créés avec des objets CommentRichContent . Appelez CommentCollection.add avec un CommentRichContent contenant une ou plusieurs mentions et spécifiez ContentType.mention comme contentType paramètre. La content chaîne doit également être mise en forme pour insérer la mention dans le texte. Le format d’une mention est : <at id="{replyIndex}">{mentionName}</at>.

Remarque

Actuellement, seul le nom exact de la mention peut être utilisé comme texte du lien de mention. La prise en charge des versions abrégées d’un nom sera ajoutée ultérieurement.

L’exemple suivant montre un commentaire avec une seule mention.

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

Événements de commentaire

Votre complément peut écouter les ajouts, modifications et suppressions de commentaires. Les événements de commentaire se produisent sur l’objet CommentCollection . Pour écouter les événements de commentaire, inscrivez le onAddedgestionnaire d’événements , onChangedou onDeleted commentaire. Lorsqu’un événement de commentaire est détecté, utilisez ce gestionnaire d’événements pour récupérer des données sur le commentaire ajouté, modifié ou supprimé. L’événement onChanged gère également les ajouts, les modifications et les suppressions de réponse aux commentaires.

Chaque événement de commentaire ne se déclenche qu’une seule fois lorsque plusieurs ajouts, modifications ou suppressions sont effectués en même temps. Tous les objets CommentAddedEventArgs, CommentChangedEventArgs et CommentDeletedEventArgs contiennent des tableaux d’ID de commentaire pour mapper les actions d’événement aux collections de commentaires.

Pour plus d’informations sur l’inscription des gestionnaires d’événements, la gestion des événements et la suppression des gestionnaires d’événements, consultez l’article Utiliser des événements à l’aide de l’API JavaScript Excel .

Événements d’ajout de commentaires

L’événement onAdded est déclenché lorsqu’un ou plusieurs nouveaux commentaires sont ajoutés à la collection de commentaires. Cet événement n’est pas déclenché lorsque des réponses sont ajoutées à un thread de commentaire (consultez Événements de modification de commentaire pour en savoir plus sur les événements de réponse aux commentaires).

L’exemple suivant montre comment inscrire le onAdded gestionnaire d’événements, puis utiliser l’objet CommentAddedEventArgs pour récupérer le commentDetails tableau du commentaire ajouté.

Remarque

Cet exemple fonctionne uniquement lorsqu’un seul commentaire est ajouté.

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

Événements de modification de commentaire

L’événement onChanged de commentaire est déclenché dans les scénarios suivants.

  • Le contenu d’un commentaire est mis à jour.
  • Un thread de commentaire est résolu.
  • Un fil de commentaires est rouvert.
  • Une réponse est ajoutée à un thread de commentaire.
  • Une réponse est mise à jour dans un thread de commentaire.
  • Une réponse est supprimée dans un thread de commentaire.

L’exemple suivant montre comment inscrire le onChanged gestionnaire d’événements, puis utiliser l’objet CommentChangedEventArgs pour récupérer le commentDetails tableau du commentaire modifié.

Remarque

Cet exemple fonctionne uniquement lorsqu’un seul commentaire est modifié.

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

Événements de suppression de commentaires

L’événement onDeleted est déclenché lorsqu’un commentaire est supprimé de la collection de commentaires. Une fois qu’un commentaire a été supprimé, ses métadonnées ne sont plus disponibles. L’objet CommentDeletedEventArgs fournit des ID de commentaire, au cas où votre complément gère les commentaires individuels.

L’exemple suivant montre comment inscrire le onDeleted gestionnaire d’événements, puis utiliser l’objet CommentDeletedEventArgs pour récupérer le commentDetails tableau du commentaire supprimé.

Remarque

Cet exemple fonctionne uniquement lorsqu’un seul commentaire est supprimé.

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

Voir aussi