Annotations

Anotaciones

Esta página cubre la creación, lectura, búsqueda y aplanado de anotaciones PDF. Page expone un método Add*() por subtipo de anotación, cada uno devolviendo un manejador Annotation en vivo; la clase base Annotation y sus subtipos (TextAnnotation, StampAnnotation, MarkupAnnotation y otros) exponen las propiedades de la anotación para lectura y edición.


Creación de anotaciones de marcado, nota y enlace

Los cuatro métodos de marcado de texto — Page.AddHighlight(), Page.AddUnderline(), Page.AddSquiggly() y Page.AddStrikeOut() — aceptan una matriz quads (/QuadPoints) y devuelven un MarkupAnnotation. Page.AddLink() crea una región clicable con un URI o acción interna, y Page.AddTextNote() añade un ícono de nota adhesiva que abre una ventana emergente con texto contents, devolviendo un TextAnnotation.

page.AddHighlight({ quads, color: [1, 1, 0], contents: 'Yellow highlight' });
page.AddUnderline({ quads, color: [0, 0, 1] });
page.AddStrikeOut({ quads, color: [1, 0, 0] });

page.AddLink({
  rect: [100, 700, 220, 716],
  action: { type: 'uri', uri: 'https://example.com' },
  border: 0,
});

page.AddTextNote({
  rect: [x, y, x + 20, y + 20], icon: 'Note', author: 'Reviewer',
  contents: 'This is a sticky-note annotation.',
});

Page también expone métodos de forma y a mano alzada — AddSquare(), AddCircle(), AddLine(), AddPolygon(), AddPolyline(), AddInk(), AddFreeText(), AddCaret() y AddStamp() — cada uno devolviendo el manejador de anotación correspondiente a ese subtipo, generando su apariencia /AP automáticamente.


Lectura y listado de anotaciones

page.Annotations es una matriz de cada Annotation en la página. Cada anotación, sin importar el subtipo, expone Subtype, Rect, Color, Contents, Name, Layer, ModDate, Flags, Print, Hidden y Opacity; los subtipos añaden sus propios campos, como StampAnnotation.StampName o MarkupAnnotation.QuadPoints.

const freeText = page.Annotations.find((a) => a.Subtype === 'FreeText');
if (freeText) {
  freeText.Contents = 'Updated note text';
}

Buscar texto de anotación

Page.SearchAnnotationText() and Page.SearchAnnotations() están deliberadamente disjuntos. SearchAnnotationText() encuentra coincidencias en el texto y una anotación carries en lugar de dibujar — de una nota’s /Contents, su autor (/T), o su tema (/Subj) — y devuelve AnnotationTextMatch[] ({ annot, key, value, text }). SearchAnnotations() encuentra coincidencias en el texto y una anotación draws, como un FreeText’s palabras visibles y devuelve AnnotationMatch[] ({ annot, text, quads }).

// A sticky note's /Contents text — found by SearchAnnotationText, not SearchAnnotations.
const textHits = page.SearchAnnotationText('body secret');
console.log(textHits[0].key, textHits[0].value); // 'Contents' 'body secret'

// A FreeText's rendered words — found by SearchAnnotations, not SearchAnnotationText.
const drawnHits = page.SearchAnnotations('bravo');

Aplanar anotaciones

Annotation.Flatten() incrusta la apariencia /AP de una anotación directamente en el flujo de contenido de la página en su /Rect, y luego la elimina de /Annots. El resultado es contenido permanente y estático — ya no una anotación distinta que el visor pueda hacer clic, editar o ocultar.

const note = page.AddTextNote({
  rect: [72, 660, 92, 680], icon: 'Comment', contents: 'Reviewed and approved.',
});
note.Flatten();

Consejos y mejores prácticas

  • Llame a Flatten() sobre el objeto devuelto directamente por la llamada Add*() — una anotación obtenida al volver a leer page.Annotations después es una referencia de objeto distinta.
  • SearchAnnotationText() y SearchAnnotations() cubren texto diferente: ejecute ambos si necesita encontrar una frase sin importar si se escribió en una nota o se dibujó en la página.
  • Los cuatro métodos de marcado (AddHighlight, AddUnderline, AddSquiggly, AddStrikeOut) generan su apariencia /AP automáticamente — no se requiere dibujo manual del flujo de contenido.
  • El cifrado sobrevive a un viaje de ida y vuelta: las anotaciones añadidas antes de Document.Save() con una opción encrypt siguen siendo válidas después de que el documento se vuelva a abrir y descifrar.

Problemas comunes

ProblemaCausaSolución
page.Annotations.find() devuelve undefined para una anotación que acabas de agregarBuscando un array obsoleto capturado antes de que se añadiera la anotaciónVuelve a leer page.Annotations después de la llamada Add*(), o usa directamente el manejador que devolvió la llamada
SearchAnnotationText() no encuentra nada para el texto visible en la páginaEl texto es generado por la anotación (p. ej., el cuerpo de un FreeText), no transportado en /ContentsUtiliza SearchAnnotations() en su lugar — coincide con el texto generado
La anotación sigue apareciendo editable después de Flatten()Flatten() se llamó sobre una copia en lugar del manejador que devolvió Add*()Llama a Flatten() sobre el objeto devuelto directamente por el método de creación

FAQ

¿Cuál es la diferencia entre SearchAnnotationText y SearchAnnotations?

SearchAnnotationText() coincide con el texto de una anotación carries — /Contents, /T (autor), o /Subj — como el cuerpo de una nota adhesiva. SearchAnnotations() coincide con el texto de una anotación draws en la página, como un FreeTextpalabras visibles. Los dos son disjuntos: una coincidencia en uno no aparecerá en el otro.

¿Cómo hago que una anotación sea permanente y no interactiva?

Llama a Flatten() sobre el identificador Annotation devuelto por el método Add*() que lo creó. Esto incorpora su apariencia en el flujo de contenido de la página y lo elimina de /Annots.

¿Qué subtipos de anotación son compatibles?

Page expone métodos de creación para marcado de texto (AddHighlight, AddUnderline, AddSquiggly, AddStrikeOut), notas y anotaciones (AddTextNote, AddFreeText, AddCaret), enlaces (AddLink), formas (AddSquare, AddCircle, AddLine, AddPolygon, AddPolyline), tinta a mano alzada (AddInk), sellos (AddStamp), y archivos adjuntos (AddFileAttachment).

¿Cómo puedo enumerar todas las anotaciones que ya existen en una página?

Lea page.Annotations, una matriz de manejadores de Annotation. Cada uno expone Subtype, Rect, Color, Contents y las demás propiedades compartidas, de modo que pueda filtrarlos o inspeccionarlos con los métodos estándar de matrices.


API Reference Resumen

Clase/MétodoDescripción
AnnotationManejador base sobre cualquier anotación; expone Subtype, Rect, Color, Contents, Name, Flags, Print, Hidden, Opacity
Annotation.Flatten()Incorpora la apariencia de la anotación en el contenido estático de la página
TextAnnotationUn manejador de notas adhesivas /Text; agrega Icon, Open, Author
StampAnnotationUn manejador de sello de goma /Stamp; agrega StampName
MarkupAnnotationUn manejador de marcado de texto (Highlight/Underline/StrikeOut/Squiggly); agrega MarkupType, QuadPoints
Page.AddHighlight() / Page.AddUnderline() / Page.AddStrikeOut() / Page.AddSquiggly()Crear una anotación de marcado de texto sobre /QuadPoints
Page.AddTextNote()Crear una anotación de nota adhesiva
Page.AddLink()Crear un enlace clicable con una URI o acción interna
Page.AnnotationsCada Annotation en la página, como un array
Page.SearchAnnotationText()Encontrar el texto que lleva una anotación (/Contents, /T, /Subj)
Page.SearchAnnotations()Buscar el texto que una anotación dibuja en la página

Ver también

 Español