پشتیبانی AcroForm

نمای کلی

از HotPDF v2.5.0 به بعد، کتابخانه می‌تواند فرم‌های تعاملی (AcroForm) را بر اساس PDF 1.7 ISO 32000-1 بخش 12.7 صادر کند. هر فیلد فرم به‌صورت یک Widget annotation ساخته می‌شود که با دیکشنری فیلد ادغام شده و به‌طور خودکار با سند ثبت می‌شود تا وقتی سند در EndDoc نهایی می‌شود، ورودی سراسری /AcroForm به Catalog افزوده شود

نوع‌های پشتیبانی‌شده فیلد

• فیلدهای متنی (/FT /Tx) از طریق THPDFPage.AddTextField. از گزینه‌های تک‌خطی، چندخطی، گذرواژه، comb، انتخاب فایل، rich-text، scroll و spell-check از طریق THPDFFormFieldFlags پشتیبانی می‌کند
• چک‌باکس‌ها (/FT /Btn، بدون bitهای Pushbutton/Radio) از طریق THPDFPage.AddCheckBox با نام export قابل تنظیم و وضعیت اولیهٔ علامت‌خورده
• دکمه‌های رادیویی (/FT /Btn /Ff Radio) از طریق THPDFPage.AddRadioButton. فراخوانی‌های متعدد با همان نام گروه زیر یک فیلد والد مشترک با آرایهٔ /Kids ادغام می‌شوند، دقیقاً مطابق 12.7.4.2
• Combo boxes (/FT /Ch /Ff Combo) via THPDFPage.AddComboBox. Pass an open array of options
• List boxes (/FT /Ch) via THPDFPage.AddListBox. ffMultiSelect enables multi-select
• دکمه‌های فشاری (/FT /Btn /Ff Pushbutton) از طریق THPDFPage.AddPushButton با زیرنویس اختیاری (/MK /CA). از HotPDF v2.31.0، THPDFPage.AddPushButtonWithAction یک action dictionaryِ PDF را به widget وصل می‌کند تا کلیک روی دکمه /SubmitForm (ارسال مقادیر فیلد به URL، PDF 1.2 12.7.5.2)، /ResetForm (PDF 1.2 12.7.5.3)، /JavaScript (اجرای یک snippet جاوااسکریپت، PDF 1.3 12.6.4.16) یا /URI (بازکردن URL در مرورگر سیستم، PDF 1.1 12.6.4.7) را اجرا کند
• فیلدهای جای‌نگهدار امضا (/FT /Sig) از طریق THPDFPage.AddSignatureField از HotPDF v2.12.0 به بعد. دیکشنری AcroForm به‌طور خودکار /SigFlags 3 (SignaturesExist + AppendOnly) را می‌گیرد وقتی دست‌کم یک فیلد امضا وجود داشته باشد. این فیلد بدون امضا باقی می‌ماند تا ابزارهای بیرونی (Adobe Acrobat، Foxit، کتابخانه‌های اختصاصی CMS / PKCS#7) بتوانند امضای رمزنگاری واقعی را بعد از ذخیره شدن فایل اضافه کنند
• گردش‌کار امضای درجا از طریق THPDFPage.AddSignedSignatureField + THotPDF.PreparePDFForSigning + THotPDF.InsertSignatureHex از HotPDF v2.23.0 به بعد. نخستین فراخوانی یک signature dictionary در /V با جای‌نگهدارهای /ByteRange و /Contents رزرو می‌کند. بعد از ذخیرهٔ سند، برنامهٔ میزبان PreparePDFForSigning را صدا می‌زند تا /ByteRange را وصله کند و بفهمد کدام بازه‌های فایل باید هش شوند. پس از تولید یک امضای detached از نوع CMS / PKCS#7 به‌صورت بیرونی (Windows CryptoAPI، OpenSSL، کتابخانه‌های اختصاصی امضا)، InsertSignatureHex را صدا می‌زند تا hex امضا را در جای‌نگهدار قرار دهد بدون آن‌که هیچ byte دیگری در فایل را دست بزند

بازبینی و به‌روزرسانی فیلدهای بارگذاری‌شده

از HotPDF v2.121.9 به بعد، برنامه‌ها می‌توانند یک PDF موجودِ AcroForm را با THotPDF.LoadFromFile بارگذاری کنند، فیلدهای آن را enumerate کنند، نام‌ها، نوع‌ها و مقدارها را بخوانند، مقدار فیلدها را تغییر دهند، flag فقط‌خواندنی را toggle کنند و گراف شیء بارگذاری‌شده را با THotPDF.SaveLoadedDocument ذخیره کنند این مسیر برای ویرایش‌های پایدار روی سندی است که از قبل بارگذاری شده است؛ برای ذخیرهٔ تغییرات مقدار فیلد، فقط به‌خاطر آن BeginDoc / EndDoc را صدا نزنید

helperهای فیلد عبارت‌اند از GetFormFieldCount، GetFormFieldName، GetFormFieldType، GetFormFieldValue، SetFormFieldValue و SetFormFieldReadOnly. جست‌وجوی فیلد هم با اندیس صفرمبنایی فیلد و هم با نام کامل فیلد پذیرفته می‌شود. مقدارهای بازگشتی THPDFLoadedFormFieldType عبارت‌اند از lfftText، lfftButton، lfftChoice، lfftSignature یا lfftUnknown

نمونه Pascal برای فیلدهای بارگذاری‌شده

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

اقدام‌های تکمیلی فیلد

wrapperهای AttachFieldKeyStrokeAction، AttachFieldFormatAction، AttachFieldValidateAction و AttachFieldCalculateAction جاوااسکریپت را به دیکشنری /AA فیلد برای triggerهای PDF /K، /F، /V و /C وصل می‌کنند. وقتی filtering در keystroke، قالب‌بندی نمایش، اعتبارسنجی یا به‌روزرسانی فیلد محاسباتی باید همراه خود فیلد بماند نه یک دکمه، پس از ساخت یا بارگذاری فیلد از آن‌ها استفاده کنید

تولید ظاهر

به‌طور پیش‌فرض دیکشنری صادرشده /AcroForm مقدار /NeedAppearances true را تنظیم می‌کند و رندر جریان ظاهر را به نمایشگر مصرف‌کننده (Adobe Reader، Foxit، Chrome، مرورگرها، Apple Preview) واگذار می‌کند. THotPDF.AutoFormAppearances را پیش از افزودن فیلدها روی true بگذارید تا HotPDF برای هر فیلد متنی، push button، choice (combo / list) و حالت‌های Yes / Off هر checkbox / radio kid، Form XObjectهای /AP /N (PDF 1.7 8.10) را از پیش بسازد. در این صورت دیکشنری AcroForm مقدار /NeedAppearances false و یک ورودی /DR برای منابع پیش‌فرض شامل فونت‌های پایه استاندارد 14‌گانه (Helv Helvetica، ZaDb ZapfDingbats) را حمل می‌کند، بنابراین رندرکننده‌هایی که /NeedAppearances را نادیده می‌گیرند هم محتوای فیلد را درست رسم می‌کنند. از HotPDF v2.28.0 در دسترس است

مرجع flagهای فیلد (THPDFFormFieldFlags)

• ffReadOnly، ffRequired، ffNoExport — flagهای رایج Table 227 که برای همهٔ نوع‌های فیلد کاربرد دارند
• ffMultiline، ffPassword، ffFileSelect، ffDoNotSpellCheck، ffDoNotScroll، ffComb، ffRichText — مخصوص Tx (Table 228)
• ffEdit، ffSort، ffMultiSelect، ffDoNotSpellCheck، ffCommitOnSelChange — مخصوص Ch (Table 230)

نمونه Pascal

HPDF.BeginDoc;
HPDF.AddPage;
HPDF.CurrentPage.AddTextField('Name', '', Rect(50, 100, 250, 120));
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;

محدودیت‌ها

• generatorِ AutoFormAppearances فعلاً فقط مقدارهای قابل‌کدگذاری با ASCII / WinAnsi را layout می‌کند؛ برای فیلدهایی که /V آن‌ها متن چندبایتی (UTF-8) دارد، /AP ذخیره‌شده تا وقتی viewer میزبان appearance را دوباره تولید کند، به‌صورت یک مستطیل خالی رندر می‌شود
• زیر-حالت‌های Down (/D) و rollover (/R) تولید نمی‌شوند؛ فقط حالت normal (/N) ساخته می‌شود
• منحصر‌بودن نام فیلد مسئولیت فراخواننده است؛ HotPDF آن را enforce نمی‌کند

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

• THPDFPage class
• THotPDF class