Wstęp

Wpis introductory post krótko omawia adnotacje: podświetlenia, podkreślenia, notatki samoprzylepne i pieczątki, dodawane przy pomocy Page.AddHighlight(), Page.AddUnderline() i podobnych metod. To mały fragment tego, co faktycznie obsługuje Page — galeria adnotacji w tej bibliotece obejmuje znacznikowanie, kształty odręczne, linki z prawdziwą nawigacją i akcjami przesyłania formularzy oraz wyszukiwanie, wszystko dostępne bezpośrednio z Page.

Ten wpis przechodzi przez pozostałą część tej powierzchni: metody adnotacji kształtów i odręcznych, co faktycznie może zrobić akcja adnotacji Link, oraz dwa różne sposoby wyszukiwania treści adnotacji w zależności od tego, czy szukany tekst znajduje się w wyglądzie adnotacji, czy w jej /Contents komentarzu.

Każda metoda adnotacji zwraca typizowany uchwyt ograniczony do adnotacji, którą właśnie utworzyła, a każda adnotacja na stronie jest później odczytywalna za pomocą page.Annotations.

Co zawiera

Adnotacje markup

Page.AddHighlight(), Page.AddUnderline(), Page.AddSquiggly() i Page.AddStrikeOut() przyjmują ten sam zestaw opcji — zestaw quad points oznaczających region tekstu oraz opcjonalny kolor — i wszystkie cztery zwracają MarkupAnnotation. Quad points są zazwyczaj wyprowadzane z wyszukiwania tekstu lub z known text rectangle.

const markup = (body: [number, number, number, number], sample: string,
  add: (quads: number[]) => void): void => {
  const yMid = (body[1] + body[3]) / 2 - 6;
  const textRect: [number, number, number, number] = [body[0] + 4, yMid, body[2] - 4, yMid + 16];
  page.AddText(sample, textRect[0], textRect[1], { fontSize: 12 });
  add(rectToQuads(textRect));
};

markup(cardBody, 'Highlight this phrase', (quads) =>
  page.AddHighlight({ quads, color: [1, 1, 0], contents: 'Yellow highlight' }));
markup(cardBody, 'Underline this phrase', (quads) =>
  page.AddUnderline({ quads, color: [0, 0, 1] }));
markup(cardBody, 'Squiggle this phrase', (quads) =>
  page.AddSquiggly({ quads, color: [1, 0.5, 0] }));
markup(cardBody, 'Strike this phrase out', (quads) =>
  page.AddStrikeOut({ quads, color: [1, 0, 0] }));

Notatki i samodzielny tekst

Page.AddTextNote() dodaje klasyczną ikonę notatki samoprzylepnej, która po kliknięciu otwiera wyskakujące okienko komentarza, zwracając TextAnnotation. Page.AddFreeText() zamiast tego rysuje swój tekst bezpośrednio na stronie wewnątrz ramki, z własnym rozmiarem czcionki, wyrównaniem i kolorem wypełnienia — przydatne dla uwag, które powinny być widoczne bez otwierania czegokolwiek.

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

page.AddFreeText({
  rect: [220, 60, 520, 96],
  contents: 'FreeText sample', fontSize: 10, align: 'center',
  fill: [1, 1, 0.8], width: 1,
});

Kształty i odręczne pióro

Page.AddSquare() i Page.AddCircle() rysują obramowany prostokąt lub elipsę, każda z opcjonalnym wypełnieniem wnętrza. Page.AddLine() rysuje prostą linię między dwoma punktami, z niezależnie wybieralnymi stylami grotu strzałki (startEnding/endEnding, np. 'OpenArrow'/'ClosedArrow') na każdym końcu. Page.AddPolygon() i Page.AddPolyline() rysują zamknięte i otwarte wielopunktowe kształty z płaskiej listy współrzędnych, a Page.AddInk() zapisuje jeden lub więcej odręcznych pociągnięć piórem jako paths list punktów.

page.AddSquare({ rect: [50, 400, 130, 435], color: [0.8, 0, 0], fill: [1, 1, 0.5], width: 2 });
page.AddCircle({ rect: [150, 400, 230, 435], color: [0, 0.5, 0], width: 2 });

page.AddLine({
  line: [260, 417, 420, 417],
  color: [0, 0, 0.7], width: 2,
  startEnding: 'OpenArrow', endEnding: 'ClosedArrow',
});

const stroke: number[] = [];
[-8, 6, -4, 10, -2, 8, -6].forEach((dy, i) => stroke.push(440 + i * 12, 417 + dy));
page.AddInk({ paths: [stroke], color: [0.6, 0, 0.6], width: 2 });

Linki i ich działania

Page.AddLink() zwraca LinkAnnotation, którego action decyduje, co się stanie po kliknięciu: { type: 'uri', uri: '...' } otwiera zewnętrzny URL, { type: 'goto', page: N } przeskakuje do strony w tym samym dokumencie, a { type: 'submit', url: '...', format: 'html' } wysyła bieżące wartości pól formularza do endpointu. Numer strony goto poza zakresem lub nieprawidłowy obiekt akcji jest odrzucany w czasie tworzenia, a nie cicho akceptowany.

const uriLink = page.AddLink({
  rect: [10, 10, 100, 30], action: { type: 'uri', uri: 'https://example.com' },
});

const gotoLink = page.AddLink({
  rect: [10, 40, 100, 60], action: { type: 'goto', page: 2 },
});

const submitLink = page.AddLink({
  rect: [10, 70, 100, 90],
  action: { type: 'submit', url: 'https://example.com/post', format: 'html' },
});

// page.AddLink({ rect: [...], action: { type: 'goto', page: 99 } }) throws RangeError
// when 99 is out of range for the document.

Wyszukiwanie treści adnotacji

Dwie różne metody przeszukują tekst adnotacji i są celowo rozłączne: Page.SearchAnnotations() przeszukuje tekst własnego wyglądu adnotacji rysuje — widoczna etykieta na FreeText lub stemplu, na przykład — podczas gdy Page.SearchAnnotationText() przeszukuje tekst zawarty w adnotacji /Contents wpisie, takim jak treść komentarza notatki samoprzylepnej. Dopasowanie w jednym nie oznacza dopasowania w drugim.

page.SearchAnnotations('bravo');          // finds it if the annotation's drawn appearance contains it
page.SearchAnnotationText('bravo');       // finds it if the annotation's /Contents comment contains it

Adnotacje, które nie są już potrzebne, można usunąć bezpośrednio za pomocą Page.RemoveAnnotation(), przekazując zarówno uchwyt adnotacji, jak i jej podstawowy słownik.

Szybki start

Zainstaluj pakiet, a następnie dodaj podświetlenie, link i notatkę samoprzylepną do istniejącej strony:

git clone https://github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-TypeScript.git
cd Aspose.PDF-FOSS-for-TypeScript
npm install
npm run build
import { Document } from '@asposefoss/pdf';

const doc = Document.OpenFile('input.pdf');
const page = doc.Pages[0];

page.AddHighlight({ quads: [72, 700, 300, 700, 72, 715, 300, 715], color: [1, 1, 0] });

page.AddLink({
  rect: [72, 670, 200, 690], action: { type: 'uri', uri: 'https://example.com' },
});

page.AddTextNote({
  rect: [320, 670, 340, 690], icon: 'Note', author: 'Reviewer',
  contents: 'Please double-check this figure.',
});

doc.WriteTo('annotated.pdf');

Obsługiwane formaty

FormatRozszerzenieOdczytZapis
PDFpdf✓✓
Markdownmd✓✓
SVGsvg✓✓
TIFFtiff✓✓
DOCXdocx—✓
HTMLhtml—✓
PNGpng—✓
EPUBepub—✓

Open Source i licencjonowanie

Aspose.PDF FOSS dla TypeScript jest wydany na licencji MIT, a kod źródłowy opublikowano na GitHub. Nie ma znaku wodnego wersji próbnej, limitu użycia ani oddzielnego pliku licencyjnego do zarządzania, a biblioteka może być używana w produktach komercyjnych bez tantiem.

Pakiet jest obecnie w wersji 0.1.0, co odzwierciedla aktywny rozwój we wczesnym etapie. Node.js (>=22) jest jedynym wymogiem środowiska uruchomieniowego, a pakiet nie ma innych zależności zewnętrznych.

Rozpoczęcie

Powiązane zasoby