הערות וטפסים

הערות וטפסים

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 מוצר ארגוני