Анотации и формуляри

Анотации и формуляри

Aspose.PDF FOSS for .NET ви предоставя пълен достъп за четене/писане до PDF анотации
и интерактивни AcroForm полета. Основната точка за достъп до анотациите е
Page.Annotations (AnnotationCollection), докато полетата на формуляра се достъпват
чрез Document.Form. Двата подсистеми работят изцяло в паметта и не изискват лицензен ключ.

Добавяне на анотации

AnnotationCollection предоставя типизирани помощни методи за всеки стандартен тип анотация. Всеки метод приема Rectangle, определяща позицията на анотацията на страницата, плюс параметри, специфични за типа.

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);

Анотации за връзка и действия

Връзките комбинират кликваем правоъгълник с PdfAction. Библиотеката поддържа
URI, GoTo, JavaScript, Named и 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");

За да прочетете връзка обратно след отваряне на запазен PDF, кастирайте анотацията към LinkAnnotation и проверете нейното Uri свойство или разрешете речника за действие чрез PdfAction.Create.

Маркиране и анотации на форми

Анотации за маркиране (осветяване, подчертаване, зачертаване) маркират съществуващ текст. Анотации за форми (квадрат, кръг, линия, мастило) рисуват геометрия върху страницата.

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);

Анотации за печат

Анотациите тип печат поставят изображение или предварително зададена икона върху страница.

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

Изравняване на анотациите

Извикайте Flatten() върху всяка анотация, за да запечатате визуалния й вид в потока на съдържанието на страницата и да я премахнете от списъка с интерактивни анотации.

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

Посетителският шаблон с AnnotationSelector

AnnotationSelector реализира шаблона посетител, така че можете да филтрирате анотациите по тип без ръчно преобразуване.

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
}

Подайте типизиран екземпляр на анотация към конструктора, за да филтрирате само за този тип:

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

Интерактивни полета за формуляри

Достъпвайте полетата на AcroForm чрез Document.Form. Класът Form предоставя операции за четене/писане на ниво поле и поддържа експортиране в JSON.

using var doc = Document.Open(pdfBytes);

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

Подкласовете на Field включват TextBoxField, CheckboxField, RadioButtonField, ComboBoxField, ListBoxField, ChoiceField и SignatureField.

Експортиране на данни от формуляра в JSON

WidgetAnnotation предоставя ExportToJson претоварвания за сериализиране на данни от полета към поток или път до файл. По избор, параметър ExportFieldsToJsonOptions контролира форматирането на изхода.

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

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

Съвети и най‑добри практики

• Винаги посочвайте явни Rectangle координати в единици на потребителското пространство на PDF (1/72 инч).
• Използвайте AddLinkAnnotation с PdfAction за максимална гъвкавост — поддържат се URI, GoTo, JavaScript и Named действия.
• Извикайте Flatten() преди разпространение на PDF, ако желаете анотациите да се показват в неинтерактивни прегледачи.
• Достъпвайте полетата на формуляра чрез Document.Form.Fields, вместо да обхождате анотациите на страниците — колекцията от форми се грижи за групирането на полетата през различни страници.
• Запазете и отворете отново документа, за да проверите точността на анотациите при преминаване напред‑назад, особено за персонализирани действия.

Чести проблеми

ЧЗВ

Как да добавя хипервръзка към страница в PDF?

Използвайте page.Annotations.AddLinkAnnotation(rect, PdfAction.CreateUri(url)), за да създадете кликваща URI връзка в указания правоъгълник.

Мога ли да прочета стойностите на полетата от формуляра в съществуващ PDF?

Да. Отворете документа с Document.Open, след това итерирайте Document.Form.Fields и прочетете свойството Value за всеки Field.

Какви типове анотации поддържа библиотеката?

Библиотеката поддържа текст, свободен текст, връзка, маркиране, подчертаване, задраскване, квадрат, кръг, линия, мастило, печат, карет, прикачен файл, звук, полигон, полилиния, уиджет, воден знак и 3D анотации. Всички типове са достъпни чрез AnnotationCollection помощни методи или директно създаване.

Как да филтрирам анотациите по тип?

Използвайте AnnotationSelector с типизирана шаблонна анотация. Извикайте page.Accept(selector) и проверете selector.Selected за съвпадащи анотации.

Мога ли да изравня само определени анотации?

Да. Извикайте Flatten() върху отделни Annotation екземпляри, вместо да итерирате цялата колекция.

API Обобщение на справката

Вижте също

• Aspose.PDF for .NET Enterprise продукт