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 llamadaAdd*()— una anotación obtenida al volver a leerpage.Annotationsdespués es una referencia de objeto distinta. SearchAnnotationText()ySearchAnnotations()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/APautomá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ónencryptsiguen siendo válidas después de que el documento se vuelva a abrir y descifrar.
Problemas comunes
| Problema | Causa | Solución |
|---|---|---|
page.Annotations.find() devuelve undefined para una anotación que acabas de agregar | Buscando un array obsoleto capturado antes de que se añadiera la anotación | Vuelve 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ágina | El texto es generado por la anotación (p. ej., el cuerpo de un FreeText), no transportado en /Contents | Utiliza 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étodo | Descripción |
|---|---|
Annotation | Manejador 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 |
TextAnnotation | Un manejador de notas adhesivas /Text; agrega Icon, Open, Author |
StampAnnotation | Un manejador de sello de goma /Stamp; agrega StampName |
MarkupAnnotation | Un 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.Annotations | Cada 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 |