Administración de comentarios en complementos de Excel mediante la API de JavaScript de Excel

En este artículo se muestra cómo crear comentarios en subprocesos en celdas específicas, responder a ellas, editarlas o eliminarlas, resolver conversaciones, leer metadatos de autor, agregar menciones y responder a eventos de comentario mediante la API de JavaScript de Excel.

En la API de JavaScript de Excel, un comentario es un subproceso que comienza con un comentario y puede incluir respuestas. Cada subproceso está asociado a una sola celda. Si necesita un comportamiento de nota heredado en lugar de discusiones en subprocesos, consulte Trabajar con notas mediante la API de JavaScript de Excel.

Qué puede hacer con los comentarios

Use las API de comentarios de Excel para:

  • Agregue un nuevo subproceso de comentario a una celda.
  • Agregue, edite y elimine respuestas en un subproceso existente.
  • Resuelva o vuelva a abrir un subproceso.
  • Lea los metadatos de creación y autor.
  • Cree comentarios que incluyan menciones.
  • Escuche los eventos de adición, cambio y eliminación de comentarios.

Descripción del modelo de objetos de comentario

La Workbook.comments propiedad realiza un seguimiento de los comentarios de un libro. Esta propiedad devuelve un CommentCollection que contiene comentarios creados por el usuario y comentarios creados por el complemento. También puede acceder a los comentarios en el nivel Hoja de cálculo a través de la Worksheet.comments propiedad .

Un objeto Comment representa el subproceso completo de una sola celda. Las respuestas de ese subproceso se almacenan como objetos CommentReply en la colección del replies comentario.

Un comentario de Excel, con la etiqueta

Agregar subprocesos de comentario

Use CommentCollection.add para iniciar una conversación encadenada en una celda. El método acepta hasta tres parámetros:

  • cellAddress: celda donde se agrega el comentario. Este parámetro puede ser una cadena o un objeto Range . El rango debe ser una sola celda.
  • content: texto del comentario. Use una cadena para los comentarios de texto sin formato. Use un objeto CommentRichContent para los comentarios que incluyan menciones.
  • contentType: valor ContentType que especifica el tipo de contenido. El valor predeterminado es ContentType.plain.

En el ejemplo siguiente se inicia un subproceso de revisión en la celda A2. Tenga en cuenta que los comentarios que crea el complemento se atribuyen al usuario actual.

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

Nota:

Se produce un InvalidArgument error si el rango contiene varias celdas.

Adición de respuestas a un subproceso de comentario

Use CommentReplyCollection.add cuando el complemento necesite continuar con una discusión existente. Las respuestas se muestran en el orden en que se agregan y también se atribuyen al usuario actual.

En el ejemplo siguiente se agrega una respuesta al subproceso de la celda A2.

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

Editar subprocesos de comentario

Actualice Comment.content para cambiar la primera entrada de un subproceso. Actualice CommentReply.content para cambiar una respuesta específica.

En el ejemplo siguiente se actualiza el comentario principal en la celda 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();
});

Edición de una respuesta

Use este patrón cuando el complemento necesite revisar una respuesta anterior en el subproceso.

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

Eliminar subprocesos de comentario

Use Comment.delete() para quitar un subproceso completo de una celda. Al eliminar un comentario también se eliminan todas las respuestas de ese subproceso.

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

Eliminación de una respuesta

Use CommentReply.delete() cuando necesite quitar una única respuesta, pero mantenga el resto del subproceso.

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

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

Resolución y reapertura de subprocesos de comentarios

Use la Comment.resolved propiedad para realizar un seguimiento de si una discusión todavía necesita atención. Establezca el valor true en para resolver el subproceso o para false volver a abrirlo. CommentReply.resolved es de solo lectura y siempre coincide con el estado del subproceso primario.

En el ejemplo siguiente se resuelve el subproceso de la celda A2.

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

Leer metadatos de comentario

Cada comentario almacena metadatos como el autor y la fecha de creación. El usuario actual crea los comentarios creados por el complemento.

En el ejemplo siguiente se registra el correo electrónico del autor, el nombre del autor y la fecha de creación del comentario en la celda 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})`);
});

Leer metadatos de respuesta

Las respuestas almacenan los mismos metadatos que el comentario inicial. En el ejemplo siguiente se obtiene la respuesta más reciente en el subproceso de la celda A2 y se registra su información de autor.

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

Mencione a los usuarios

Use menciones cuando el complemento necesite etiquetar a un compañero en un comentario y desencadenar una notificación por correo electrónico. Para crear un comentario con menciones, llame a CommentCollection.add con un objeto CommentRichContent y establezca el contentType parámetro en ContentType.mention.

Dé formato a cada mención de la richContent cadena como <at id="{replyIndex}">{mentionName}</at>.

Actualmente, solo se puede usar el nombre exacto de la mención como texto del vínculo de mención. La compatibilidad con versiones abreviadas de un nombre se agregará más adelante.

En el ejemplo siguiente se agrega un comentario con una sola mención a la celda 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();
});

Controlar eventos de comentario

Use eventos de comentario cuando el complemento necesite reaccionar a las discusiones a medida que los usuarios actualizan un libro. Los eventos de comentario se producen en el CommentCollection objeto .

Registre controladores para:

  • onAdded cuando se crea un nuevo subproceso de comentario.
  • onChanged cuando se agrega, edita, elimina, resuelve o vuelve a abrir un comentario o respuesta.
  • onDeleted cuando se elimina un subproceso de comentario.

Si una operación afecta a varios comentarios, los argumentos de evento contienen varios elementos en commentDetails. En los ejemplos siguientes se usa el primer elemento solo para mayor claridad. Para obtener instrucciones generales sobre eventos, consulte Trabajar con eventos mediante la API de JavaScript de Excel.

Controlar eventos de adición de comentarios

El onAdded evento se desencadena cuando se agregan uno o varios comentarios a la colección. No se desencadena cuando se agrega una respuesta a un subproceso existente.

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

Controlar eventos de cambio de comentario

El onChanged evento se desencadena cuando:

  • Se actualiza el contenido de un comentario.
  • Se resuelve un subproceso de comentario.
  • Se vuelve a abrir un subproceso de comentario.
  • Se agrega una respuesta a un subproceso de comentario.
  • Una respuesta se actualiza en un subproceso de comentario.
  • Una respuesta se elimina de un subproceso de comentario.
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}`);
    });
}

Controlar eventos de eliminación de comentarios

El onDeleted evento se desencadena cuando se elimina un comentario de la colección. Una vez eliminado un comentario, sus metadatos ya no están disponibles. Use los identificadores en CommentDeletedEventArgs.commentDetails si el complemento necesita realizar un seguimiento de los subprocesos eliminados.

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

Vea también

  • Last updated on