Uso de anotaciones en el complemento de Word

Incluye contribuciones de la comunidad de:Abdulhadi Jarad

Use anotaciones para mostrar comentarios de escritura directamente en un documento de Word, como instrucciones gramaticales o mejoras sugeridas. Word resalta el texto afectado y puede mostrar un elemento emergente con acciones sugeridas cuando el usuario apunta a la anotación.

En este artículo se muestra cómo:

Registre eventos de anotación para que el complemento pueda responder a las acciones del usuario.
Agregue críticas al párrafo actual.
Inspeccione los detalles de estado de anotación y crítica.
Aplicar o descartar sugerencias y Rechazar una anotación.
Quite las anotaciones cuando ya no las necesite.

Importante

Estas anotaciones no se conservan en el documento. Esto significa que cuando se vuelve a abrir el documento, es necesario volver a generar las anotaciones. Sin embargo, si el usuario acepta los cambios sugeridos, los cambios se conservarán siempre y cuando el usuario los guarde antes de cerrar el documento.

Requisitos previos

Las API de anotación se basan en un servicio que requiere una suscripción a Microsoft 365. Por lo tanto, el uso de esta característica en Word con una licencia de compra única no funcionará. El usuario debe ejecutar Word conectado a una suscripción de Microsoft 365 para que el complemento pueda ejecutar correctamente las API de anotación.

API de anotación clave

A continuación se muestran las API de anotación clave.

Paragraph.insertAnnotations
Paragraph.getAnnotations
Objetos:
- Anotación: representa una anotación.
- AnnotationCollection: representa la colección de anotaciones.
- AnnotationSet: representa el conjunto de anotaciones generadas por el complemento en esta sesión.
- CritiqueAnnotation: representa el tipo de crítica de anotación.
- Crítica: representa los comentarios sobre un área afectada de un párrafo, indicada por un subrayado coloreado.
Eventos de anotación en el documento:

Uso de API de anotación

En las secciones siguientes se muestra cómo trabajar con las API de anotación. Los ejemplos se basan en el ejemplo de código Administrar anotaciones.

Use los comentarios o los resultados de crítica del servicio para administrar las anotaciones dinámicamente en función del contenido del documento del usuario.

Registro de eventos de anotación

En el código siguiente se muestra cómo registrar controladores de eventos. Para obtener más información sobre cómo trabajar con eventos en Word, consulte Trabajo con eventos mediante la API de JavaScript de Word. Para obtener ejemplos de controladores de eventos de anotación, vea las secciones siguientes.

let eventContexts = [];

async function registerEventHandlers() {
  // Registers event handlers.
  await Word.run(async (context) => {
    eventContexts[0] = context.document.onParagraphAdded.add(paragraphChanged);
    eventContexts[1] = context.document.onParagraphChanged.add(paragraphChanged);

    eventContexts[2] = context.document.onAnnotationClicked.add(onClickedHandler);
    eventContexts[3] = context.document.onAnnotationHovered.add(onHoveredHandler);
    eventContexts[4] = context.document.onAnnotationInserted.add(onInsertedHandler);
    eventContexts[5] = context.document.onAnnotationRemoved.add(onRemovedHandler);
    eventContexts[6] = context.document.onAnnotationPopupAction.add(onPopupActionHandler);

    await context.sync();

    console.log("Event handlers registered.");
  });
}

Controlador de eventos onClickedHandler

El código siguiente se ejecuta cuando se produce el evento registrado onAnnotationClicked .

async function onClickedHandler(args: Word.AnnotationClickedEventArgs) {
  // Runs when the registered Document.onAnnotationClicked event occurs.
  await Word.run(async (context) => {
    const annotation: Word.Annotation = context.document.getAnnotationById(args.id);
    annotation.load("critiqueAnnotation");

    await context.sync();

    console.log(`AnnotationClicked: ID ${args.id}:`, annotation.critiqueAnnotation.critique);
  });
}

Controlador de eventos onHoveredHandler

El código siguiente se ejecuta cuando se produce el evento registrado onAnnotationHovered .

async function onHoveredHandler(args: Word.AnnotationHoveredEventArgs) {
  // Runs when the registered Document.onAnnotationHovered event occurs.
  await Word.run(async (context) => {
    const annotation: Word.Annotation = context.document.getAnnotationById(args.id);
    annotation.load("critiqueAnnotation");

    await context.sync();

    console.log(`AnnotationHovered: ID ${args.id}:`, annotation.critiqueAnnotation.critique);
  });
}

Controlador de eventos onInsertedHandler

El código siguiente se ejecuta cuando se produce el evento registrado onAnnotationInserted .

async function onInsertedHandler(args: Word.AnnotationInsertedEventArgs) {
  // Runs when the registered Document.onAnnotationInserted event occurs.
  await Word.run(async (context) => {
    const annotations = [];
    for (let i = 0; i < args.ids.length; i++) {
      let annotation: Word.Annotation = context.document.getAnnotationById(args.ids[i]);
      annotation.load("id,critiqueAnnotation");
      annotations.push(annotation);
    }

    await context.sync();

    for (let annotation of annotations) {
      console.log(`AnnotationInserted: ID ${annotation.id}:`, annotation.critiqueAnnotation.critique);
    }
  });
}

Controlador de eventos onRemovedHandler

El código siguiente se ejecuta cuando se produce el evento registrado onAnnotationRemoved .

async function onRemovedHandler(args: Word.AnnotationRemovedEventArgs) {
  // Runs when the registered Document.onAnnotationRemoved event occurs.
  await Word.run(async (context) => {
    for (let id of args.ids) {
      console.log(`AnnotationRemoved: ID ${id}`);
    }
  });
}

Controlador de eventos onPopupActionHandler

El código siguiente se ejecuta cuando se produce el evento registrado onAnnotationPopupAction .

async function onPopupActionHandler(args: Word.AnnotationPopupActionEventArgs) {
  // Runs when the registered Document.onAnnotationPopupAction event occurs.
  await Word.run(async (context) => {
    let message = `AnnotationPopupAction: ID ${args.id} = `;
    if (args.action === "Accept") {
      message += `Accepted: ${args.critiqueSuggestion}`;
    } else {
      message += "Rejected";
    }

    console.log(message);
  });
}

Insertar anotaciones

En el código siguiente se muestra cómo insertar anotaciones en el párrafo seleccionado.

async function insertAnnotations() {
  // Adds annotations to the selected paragraph.
  await Word.run(async (context) => {
    const paragraph: Word.Paragraph = context.document.getSelection().paragraphs.getFirst();
    const options: Word.CritiquePopupOptions = {
      brandingTextResourceId: "PG.TabLabel",
      subtitleResourceId: "PG.HelpCommand.TipTitle",
      titleResourceId: "PG.HelpCommand.Label",
      suggestions: ["suggestion 1", "suggestion 2", "suggestion 3"]
    };
    const critique1: Word.Critique = {
      colorScheme: Word.CritiqueColorScheme.red,
      start: 1,
      length: 3,
      popupOptions: options
    };
    const critique2: Word.Critique = {
      colorScheme: Word.CritiqueColorScheme.green,
      start: 6,
      length: 1,
      popupOptions: options
    };
    const critique3: Word.Critique = {
      colorScheme: Word.CritiqueColorScheme.blue,
      start: 10,
      length: 3,
      popupOptions: options
    };
    const critique4: Word.Critique = {
      colorScheme: Word.CritiqueColorScheme.lavender,
      start: 14,
      length: 3,
      popupOptions: options
    };
    const critique5: Word.Critique = {
      colorScheme: Word.CritiqueColorScheme.berry,
      start: 18,
      length: 10,
      popupOptions: options
    };
    const annotationSet: Word.AnnotationSet = {
      critiques: [critique1, critique2, critique3, critique4, critique5]
    };

    const annotationIds = paragraph.insertAnnotations(annotationSet);

    await context.sync();

    console.log("Annotations inserted:", annotationIds.value);
  });
}

Obtener anotaciones

En el código siguiente se muestra cómo obtener anotaciones del párrafo seleccionado.

async function getAnnotations() {
  // Gets annotations found in the selected paragraph.
  await Word.run(async (context) => {
    const paragraph: Word.Paragraph = context.document.getSelection().paragraphs.getFirst();
    const annotations: Word.AnnotationCollection = paragraph.getAnnotations();
    annotations.load("id,state,critiqueAnnotation");

    await context.sync();

    console.log("Annotations found:");

    for (let i = 0; i < annotations.items.length; i++) {
      const annotation: Word.Annotation = annotations.items[i];

      console.log(`ID ${annotation.id} - state '${annotation.state}':`, annotation.critiqueAnnotation.critique);
    }
  });
}

Aceptar una anotación

En el código siguiente se muestra cómo aceptar la primera anotación que se encuentra en el párrafo seleccionado.

async function acceptFirst() {
  // Accepts the first annotation found in the selected paragraph.
  await Word.run(async (context) => {
    const paragraph: Word.Paragraph = context.document.getSelection().paragraphs.getFirst();
    const annotations: Word.AnnotationCollection = paragraph.getAnnotations();
    annotations.load("id,state,critiqueAnnotation");

    await context.sync();

    for (let i = 0; i < annotations.items.length; i++) {
      const annotation: Word.Annotation = annotations.items[i];

      if (annotation.state === Word.AnnotationState.created) {
        console.log(`Accepting ID ${annotation.id}...`);
        annotation.critiqueAnnotation.accept();

        await context.sync();
        break;
      }
    }
  });
}

Rechazar una anotación

En el código siguiente se muestra cómo rechazar la última anotación encontrada en el párrafo seleccionado.

async function rejectLast() {
  // Rejects the last annotation found in the selected paragraph.
  await Word.run(async (context) => {
    const paragraph: Word.Paragraph = context.document.getSelection().paragraphs.getFirst();
    const annotations: Word.AnnotationCollection = paragraph.getAnnotations();
    annotations.load("id,state,critiqueAnnotation");

    await context.sync();

    for (let i = annotations.items.length - 1; i >= 0; i--) {
      const annotation: Word.Annotation = annotations.items[i];

      if (annotation.state === Word.AnnotationState.created) {
        console.log(`Rejecting ID ${annotation.id}...`);
        annotation.critiqueAnnotation.reject();

        await context.sync();
        break;
      }
    }
  });
}

Eliminación de anotaciones

En el código siguiente se muestra cómo eliminar todas las anotaciones que se encuentran en el párrafo seleccionado.

async function deleteAnnotations() {
  // Deletes all annotations found in the selected paragraph.
  await Word.run(async (context) => {
    const paragraph: Word.Paragraph = context.document.getSelection().paragraphs.getFirst();
    const annotations: Word.AnnotationCollection = paragraph.getAnnotations();
    annotations.load("id");

    await context.sync();

    const ids = [];
    for (let i = 0; i < annotations.items.length; i++) {
      const annotation: Word.Annotation = annotations.items[i];

      ids.push(annotation.id);
      annotation.delete();
    }

    await context.sync();

    console.log("Annotations deleted:", ids);
  });
}

Anulación del registro de eventos de anotación

En el código siguiente se muestra cómo anular el registro de controladores de eventos mediante los contextos de eventos de los que se realiza el seguimiento en la eventContexts variable .

async function deregisterEventHandlers() {
  // Deregisters event handlers.
  await Word.run(async (context) => {
    for (let i = 0; i < eventContexts.length; i++) {
      await Word.run(eventContexts[i].context, async (context) => {
        eventContexts[i].remove();
      });
    }

    await context.sync();

    eventContexts = [];
    console.log("Removed event handlers.");
  });
}

Vea también

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-05-22