Adnotacje i formularze

Adnotacje i formularze

Aspose.PDF FOSS for .NET zapewnia pełny dostęp do odczytu/zapisu adnotacji PDF oraz interaktywnych pól AcroForm. Głównym punktem wejścia dla adnotacji jest Page.Annotations (AnnotationCollection), natomiast pola formularza są dostępne przez Document.Form. Oba podsystemy działają w całości w pamięci i nie wymagają klucza licencyjnego.

Dodawanie adnotacji

AnnotationCollection udostępnia typowane metody pomocnicze dla każdego standardowego rodzaju adnotacji. Każda metoda przyjmuje Rectangle definiujący położenie adnotacji na stronie oraz parametry specyficzne dla typu.

using var doc = Document.Open(pdfBytes);
var page = doc.Pages[1];

// Text (sticky-note) annotation
page.Annotations.AddTextAnnotation(
    new Rectangle(72, 720, 200, 740),
    contents: "Review this paragraph",
    title: "Editor",
    open: true);

// Highlight annotation
page.Annotations.AddHighlightAnnotation(
    new Rectangle(72, 680, 300, 700),
    quadPoints: null,
    color: new double[] { 1, 1, 0 });

// Free-text annotation (rendered directly on the page)
page.Annotations.AddFreeTextAnnotation(
    new Rectangle(72, 640, 350, 660),
    contents: "Inline note",
    fontName: "Helvetica",
    fontSize: 10,
    color: new double[] { 0, 0, 0 });

using var ms = new MemoryStream();
doc.Save(ms);

Adnotacje i akcje linków

Linki łączą prostokąt klikalny z PdfAction. Biblioteka obsługuje
akcje URI, GoTo, JavaScript, Named oraz Launch.

using var doc = Document.Open(pdfBytes);
var page = doc.Pages[1];

// URI link
var uriAction = PdfAction.CreateUri("https://aspose.com");
page.Annotations.AddLinkAnnotation(
    new Rectangle(50, 700, 200, 720), uriAction);

// GoTo link (jump to page 3)
page.Annotations.AddLinkAnnotation(
    new Rectangle(50, 660, 200, 680),
    destinationPage: 3,
    destRect: new Rectangle(0, 0, 612, 792));

// JavaScript link
var jsAction = PdfAction.CreateJavaScript("app.alert('Hello');");
page.Annotations.AddLinkAnnotation(
    new Rectangle(50, 620, 200, 640), jsAction);

doc.Save("links.pdf");

Aby odczytać link po otwarciu zapisanego PDF, rzutuj adnotację na LinkAnnotation i sprawdź jej Uri właściwość lub rozwiąż słownik akcji za pomocą PdfAction.Create.

Adnotacje znaczników i kształtów

Adnotacje znaczników (podświetlenie, podkreślenie, przekreślenie) oznaczają istniejący tekst. Adnotacje kształtów (kwadrat, koło, linia, atrament) rysują geometrię na stronie.

var page = doc.Pages[1];

// Underline
page.Annotations.AddUnderlineAnnotation(
    new Rectangle(72, 600, 300, 620),
    quadPoints: null,
    color: new double[] { 1, 0, 0 });

// Square
page.Annotations.AddSquareAnnotation(
    new Rectangle(72, 540, 200, 580),
    borderColor: new double[] { 0, 0, 1 },
    fillColor: null,
    lineWidth: 1.5);

// Line
page.Annotations.AddLineAnnotation(
    new Rectangle(72, 500, 300, 520),
    x1: 72, y1: 510, x2: 300, y2: 510,
    color: new double[] { 0, 0.5, 0 },
    lineWidth: 2);

// Ink (freehand)
page.Annotations.AddInkAnnotation(
    new Rectangle(72, 440, 200, 480),
    inkPaths: new[] { new double[] { 80, 450, 120, 470, 160, 450 } },
    color: new double[] { 0.5, 0, 0.5 },
    lineWidth: 1);

Adnotacje pieczątki

Adnotacje pieczątki nakładają obraz lub zdefiniowaną wcześniej ikonę na stronę.

var stamp = new StampAnnotation(doc);
// Configure stamp properties, then add to page
page.Annotations.Add(stamp);

Spłaszczanie adnotacji

Wywołaj Flatten() na dowolnej adnotacji, aby utrwalić jej wygląd wizualny w strumieniu zawartości strony i usunąć ją z listy interaktywnych adnotacji.

foreach (var annot in doc.Pages[1].Annotations)
{
    annot.Flatten();
}

Wzorzec odwiedzający z AnnotationSelector

AnnotationSelector implementuje wzorzec odwiedzający, dzięki czemu możesz filtrować adnotacje według typu bez ręcznego rzutowania.

var selector = new AnnotationSelector();
doc.Pages[1].Accept(selector);

// selector.Selected now contains all annotations on page 1
foreach (var annot in selector.Selected)
{
    // Process each annotation by type
}

Przekaż instancję adnotacji typowanej do konstruktora, aby filtrować tylko ten typ:

var linkFilter = new AnnotationSelector(new LinkAnnotation(page, Rectangle.Empty));
page.Accept(linkFilter);
// linkFilter.Selected contains only LinkAnnotation instances

Interaktywne pola formularza

Uzyskaj dostęp do pól AcroForm za pomocą Document.Form. Klasa Form udostępnia operacje odczytu/zapisu na poziomie pól i obsługuje eksport JSON.

using var doc = Document.Open(pdfBytes);

// Enumerate all fields
foreach (var field in doc.Form.Fields)
{
    Console.WriteLine($"{field.FullName}: {field.Value}");
}

Podklasy pola obejmują TextBoxField, CheckboxField, RadioButtonField, ComboBoxField, ListBoxField, ChoiceField i SignatureField.

Eksportowanie danych formularza do JSON

WidgetAnnotation udostępnia przeciążenia ExportToJson do serializacji danych pól do strumienia lub ścieżki pliku. Opcjonalny parametr ExportFieldsToJsonOptions kontroluje formatowanie wyjścia.

using var doc = Document.Open(pdfBytes);
var widget = (WidgetAnnotation)doc.Pages[1].Annotations[1];

using var jsonStream = new MemoryStream();
widget.ExportToJson(jsonStream);

Wskazówki i najlepsze praktyki

• Zawsze podawaj explicite współrzędne Rectangle w jednostkach przestrzeni użytkownika PDF (1/72 cala).
• Użyj AddLinkAnnotation z PdfAction dla maksymalnej elastyczności — obsługiwane są URI, GoTo, JavaScript i Named actions.
• Wywołaj Flatten() przed rozpowszechnieniem pliku PDF, jeśli chcesz, aby adnotacje były widoczne w przeglądarkach nieinteraktywnych.
• Uzyskaj dostęp do pól formularza za pomocą Document.Form.Fields zamiast iterować adnotacje stron — kolekcja formularzy obsługuje grupowanie pól na wielu stronach.
• Zapisz i ponownie otwórz dokument, aby zweryfikować integralność adnotacji w cyklu round‑trip, szczególnie dla niestandardowych akcji.

Typowe problemy

FAQ

Jak dodać hiperłącze do strony PDF?

Użyj page.Annotations.AddLinkAnnotation(rect, PdfAction.CreateUri(url)), aby utworzyć klikalny link URI w określonym prostokącie.

Czy mogę odczytać wartości pól formularza z istniejącego pliku PDF?

Tak. Otwórz dokument przy użyciu Document.Open, następnie iteruj Document.Form.Fields i odczytaj właściwość Value dla każdego Field.

Jakie typy adnotacji obsługuje biblioteka?

Biblioteka obsługuje tekst, wolny tekst, link, podświetlenie, podkreślenie, przekreślenie, kwadrat, koło, linię, atrament, pieczęć, karetkę, załącznik pliku, dźwięk, wielokąt, polilinię, widżet, znak wodny i adnotacje 3D. Wszystkie typy są dostępne poprzez AnnotationCollection metody pomocnicze lub bezpośrednie tworzenie.

Jak filtrować adnotacje według typu?

Użyj AnnotationSelector z typowaną adnotacją szablonu. Wywołaj page.Accept(selector) i sprawdź selector.Selected pod kątem dopasowanych adnotacji.

Czy mogę spłaszczyć tylko określone adnotacje?

Tak. Wywołaj Flatten() na poszczególnych instancjach Annotation zamiast iterować całą kolekcję.

Podsumowanie referencji API

Zobacz także

• Aspose.PDF for .NET Enterprise Product