Annotations
Adnotacje
Ta strona opisuje tworzenie, odczytywanie, wyszukiwanie i spłaszczanie adnotacji PDF. Page udostępnia jedną metodę Add*() dla każdego podtypu adnotacji, zwracając żywy uchwyt Annotation; klasa bazowa Annotation oraz jej podtypy (TextAnnotation, StampAnnotation, MarkupAnnotation i inne) udostępniają właściwości adnotacji do odczytu i edycji.
Tworzenie adnotacji typu markup, notatki i linku
Cztery metody tekstowego markup — Page.AddHighlight(), Page.AddUnderline(), Page.AddSquiggly() i Page.AddStrikeOut() — przyjmują tablicę quads (/QuadPoints) i zwracają MarkupAnnotation. Page.AddLink() tworzy klikalny obszar z URI lub akcją wewnętrzną, a Page.AddTextNote() dodaje ikonę notatki samoprzylepnej, która otwiera wyskakujące okno z tekstem contents, zwracając 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 udostępnia także metody kształtu i odręczne — AddSquare(), AddCircle(), AddLine(), AddPolygon(), AddPolyline(), AddInk(), AddFreeText(), AddCaret() i AddStamp() — każda zwraca odpowiedni uchwyt adnotacji dla tego podtypu, automatycznie generując jej wygląd /AP.
Odczytywanie i listowanie adnotacji
page.Annotations jest tablicą wszystkich Annotation na stronie. Każda adnotacja, niezależnie od podtypu, udostępnia Subtype, Rect, Color, Contents, Name, Layer, ModDate, Flags, Print, Hidden i Opacity; podtypy dodają własne pola, takie jak StampAnnotation.StampName lub MarkupAnnotation.QuadPoints.
const freeText = page.Annotations.find((a) => a.Subtype === 'FreeText');
if (freeText) {
freeText.Contents = 'Updated note text';
}Wyszukiwanie tekstu adnotacji
Page.SearchAnnotationText() and Page.SearchAnnotations() są celowo rozłączne. SearchAnnotationText() znajduje dopasowania w tekście i adnotację carries zamiast rysować — notatki /Contents, jej autora (/T), lub jej tematu (/Subj) — i zwraca AnnotationTextMatch[] ({ annot, key, value, text }). SearchAnnotations() znajduje dopasowania w tekście i adnotację draws, takie jak a FreeText’s widoczne słowa, i zwraca 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');Spłaszczanie adnotacji
Annotation.Flatten() wbudowuje wygląd /AP adnotacji bezpośrednio do strumienia zawartości strony w miejscu /Rect, a następnie usuwa go z /Annots. Wynik to trwała, statyczna treść — już nie oddzielna adnotacja, którą widz może kliknąć, edytować lub ukryć.
const note = page.AddTextNote({
rect: [72, 660, 92, 680], icon: 'Comment', contents: 'Reviewed and approved.',
});
note.Flatten();Wskazówki i najlepsze praktyki
- Wywołaj
Flatten()na obiekcie zwróconym bezpośrednio przez wywołanieAdd*()— adnotacja uzyskana przez ponowne odczytaniepage.Annotationspóźniej jest innym odniesieniem do obiektu. SearchAnnotationText()iSearchAnnotations()obejmują różny tekst: uruchom oba, jeśli potrzebujesz znaleźć frazę, niezależnie od tego, czy została wpisana w notatkę, czy narysowana na stronie.- Cztery metody znaczników (
AddHighlight,AddUnderline,AddSquiggly,AddStrikeOut) generują ich/APwygląd automatycznie — nie jest wymagane ręczne rysowanie w strumieniu zawartości. - Szyfrowanie przetrwa jedną podróż w obie strony: adnotacje dodane przed
Document.Save()z opcjąencryptpozostają ważne po ponownym otwarciu i odszyfrowaniu dokumentu.
Typowe problemy
| Problem | Przyczyna | Naprawa |
|---|---|---|
page.Annotations.find() zwraca undefined dla adnotacji, którą właśnie dodałeś | Wyszukiwanie przestarzałej tablicy przechwyconej przed dodaniem adnotacji | Ponownie odczytaj page.Annotations po wywołaniu Add*(), albo użyj uchwytu zwróconego przez wywołanie bezpośrednio |
SearchAnnotationText() nie znajduje nic dla tekstu widocznego na stronie | Tekst jest rysowany przez adnotację (np. ciało FreeText), a nie przenoszony w /Contents | Użyj SearchAnnotations() zamiast — pasuje do rysowanego tekstu |
Adnotacja nadal wydaje się edytowalna po Flatten() | Flatten() został wywołany na kopii zamiast na uchwycie zwróconym przez Add*() | Wywołaj Flatten() na obiekcie zwróconym bezpośrednio przez metodę tworzącą |
FAQ
Jaka jest różnica między SearchAnnotationText a SearchAnnotations?
SearchAnnotationText() dopasowuje tekst adnotacji carries — /Contents, /T (autor), lub /Subj — na przykład ciało notatki samoprzylepnej. SearchAnnotations() dopasowuje tekst do adnotacji draws na stronie, na przykład FreeText’s widoczne słowa. Oba są rozłączne: dopasowanie w jednym nie pojawi się w drugim.
Jak uczynić adnotację trwałą i nieinteraktywną?
Wywołaj Flatten() na uchwycie Annotation zwróconym przez metodę Add*(), która go utworzyła. To zapisuje jego wygląd w strumieniu zawartości strony i usuwa go z /Annots.
Jakie podtypy adnotacji są obsługiwane?
Page udostępnia metody tworzenia oznaczeń tekstowych (AddHighlight, AddUnderline, AddSquiggly, AddStrikeOut), notatek i adnotacji (AddTextNote, AddFreeText, AddCaret), linków (AddLink), kształtów (AddSquare, AddCircle, AddLine, AddPolygon, AddPolyline), odręcznego tuszu (AddInk), stempli (AddStamp) oraz załączników plików (AddFileAttachment).
Jak mogę wyświetlić wszystkie adnotacje już znajdujące się na stronie?
Odczytaj page.Annotations, tablicę uchwytów Annotation. Każdy udostępnia Subtype, Rect, Color, Contents oraz inne wspólne właściwości, dzięki czemu możesz filtrować lub przeglądać je przy użyciu standardowych metod tablicowych.
API Reference Podsumowanie
| Klasa/Metoda | Opis |
|---|---|
Annotation | Podstawowy uchwyt nad dowolną adnotacją; udostępnia Subtype, Rect, Color, Contents, Name, Flags, Print, Hidden, Opacity |
Annotation.Flatten() | Wbuduj wygląd adnotacji w statyczną treść strony |
TextAnnotation | Uchwyt /Text w formie karteczki samoprzylepnej; dodaje Icon, Open, Author |
StampAnnotation | Uchwyt /Stamp w formie stempla gumowego; dodaje StampName |
MarkupAnnotation | Uchwyt znakowania tekstu (Highlight/Underline/StrikeOut/Squiggly); dodaje MarkupType, QuadPoints |
Page.AddHighlight() / Page.AddUnderline() / Page.AddStrikeOut() / Page.AddSquiggly() | Utwórz adnotację tekstową nad /QuadPoints |
Page.AddTextNote() | Utwórz adnotację w formie notatki samoprzylepnej |
Page.AddLink() | Utwórz klikalny link z URI lub akcją wewnętrzną |
Page.Annotations | Wszystkie Annotation na stronie, jako tablica |
Page.SearchAnnotationText() | Znajdź tekst, który zawiera adnotacja (/Contents, /T, /Subj) |
Page.SearchAnnotations() | Znajdź tekst, który adnotacja rysuje na stronie |