وثائق HotPDF
الصفحة الرئيسية المحتويات نظرة عامة

دعم AcroForm

ملاحظة

منذ HotPDF v2.5.0 تستطيع المكتبة إصدار نماذج تفاعلية (AcroForm) وفق القسم 12.7 من PDF 1.7 ISO 32000-1. يُنشَأ كل حقل نموذج كتعليق Widget مدموج مع قاموس الحقل، ويُسجَّل تلقائيًا مع المستند بحيث يُضاف مُدخل /AcroForm العام إلى الكتالوج عند إنهاء المستند في EndDoc.

ملاحظة

  • حقول النص (/FT /Tx) عبر THPDFPage.AddTextField. تدعم خيارات سطر واحد، ومتعدد الأسطر، وكلمة مرور، وcomb، واختيار ملف، ونص غني، وتمرير (scroll)، وتدقيق إملائي عبر THPDFFormFieldFlags.
  • خانات الاختيار (check boxes) (/FT /Btn، دون بتّات Pushbutton/Radio) عبر THPDFPage.AddCheckBox مع اسم قيمة تصدير (export value) قابل للتهيئة وحالة تحديد أولية
  • أزرار الراديو (radio buttons) (/FT /Btn /Ff Radio) عبر THPDFPage.AddRadioButton. تُدمَج الاستدعاءات المتعددة بنفس اسم المجموعة تحت حقل أب مشترك بمصفوفة /Kids، تمامًا كما يقتضي البند 12.7.4.2.
  • الصناديق المركَّبة (combo boxes) (/FT /Ch /Ff Combo) عبر THPDFPage.AddComboBox. مرِّر مصفوفة مفتوحة (open array) من الخيارات
  • صناديق القوائم (list boxes) (/FT /Ch) عبر THPDFPage.AddListBox. تُفعِّل ffMultiSelect التحديد المتعدد
  • أزرار الضغط (push buttons) (/FT /Btn /Ff Pushbutton) عبر THPDFPage.AddPushButton مع تعليق (caption) اختياري (/MK /CA). ومنذ HotPDF v2.31.0، تُرفق THPDFPage.AddPushButtonWithAction قاموس إجراء PDF بالودجة بحيث ينفّذ النقر على الزر /SubmitForm (إرسال قيم الحقول إلى عنوان URL، PDF 1.2 12.7.5.2)، أو /ResetForm (PDF 1.2 12.7.5.3)، أو /JavaScript (تشغيل مقتطف JS، PDF 1.3 12.6.4.16)، أو /URI (فتح عنوان URL في متصفح النظام، PDF 1.1 12.6.4.7)
  • حقول توقيع محجوزة مسبقًا (placeholder) (/FT /Sig) عبر THPDFPage.AddSignatureField منذ HotPDF v2.12.0. ويكتسب قاموس AcroForm تلقائيًا /SigFlags 3 (SignaturesExist + AppendOnly) عند وجود حقل توقيع واحد على الأقل. ويُترَك الحقل غير موقَّع بحيث تستطيع أدوات خارجية (Adobe Acrobat، وFoxit، ومكتبات توقيع CMS / PKCS#7 المخصَّصة) إرفاق التوقيع التشفيري الفعلي بعد حفظ الملف
  • مسار عمل التوقيع في المكان (in-place) عبر THPDFPage.AddSignedSignatureField + THotPDF.PreparePDFForSigning + THotPDF.InsertSignatureHex منذ HotPDF v2.23.0. يحجز النداء الأول قاموس توقيع /V مع حجوزات مسبقة (placeholders) لـ /ByteRange و/Contents. وبعد حفظ المستند، يستدعي التطبيق المضيف PreparePDFForSigning لترقيع /ByteRange ومعرفة نطاقات الملف الواجب تجزئتها (hash). وبعد إنتاج توقيع CMS / PKCS#7 منفصل (detached) خارجيًا (عبر Windows CryptoAPI أو OpenSSL أو مكتبات توقيع مخصَّصة)، يستدعي InsertSignatureHex لإسقاط قيمة التوقيع السداسية عشرية في الحجز المسبق دون المساس بأي بايت آخر في الملف

ملاحظة

منذ HotPDF v2.292.12، تُنشئ الدوال المساعدة THPDFPage.CreateTextField و CreateCheckBox و CreateRadioButton و CreateComboBox و CreateListBox نفس ودجات AcroForm التي تنشئها دوال Add... الحالية، وتُعيد غلافًا (wrapper) خفيفًا من نوع THPDFAcroFormField للتهيئة الفورية

منذ HotPDF v2.292.26، تُعيِّن THotPDF.SetFormFieldTooltip تلميح المستخدم /TU من PDF باسم الحقل للحقول المُنشَأة عبر دوال Add... الحالية، بما يطابق مسار عمل THPDFAcroFormField.SetTooltip على مستوى الغلاف (wrapper)

منذ HotPDF v2.298.0، ترفض واجهات إنشاء الحقول وقت الإنشاء وواجهات إنشاء الحقول في المستند المحمَّل أسماء الحقول الجذرية المكرَّرة باستثناء تشخيصي قبل تسجيل أي ودجة. وتبقى استدعاءات AddRadioButton المتكررة بنفس اسم المجموعة صالحة لأنها تشترك في حقل أب واحد وتضيف ودجات فرعية إضافية تحت مصفوفة /Kids الخاصة به

يكشف الغلاف (wrapper) دوال تعيين قابلة للتسلسل (chainable) لتلميحات /TU، وأعلام (flags) الحقل الشائعة (SetReadOnly، وSetRequired، وSetNoExport)، وسلاسل المظهر الافتراضي /DA، وإجراءات إضافية على مستوى الحقل مثل /AA /K و /AA /F و /AA /V و /AA /C، وإجراءات الماوس أو التركيز للودجة عبر THPDFActionBuilder

ملاحظة

Field := HPDF.CurrentPage.CreateTextField('Email', '', Rect(50, 80, 250, 104));
Action := THPDFActionBuilder.JavaScript('event.rc = event.value.indexOf("@") > 0;');
try
  Field.SetTooltip('Email address');
  Field.SetRequired(True);
  Field.SetReadOnly(False);
  Field.SetAdditionalAction(fatValidate, Action);
finally
  Action.Free;
  Field.Free;
end;

ملاحظة

منذ HotPDF v2.121.9، تستطيع التطبيقات تحميل ملف AcroForm PDF موجود عبر THotPDF.LoadFromFile، وسرد حقوله، وقراءة أسمائها وأنواعها وقيمها، وتغيير قيم الحقول، وتبديل علم القراءة فقط (read-only)، وحفظ رسم الكائنات المحمَّل عبر THotPDF.SaveLoadedDocument. وهذا المسار مخصَّص لتعديلات دائمة على مستند محمَّل بالفعل؛ لا تستدعِ BeginDoc / EndDoc فقط لحفظ تغييرات قيم الحقول المحمَّلة

الدوال المساعدة للحقول هي GetFormFieldCount و GetFormFieldName و GetFormFieldType و GetFormFieldValue و SetFormFieldValue و SetFormFieldReadOnly. ويقبل البحث عن الحقل إما فهرسًا صفري الأساس (zero-based) أو اسم الحقل المؤهَّل بالكامل. وقيم THPDFLoadedFormFieldType المُعادة هي lfftText أو lfftButton أو lfftChoice أو lfftSignature أو lfftUnknown.

ملاحظة

HPDF.LoadFromFile('InputForm.pdf');
for I := 0 to HPDF.GetFormFieldCount - 1 do
  Writeln(HPDF.GetFormFieldName(I), ' = ', HPDF.GetFormFieldValue(I));

HPDF.SetFormFieldValue('CustomerName', 'Bob');
HPDF.SetFormFieldValue('Plan', 'Premium');
HPDF.SetFormFieldReadOnly('CustomerName', True);
HPDF.SaveLoadedDocument('UpdatedForm.pdf');

ملاحظة

تُرفق الأغلفة AttachFieldKeyStrokeAction و AttachFieldFormatAction و AttachFieldValidateAction و AttachFieldCalculateAction شفرة JavaScript بقاموس /AA الخاص بالحقل لمحفّزات PDF /K و /F و /V و /C. استخدم SetFormFieldAdditionalAction أو أغلفتها المسمّاة في THPDFActionBuilder عندما يجب أن ينفّذ نفس المحفّز سلسلة إجراءات قابلة لإعادة الاستخدام مثل JavaScript أو ResetForm أو SubmitForm أو URI أو Hide أو ImportData أو إجراء /Next متسلسل. ويمكن أيضًا تركيب محفّزات الماوس والتركيز على مستوى الودجة باسم الحقل عبر SetFormFieldAnnotationAction والدوال المساعدة المسمّاة للماوس/التركيز، بينما تزيل دوال المسح المطابقة محفّزًا واحدًا دون المساس ببقية قاموس /AA

ملاحظة

افتراضيًا، يضبط قاموس /AcroForm المُصدَر /NeedAppearances true ويفوّض عرض stream المظهر إلى العارض (viewer) المستهلك (Adobe Reader، وFoxit، وChrome، والمتصفحات، وApple Preview). واضبط THotPDF.AutoFormAppearances على true قبل إضافة الحقول، وستبني HotPDF مسبقًا كائنات Form XObject من نوع /AP /N (PDF 1.7 8.10) لكل حقل نص، وزر ضغط، وخيار (combo / list)، وحالتَي Yes / Off لكل عنصر (kid) خانة اختيار/راديو. عندئذٍ يحمل قاموس AcroForm /NeedAppearances false ومُدخل موارد افتراضية /DR يشير إلى خطوط Base 14 القياسية (Helv لـ Helvetica، وZaDb لـ ZapfDingbats)، بحيث ترسم العارضات التي تتجاهل /NeedAppearances محتوى الحقل بشكل صحيح رغم ذلك. متاح منذ HotPDF v2.28.0.

ملاحظةTHPDFFormFieldFlagsملاحظة

  • ffReadOnly، ffRequired، ffNoExport — أعلام شائعة من الجدول 227 قابلة للتطبيق على كل نوع حقل
  • ffMultiline، ffPassword، ffFileSelect، ffDoNotSpellCheck، ffDoNotScroll، ffComb، ffRichText — خاصة بـ Tx (الجدول 228)
  • ffEdit، ffSort، ffMultiSelect، ffDoNotSpellCheck، ffCommitOnSelChange — خاصة بـ Ch (الجدول 230)

ملاحظة

HPDF.BeginDoc;
HPDF.AddPage;
HPDF.CurrentPage.AddTextField('Name', '', Rect(50, 100, 250, 120));
HPDF.SetFormFieldTooltip('Name', 'Customer name');
HPDF.CurrentPage.AddCheckBox('Agree', 'Yes', Rect(50, 130, 70, 145), True);
HPDF.CurrentPage.AddRadioButton('Color', 'Red',   Rect(50, 160, 70, 175), True);
HPDF.CurrentPage.AddRadioButton('Color', 'Green', Rect(80, 160, 100, 175));
HPDF.CurrentPage.AddRadioButton('Color', 'Blue',  Rect(110, 160, 130, 175));
HPDF.CurrentPage.AddComboBox('Country', 'CN',
                             ['CN', 'US', 'JP'], Rect(50, 190, 250, 210));
HPDF.EndDoc;

ملاحظة

  • يُخطِّط مولِّد AutoFormAppearances حاليًا القيم القابلة للترميز بـ ASCII / WinAnsi فقط؛ وبالنسبة للحقول التي يحتوي /V فيها على نص متعدد البايت (UTF-8)، يعرض /AP المخزَّن مستطيلًا فارغًا إلى أن يعيد العارض المضيف توليد المظهر
  • لا تُولَّد الحالتان الفرعيتان down (/D) وrollover (/R)؛ إذ تُنتَج الحالة العادية (/N) فقط
  • تُفحَص أسماء الحقول بحثًا عن مُدخلات جذرية مكرَّرة عند إنشاء ودجات AcroForm جديدة؛ ويبقى بناء الأسماء الجزئية الهرمي (hierarchical) بما يتجاوز نمط أب-راديو/ودجة مسؤولية المستدعي'.

ملاحظة