حاشیه‌نویسی‌ها و فرم‌ها

حاشیه‌نویسی‌ها و فرم‌ها

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

فیلدهای فرم تعاملی

از طریق Document.Form به فیلدهای AcroForm دسترسی پیدا کنید. کلاس 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 overloadهای 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 و اقدامات نام‌گذاری‌شده همگی پشتیبانی می‌شوند.
• قبل از توزیع یک PDF، اگر می‌خواهید حاشیه‌نویسی‌ها در نمایشگرهای غیر تعاملی ظاهر شوند، Flatten() را فراخوانی کنید.
• به فیلدهای فرم از طریق 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

همچنین ببینید

• محصول Enterprise Aspose.PDF برای .NET