Dokumentacja HotPDF
Start Spis treści Omówienie

Obsługa AcroForm

Omówienie

Od HotPDF v2.5.0 biblioteka może emitować formularze interaktywne (AcroForm) zgodnie z PDF 1.7 ISO 32000-1 section 12.7. Każde pole formularza jest tworzone jako adnotacja Widget połączona ze słownikiem pola i automatycznie rejestrowane w dokumencie, dzięki czemu globalny wpis /AcroForm jest dodawany do Catalog podczas finalizacji dokumentu w EndDoc.

Obsługiwane typy pól

  • Pola tekstowe (/FT /Tx) przez THPDFPage.AddTextField. Obsługują opcje jednowierszowe, wielowierszowe, hasła, comb, wybór pliku, rich-text, przewijanie i sprawdzanie pisowni przez THPDFFormFieldFlags.
  • Pola wyboru (/FT /Btn, bez bitów Pushbutton/Radio) przez THPDFPage.AddCheckBox z konfigurowalną nazwą wartości eksportu i początkowym stanem zaznaczenia.
  • Przyciski opcji (/FT /Btn /Ff Radio) przez THPDFPage.AddRadioButton. Wielokrotne wywołania z tą samą nazwą grupy są łączone pod wspólnym polem nadrzędnym z tablicą /Kids, dokładnie tak, jak wymaga 12.7.4.2.
  • Pola combo (/FT /Ch /Ff Combo) przez THPDFPage.AddComboBox. Przekaż otwartą tablicę opcji.
  • Listy (/FT /Ch) przez THPDFPage.AddListBox. ffMultiSelect włącza wybór wielu pozycji.
  • Przyciski (/FT /Btn /Ff Pushbutton) przez THPDFPage.AddPushButton z opcjonalnym podpisem (/MK /CA). Od HotPDF v2.31.0 THPDFPage.AddPushButtonWithAction dołącza słownik akcji PDF do widgetu, aby kliknięcie przycisku uruchamiało /SubmitForm (wysłanie wartości pól do URL, PDF 1.2 12.7.5.2), /ResetForm (PDF 1.2 12.7.5.3), /JavaScript (uruchomienie fragmentu JS, PDF 1.3 12.6.4.16) albo /URI (otwarcie URL w przeglądarce systemowej, PDF 1.1 12.6.4.7).
  • Pola zastępcze podpisu (/FT /Sig) przez THPDFPage.AddSignatureField od HotPDF v2.12.0. Słownik AcroForm automatycznie otrzymuje /SigFlags 3 (SignaturesExist + AppendOnly), gdy obecne jest co najmniej jedno pole podpisu. Pole pozostaje niepodpisane, aby narzędzia zewnętrzne (Adobe Acrobat, Foxit, dedykowane biblioteki podpisywania CMS / PKCS#7) mogły dołączyć rzeczywisty podpis kryptograficzny po zapisaniu pliku.
  • Przepływ podpisywania w miejscu przez THPDFPage.AddSignedSignatureField + THotPDF.PreparePDFForSigning + THotPDF.InsertSignatureHex od HotPDF v2.23.0. Pierwsze wywołanie rezerwuje słownik podpisu /V z placeholderami /ByteRange i /Contents. Po zapisaniu dokumentu aplikacja hosta wywołuje PreparePDFForSigning, aby załatać /ByteRange i poznać zakresy pliku do haszowania. Po zewnętrznym utworzeniu podpisu odłączonego CMS / PKCS#7 (Windows CryptoAPI, OpenSSL, dedykowane biblioteki podpisujące) wywołuje InsertSignatureHex, aby wstawić hex podpisu do placeholdera bez naruszania żadnego innego bajtu w pliku.

Inspekcja i aktualizacje wczytanych pól formularza

Od HotPDF v2.121.9 aplikacje mogą wczytać istniejący PDF AcroForm przez THotPDF.LoadFromFile, wyliczyć jego pola, odczytać ich nazwy, typy i wartości, zmienić wartości pól, przełączyć flagę tylko do odczytu oraz zapisać wczytany graf obiektów przez THotPDF.SaveLoadedDocument. Ta ścieżka jest przeznaczona do trwałych edycji dokumentu już wczytanego; nie wywołuj BeginDoc / EndDoc tylko po to, aby zapisać zmiany wartości wczytanych pól.

Pomocnikami pól są GetFormFieldCount, GetFormFieldName, GetFormFieldType, GetFormFieldValue, SetFormFieldValue oraz SetFormFieldReadOnly. Wyszukiwanie pola przyjmuje indeks pola liczony od zera albo w pełni kwalifikowaną nazwę pola. Zwracane wartości THPDFLoadedFormFieldType to lfftText, lfftButton, lfftChoice, lfftSignature albo lfftUnknown.

Przykład Pascal dla wczytanego pola

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

Dodatkowe akcje pól

AttachFieldKeyStrokeAction, AttachFieldFormatAction, AttachFieldValidateAction i AttachFieldCalculateAction dołączają JavaScript do słownika /AA pola dla wyzwalaczy PDF /K, /F, /V i /C. Używaj ich po utworzeniu lub wczytaniu pola, gdy filtrowanie, format, walidacja albo obliczenia mają należeć do pola.

Generowanie wyglądu

Domyślnie emitowany słownik /AcroForm ustawia /NeedAppearances true i przekazuje renderowanie strumieni wyglądu do czytnika odbiorcy (Adobe Reader, Foxit, Chrome, przeglądarki, Apple Preview). Ustaw THotPDF.AutoFormAppearances na true przed dodaniem pól, a HotPDF zbuduje wcześniej obiekty Form XObject /AP /N (PDF 1.7 8.10) dla każdego pola tekstowego, przycisku, wyboru (combo / lista) oraz stanów Yes / Off każdego checkboxa / dziecka radio. Słownik AcroForm zawiera wtedy /NeedAppearances false i domyślny wpis zasobów /DR odwołujący się do standardowych 14 fontów bazowych (Helv Helvetica, ZaDb ZapfDingbats), więc renderery ignorujące /NeedAppearances nadal poprawnie rysują zawartość pola. Dostępne od HotPDF v2.28.0.

Referencja flag pól (THPDFFormFieldFlags)

  • ffReadOnly, ffRequired, ffNoExport — wspólne flagi Table 227 mające zastosowanie do każdego typu pola.
  • ffMultiline, ffPassword, ffFileSelect, ffDoNotSpellCheck, ffDoNotScroll, ffComb, ffRichText — specyficzne dla Tx (Table 228).
  • ffEdit, ffSort, ffMultiSelect, ffDoNotSpellCheck, ffCommitOnSelChange — specyficzne dla Ch (Table 230).

Przykład 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;

Ograniczenia

  • Generator AutoFormAppearances obecnie układa tylko wartości możliwe do zakodowania jako ASCII / WinAnsi; dla pól, których /V zawiera tekst wielobajtowy (UTF-8), zapisany /AP renderuje pusty prostokąt do czasu, aż czytnik hosta odtworzy wygląd.
  • Podstany down (/D) i rollover (/R) nie są generowane; tworzony jest tylko stan normalny (/N).
  • Unikalność nazw pól jest obowiązkiem kodu wywołującego; HotPDF jej nie wymusza.

Zobacz też