Gérer les commentaires dans les compléments Excel à l’aide de l’API JavaScript Excel

Cet article explique comment créer des commentaires thread sur des cellules spécifiques, y répondre, les modifier ou les supprimer, résoudre des conversations, lire des métadonnées d’auteur, ajouter des mentions et répondre aux événements de commentaire à l’aide de l’API JavaScript Excel.

Dans l’API JavaScript Excel, un commentaire est un thread qui commence par un commentaire et peut inclure des réponses. Chaque thread est lié à une seule cellule. Si vous avez besoin d’un comportement de note hérité au lieu de discussions à threads, consultez Utiliser des notes à l’aide de l’API JavaScript Excel.

Ce que vous pouvez faire avec les commentaires

Utilisez les API de commentaire Excel pour :

  • Ajoutez un nouveau thread de commentaire à une cellule.
  • Ajouter, modifier et supprimer des réponses dans un thread existant.
  • Résolvez ou rouvrez un thread.
  • Lire les métadonnées d’auteur et de création.
  • Créez des commentaires qui incluent des mentions.
  • Écoutez les événements d’ajout, de modification et de suppression de commentaires.

Comprendre le modèle objet de commentaire

La Workbook.comments propriété suit les commentaires dans un classeur. Cette propriété renvoie un CommentaireCollection qui contient à la fois les commentaires créés par l’utilisateur et les commentaires créés par votre complément. Vous pouvez également accéder aux commentaires au niveau de la feuille de calcul via la Worksheet.comments propriété .

Un objet Comment représente le thread complet d’une seule cellule. Les réponses de ce thread sont stockées en tant qu’objets CommentReply dans la collection du replies commentaire.

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

Ajouter des threads de commentaires

Utilisez CommentCollection.add pour démarrer une conversation à threads sur une cellule. La méthode accepte jusqu’à trois paramètres :

  • cellAddress: cellule dans laquelle vous ajoutez le commentaire. Ce paramètre peut être une chaîne ou un objet Range . La plage doit être une seule cellule.
  • content: texte du commentaire. Utilisez une chaîne pour les commentaires en texte brut. Utilisez un objet CommentRichContent pour les commentaires qui incluent des mentions.
  • contentType: valeur ContentType qui spécifie le type de contenu. La valeur par défaut est ContentType.plain.

L’exemple suivant démarre un thread de révision sur la cellule A2. Notez que les commentaires créés par votre complément sont attribués à l’utilisateur actuel.

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

Remarque

Une InvalidArgument erreur est générée si la plage contient plusieurs cellules.

Ajouter des réponses à un thread de commentaire

Utilisez CommentReplyCollection.add lorsque votre complément doit poursuivre une discussion existante. Les réponses sont affichées dans l’ordre dans lequel elles sont ajoutées et sont également attribuées à l’utilisateur actuel.

L’exemple suivant ajoute une réponse au thread de la cellule A2.

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

Modifier les threads de commentaires

Mettez à jour Comment.content pour modifier la première entrée d’un thread. Mettez à jour CommentReply.content pour modifier une réponse spécifique.

L’exemple suivant met à jour le commentaire principal sur la cellule A2.

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

Modifier une réponse

Utilisez ce modèle lorsque votre complément doit réviser une réponse antérieure dans le thread.

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

Supprimer des threads de commentaires

Utilisez Comment.delete() pour supprimer un thread entier d’une cellule. La suppression d’un commentaire supprime également toutes les réponses de ce thread.

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

Supprimer une réponse

Utilisez CommentReply.delete() lorsque vous devez supprimer une seule réponse, mais conserver le reste du thread.

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

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

Résoudre et rouvrir les threads de commentaires

Utilisez la Comment.resolved propriété pour déterminer si une discussion a toujours besoin d’attention. Définissez la valeur true sur pour résoudre le thread ou false pour le rouvrir. CommentReply.resolved est en lecture seule et correspond toujours à l’état du thread parent.

L’exemple suivant résout le thread sur la cellule A2.

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

Lire les métadonnées de commentaire

Chaque commentaire stocke des métadonnées telles que l’auteur et la date de création. Les commentaires créés par votre complément sont créés par l’utilisateur actuel.

L’exemple suivant enregistre l’e-mail de l’auteur, le nom de l’auteur et la date de création du commentaire sur la cellule A2.

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

Lire les métadonnées de réponse

Les réponses stockent les mêmes métadonnées que le commentaire initial. L’exemple suivant obtient la dernière réponse dans le thread sur la cellule A2 et enregistre ses informations d’auteur.

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

Mentionner les utilisateurs

Utilisez des mentions lorsque votre complément doit étiqueter un collègue dans un commentaire et déclencher une notification par e-mail. Pour créer un commentaire avec des mentions, appelez CommentCollection.add avec un objet CommentRichContent et définissez le paramètre sur contentTypeContentType.mention.

Mettez en forme chaque mention dans la richContent chaîne en tant que <at id="{replyIndex}">{mentionName}</at>.

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

L’exemple suivant ajoute un commentaire avec une seule mention à la cellule A1.

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

Gérer les événements de commentaire

Utilisez des événements de commentaire lorsque votre complément doit réagir aux discussions lorsque les utilisateurs mettent à jour un classeur. Les événements de commentaire se produisent sur l’objet CommentCollection .

Inscrire des gestionnaires pour :

  • onAdded lorsqu’un thread de commentaire est créé.
  • onChanged lorsqu’un commentaire ou une réponse est ajouté, modifié, supprimé, résolu ou rouvert.
  • onDeleted lorsqu’un thread de commentaire est supprimé.

Si une opération affecte plusieurs commentaires, les arguments d’événement contiennent plusieurs éléments dans commentDetails. Les exemples suivants utilisent le premier élément uniquement pour plus de clarté. Pour obtenir des conseils généraux sur les événements, consultez Utiliser des événements à l’aide de l’API JavaScript Excel.

Gérer les événements d’ajout de commentaire

L’événement onAdded se déclenche lorsqu’un ou plusieurs commentaires sont ajoutés à la collection. Il ne se déclenche pas lorsqu’une réponse est ajoutée à un thread existant.

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

Gérer les événements de modification de commentaire

L’événement onChanged se déclenche lorsque :

  • 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 d’un thread de commentaire.
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}`);
    });
}

Gérer les événements de suppression de commentaires

L’événement onDeleted se déclenche lorsqu’un commentaire est supprimé de la collection. Une fois qu’un commentaire est supprimé, ses métadonnées ne sont plus disponibles. Utilisez les ID dans CommentDeletedEventArgs.commentDetails si votre complément doit effectuer le suivi des threads supprimés.

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

Voir aussi

  • Last updated on