التعليقات التوضيحية والنماذج

التعليقات والنماذج

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

تشمل الفئات الفرعية للحقول 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 والإجراءات المسماة كلها مدعومة.
• استدعِ 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 لـ .NET منتج Enterprise