Trabajar con comentarios mediante la API de JavaScript de Excel

En este artículo se describe cómo agregar, leer, modificar y quitar comentarios en un libro con la API de JavaScript de Excel. Puede obtener más información sobre la característica de comentario en el artículo Insertar comentarios y notas en Excel .

En la API de JavaScript de Excel, un comentario incluye tanto el comentario inicial único como la discusión en subprocesos conectada. Está vinculado a una celda individual. Cualquier persona que vea el libro con permisos suficientes puede responder a un comentario. Un objeto Comment almacena esas respuestas como objetos CommentReply . Debe considerar un comentario como un subproceso y que un subproceso debe tener una entrada especial como punto de partida.

Un comentario de Excel, con la etiqueta

La propiedad realiza un seguimiento Workbook.comments de los comentarios dentro de un libro. Esto incluye los comentarios creados por los usuarios y también los comentarios creados por su complemento. La propiedad Workbook.comments es un objeto CommentCollection que tiene una colección de objetos Comentario. Los comentarios también son accesibles en el nivel hoja de cálculo . Los ejemplos de este artículo funcionan con comentarios en el nivel de libro, pero se pueden modificar fácilmente para usar la Worksheet.comments propiedad .

Agregar comentarios

Use el CommentCollection.add método para agregar comentarios a un libro. Este método toma hasta tres parámetros:

  • cellAddress: celda donde se agrega el comentario. Puede ser una cadena o un objeto Range . El rango debe ser una sola celda.
  • content: el contenido del comentario. Use una cadena para los comentarios de texto sin formato. Use un objeto CommentRichContent para los comentarios con menciones.
  • contentType: enumeración ContentType que especifica el tipo de contenido. El valor predeterminado es ContentType.plain.

El siguiente ejemplo de código agrega un comentario a la celda 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();
});

Nota:

Los comentarios agregados por un complemento se atribuyen al usuario actual de ese complemento.

Agregar respuestas de comentario

Un Comment objeto es un subproceso de comentario que contiene cero o más respuestas. Los objetos Comment tienen una propiedad replies, que es un CommentReplyCollection que contiene objetos CommentReply. Para agregar una respuesta a un comentario, utilice el método CommentReplyCollection.add y especificando el texto de la respuesta. Las respuestas se muestran en el orden en el que se agregaron. También se atribuyen al usuario actual del complemento.

El siguiente ejemplo de código agrega una respuesta al primer comentario del libro.

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

Editar comentarios

Para editar un comentario o la respuesta de un comentario, establezca su propiedad Comment.content o la propiedad 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();
});

Editar respuestas de comentario

Para editar una respuesta de comentario, establezca su CommentReply.content propiedad.

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

Eliminar comentarios

Para eliminar un comentario, use el Comment.delete método . Al eliminar un comentario también se eliminan las respuestas asociadas a ese comentario.

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

Eliminar respuestas de comentario

Para eliminar una respuesta de comentario, use el CommentReply.delete método .

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

Resolución de subprocesos de comentario

Un subproceso de comentario tiene un valor booleano configurable, resolved, para indicar si se resuelve. Un valor de true significa que se resuelve el subproceso de comentario. Un valor de false significa que el subproceso de comentario es nuevo o se vuelve a abrir.

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

Las respuestas de comentario tienen una propiedad de solo resolved lectura. Su valor siempre es igual al del resto del subproceso.

Metadatos de comentario

Cada comentario contiene los metadatos de su creación, tales como el autor y la fecha de creación. Se considera que los comentarios creados por su complemento son creados por el usuario actual.

El ejemplo siguiente muestra cómo visualizar el correo electrónico del autor, el nombre del autor y la fecha de creación de un comentario en 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})`);
});

Metadatos de respuesta de comentario

Las respuestas de comentario almacenan los mismos tipos de metadatos que el comentario inicial.

En el ejemplo siguiente se muestra cómo mostrar el correo electrónico del autor, el nombre del autor y la fecha de creación de la última respuesta de comentario en 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();
});

Menciones

Las menciones se usan para etiquetar compañeros en un comentario. Esto les envía notificaciones con el contenido del comentario. El complemento puede crear estas menciones en su nombre.

Los comentarios con menciones deben crearse con objetos CommentRichContent . Llame a CommentCollection.add con un CommentRichContent objeto que contenga una o varias menciones y especifique ContentType.mention como contentType parámetro. La content cadena también debe tener formato para insertar la mención en el texto. El formato de una mención es: <at id="{replyIndex}">{mentionName}</at>.

Nota:

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 muestra un comentario con una sola mención.

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

Eventos de comentario

El complemento puede escuchar las adiciones, cambios y eliminaciones de comentarios. Los eventos de comentario se producen en el CommentCollection objeto . Para escuchar eventos de comentario, registre el onAddedcontrolador de eventos , onChangedo onDeleted comment. Cuando se detecte un evento de comentario, use este controlador de eventos para recuperar datos sobre el comentario agregado, modificado o eliminado. El onChanged evento también controla las adiciones, los cambios y las eliminaciones de la respuesta de comentario.

Cada evento de comentario solo se desencadena una vez cuando se realizan varias adiciones, cambios o eliminaciones al mismo tiempo. Todos los objetos CommentAddedEventArgs, CommentChangedEventArgs y CommentDeletedEventArgs contienen matrices de identificadores de comentario para asignar las acciones del evento a las colecciones de comentarios.

Consulte el artículo Trabajar con eventos mediante la API de JavaScript de Excel para obtener información adicional sobre el registro de controladores de eventos, el control de eventos y la eliminación de controladores de eventos.

Eventos de adición de comentarios

El onAdded evento se desencadena cuando se agregan uno o varios comentarios nuevos a la colección de comentarios. Este evento no se desencadena cuando las respuestas se agregan a un subproceso de comentario (consulte Eventos de cambio de comentario para obtener información sobre los eventos de respuesta de comentario).

En el ejemplo siguiente se muestra cómo registrar el onAdded controlador de eventos y, a continuación, usar el CommentAddedEventArgs objeto para recuperar la commentDetails matriz del comentario agregado.

Nota:

Este ejemplo solo funciona cuando se agrega un solo comentario.

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

Eventos de cambio de comentario

El onChanged evento de comentario se desencadena en los siguientes escenarios.

  • 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 en un subproceso de comentario.

En el ejemplo siguiente se muestra cómo registrar el onChanged controlador de eventos y, a continuación, usar el CommentChangedEventArgs objeto para recuperar la commentDetails matriz del comentario modificado.

Nota:

Este ejemplo solo funciona cuando se cambia un solo comentario.

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

Eventos de eliminación de comentarios

El onDeleted evento se desencadena cuando se elimina un comentario de la colección de comentarios. Una vez eliminado un comentario, sus metadatos ya no están disponibles. El objeto CommentDeletedEventArgs proporciona identificadores de comentario, en caso de que el complemento administre comentarios individuales.

En el ejemplo siguiente se muestra cómo registrar el onDeleted controlador de eventos y, a continuación, usar el CommentDeletedEventArgs objeto para recuperar la commentDetails matriz del comentario eliminado.

Nota:

Este ejemplo solo funciona cuando se elimina un solo comentario.

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

Vea también