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łanie Add*() — adnotacja uzyskana przez ponowne odczytanie page.Annotations później jest innym odniesieniem do obiektu.
  • SearchAnnotationText() i SearchAnnotations() 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 /AP wyglą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ą encrypt pozostają ważne po ponownym otwarciu i odszyfrowaniu dokumentu.

Typowe problemy

ProblemPrzyczynaNaprawa
page.Annotations.find() zwraca undefined dla adnotacji, którą właśnie dodałeśWyszukiwanie przestarzałej tablicy przechwyconej przed dodaniem adnotacjiPonownie 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 stronieTekst jest rysowany przez adnotację (np. ciało FreeText), a nie przenoszony w /ContentsUż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/MetodaOpis
AnnotationPodstawowy 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
TextAnnotationUchwyt /Text w formie karteczki samoprzylepnej; dodaje Icon, Open, Author
StampAnnotationUchwyt /Stamp w formie stempla gumowego; dodaje StampName
MarkupAnnotationUchwyt 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.AnnotationsWszystkie 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

Zobacz także

 Polski