XFA formų konvertavimas į „AcroForm“ su „HotPDF“ „Delphi“ aplinkoje

Dvi formos gali turėti tuos pačius laukus, tačiau veikti visiškai skirtingai. „AcroForm“ savo laukus saugo kaip įprastus PDF objektus, esančius virš tikrojo puslapio turinio, zodžiu, bet kuri suderinama peržiūros programa juos lengvai atvaizduoja. Dinaminė XFA forma PDF formatu nesaugo beveik nieko: laukai, išdėstymas ir net puslapio geometrija yra XML pakete, o matomi puslapiai sugeneruojami tik atidarant failą per maketavimo variklį, kurį plačiau platino tik „Adobe“. Pateikę tokį failą interneto naršyklei, archyvo atvaizdavimo programai ar teksto išgavimo įrankiui, formos nematysite. Pamatysite tik pilką puslapį su užrašu „Prašome palaukti...“ (angl. Please wait...). Kiekvienas, kuriam teko susidurti su valstybiniais ar draudimo dokumentais, šį puslapį žino iš pirmo žvilgsnio.

Šis vietos rezervavimo ženklas (placeholder) nėra failo sugadinimas. Formato specifikacijoje nurodyta, kad būtent taip turi nutikti, kai sistemoje nėra XFA procesoriaus, o tai apibūdina beveik visas peržiūros programas, išskyrus stalinę „Acrobat“ versiją. Todėl praktiškiausia yra konvertuoti dinaminę formą į paprastą „AcroForm“, prieš jai patenkant į kitas sistemas. „HotPDF“ – „losLab“ PDF biblioteka, skirta „Delphi“ ir „C++Builder“ – atlieka šį konvertavimą kode, perstatydama XML formą į standartinius laukus tikruose PDF puslapiuose.

Kodėl abu modeliai negali bendrai egzistuoti

„AcroForm“ yra apibrėžta ISO 32000-1 §12.7. Kiekvienas laukas yra PDF objektas su valdiklio anotacija (widget annotation) ir išvaizdos srautu (appearance stream), puslapis yra tikras PDF turinys, o duomenys yra virš jo. XFA veikia priešingai: forma yra XML dokumentas, XDP paketas, saugomas „AcroForm“ žodyno /XFA įraše, o dinaminės formos PDF puslapiuose yra tik „Prašome palaukti“ pranešimas, nes tikrasis turinys niekada nebuvo išsaugotas kaip PDF. Peržiūros programa apdoroja failą pagal vieną arba kitą modelį. Jei ignoruosite /XFA įrašą, matysite tik tuščią apvalkalą; jei bandysite jį apdoroti be XFA variklio, matysite įspėjimą. ISO 32000-2 standartas užbaigė šias diskusijas pašalindamas XFA palaikymą iš PDF 2.0 versijos, ir tai yra pagrindinė priežastis, kodėl formų konvertavimas tapo kasdiene praktika.

Prieš konvertuodami klasifikuokite failus, nes ne kiekvienas XFA failas rodo pradinį įspėjimą. Statinės XFA formos pateikia iš anksto sugeneruotus PDF puslapius šalia XML struktūros, zodžiu, jos rodomos visur, o problemų kyla tik jas pildant. Dinaminės formos turi tik įspėjimą ir yra nenaudojamos, kol nėra sukonvertuotos. Pasitikėkite tik pačiu dokumentu, o ne jo plėtiniu ar siuntėju. Failas, kuris rodo tikrąjį turinį ne „Adobe“ peržiūros programoje, bet vis tiek turi /XFA įrašą, yra statinis arba hibridinis. Dokumentas, rodantis įspėjamąjį puslapį, yra dinaminis. Užregistruokite, kuriai kategorijai priklauso kiekvienas gaunamas failas, nes šios dvi rūšys vėliau sukelia skirtingų problemų, o užklausa dėl tuščio suarchyvuoto dokumento bus išspręsta per kelias sekundes, jei žurnale matysite įrašą „dinaminis XFA, sukonvertuotas, susieta laukų: 47, įspėjimų: 2“.

Įkelto XFA dokumento konvertavimas į standartinius laukus

Konvertavimas atliekamas su jau atmintyje esančiu dokumentu. Metodas FlattenLoadedXFA išanalizuoja XFA šabloną ir jo duomenų paketus, suformuoja puslapio struktūrą ir atkuria ją kaip „AcroForm“ laukus tikruose PDF puslapiuose:

var
  Pdf: THotPDF;
  MappedCount, I: Integer;
  Warnings: TStrings;
begin
  Pdf := THotPDF.Create(nil);
  try
    Pdf.LoadFromFile('dynamic_xfa.pdf');
    MappedCount := Pdf.FlattenLoadedXFA(True);   // True = fields stay editable
    Warnings := Pdf.XFAFlattenWarnings;
    for I := 0 to Warnings.Count - 1 do
      Log('XFA flatten warning: ' + Warnings[I]); // unmapped elements
    Pdf.SaveLoadedDocument('native_acroform.pdf');
    Log(Format('Mapped %d fields', [MappedCount]));
  finally
    Pdf.Free;
  end;
end;

Grąžinama reikšmė ir įspėjimų sąrašas yra svarbi informacija, o ne derinimo (debug) pranešimai, todėl išsaugokite juos abu. Konvertavimo metu natūraliai prarandama dalis informacijos: XFA skriptai, skaičiuojami laukai ir dinaminės poformės neturi atitikmenų „AcroForm“ aplinkoje, o XFAFlattenWarnings nurodo kiekvieną šablono elementą, kurio nepavyko susieti. Suarchyvavus konvertuotą failą be įspėjimų sąrašo, vėliau galite susidurti su tuščiais laukais dokumento kopijoje ir nežinoti to priežasties. Požymis Editable nurodo, ar nauji laukai išliks užpildomi. Perduokite True, jei naudotojai toliau dirbs su šia forma, arba užrakinkite reikšmes, jei tikslas yra sukurti nekintamą dokumento kopiją.

Konvertavimo patikra susideda iš vizualinės ir struktūrinės dalies. Struktūrinė dalis paprasta: patikrinkite, ar laukų skaičius sutampa su MappedCount reikšme. Vizualinis tikrinimas leidžia pastebėti tikruosius neatitikimus. Atidarykite pradinį dokumentą programoje „Acrobat“ (kuri vis dar naudoja XFA variklį) šalia konvertuoto failo paprastoje peržiūros programoje ir palyginkite reikšmes bei išdėstymą bent viename užpildytame pavyzdyje. Data, kurią XFA rodė kaip 2026-06-11, „AcroForm“ kopijoje gali atsirasti kaip neapdorota, nesuformatuota reikšmė, ir tik vizualus patikrinimas leis tai pastebėti.

Kai įvestis yra XDP paketas

Ne visi darbai prasideda nuo užpildyto PDF failo. Kartais XDP paketą gaunate atskirai (pavyzdžiui, eksportuotą iš formų kūrimo įrankio ar perduotą iš partnerių sistemos). Metodas ApplyXFAAsAcroForm leidžia praleisti failo įkėlimo etapą ir pritaikyti paketą tiesiai dabartiniam dokumentui:

XDPBytes := TFile.ReadAllBytes('benefit-claim.xdp');
MappedCount := Pdf.ApplyXFAAsAcroForm(XDPBytes, True);

Šie metodai gali būti naudojami ir priešinga kryptimi, kai reikia generuoti XFA struktūrą. Metodas AddXFAPacket prideda atskirus paketus, tokius kaip 'xdp' arba 'config'. Metodas SetXFADocument įrašo pilną vieno srauto turinį vienu iškvietimu. Metodas ClearXFAPackets išvalo registraciją, kad galėtumėte pradėti iš naujo, o AddXFASignaturePacket įterpia XAdES duomenis, skirtus pasirašyti XML formos duomenis tiesiogiai. XFA kūrimas šiuo metu yra išskirtinis poreikis, dažniausiai nulemtas pasenusių sistemų reikalavimų, tačiau šie metodai leidžia tai išspręsti konfigūracijos nustatymais be papildomų įrankių.

Kita sąvokos „flatten“ reikšmė

Sąvoka „flatten“ (suliejimas) dažnai sukelia nesusipratimų, nes ji gali reikšti visiškai kitą operaciją: interaktyvių „AcroForm“ laukų išvaizdos įrašymą tiesiai į puslapio turinio srautą, pašalinant visus interaktyvius objektus. Šiuo metu „HotPDF“ neturi tam skirtos API, ir tai svarbu žinoti dar prieš pradedant projektą. Vietoj to biblioteka leidžia užrakinti laukus jų kūrimo metu, naudojant dokumento teises (permissions):

// Lock the value at field creation: read-only text field
Pdf.CurrentPage.AddTextField('CaseNumber', 'BC-2026-0117',
  Rect(50, 700, 220, 720), 0, [ffReadOnly]);

// Belt and suspenders: restrict form filling document-wide
Pdf.ActivateProtection := True;
Pdf.CryptKeyLength := aes256;
Pdf.OwnerPassword := 'records-owner';
Pdf.ProtectOptions := [prPrint, prInformationCopy, prExtractContent];
// fill permission withheld: prFillAnnotations is absent from the set

Svarbu suprasti, ką tai suteikia ir ko ne. Tik nuskaitomas (read-only) laukas vis tiek išlieka formos objektu. Jis rodomas peržiūros programos laukų skydelyje, jo reikšmė yra nuskaitoma per formos API, o failą redaguojantys įrankiai gali vėl pašalinti šį požymį. Teisių nustatymai padidina saugumą, tačiau priklauso nuo to, ar peržiūros programa nusprės jų laikytis (šį apribojimą aiškiai nurodo ISO 32000-1). Jei reikalaujama, kad suarchyvuotame dokumente nebūtų jokių formos objektų, geriausias sprendimas su „HotPDF“ yra sugeneruoti dokumentą iš naujo: nuskaityti reikšmes ir nupiešti jas kaip įprastą tekstą su TextOut naujame puslapyje, užuot bandžius suliejimą pakeisti tik nuskaitomais laukais. Naudojant teisių apribojimus, atminkite, kad CryptKeyLength turi būti nustatytas prieš kviečiant BeginDoc; daugiau apie tai rasite straipsnyje apie AES-256 šifravimą ir teises.

Ką XFA reiškia dokumentų archyvavimui

Tiek PDF/A, tiek PDF/X standartai visiškai atmeta XFA naudojimą. Todėl dokumentų apdorojimo procese prieš suarchyvuojant juos pagal ISO 19005 reikalavimus būtina atlikti konvertavimą tokia tvarka: failo įkėlimas, FlattenLoadedXFA, išsaugojimas ir tik tada archyvinio failo generavimas bei validacija gautam „AcroForm“ rezultatui. Nelaikykite konvertavimo atitikties įrodymu. Tai tik pakeičia formos modelį, tačiau palieka šriftus, spalvas ir metaduomenis taisyklingus, todėl prieš pasitikėdami rezultatu patikrinkite jį su „veraPDF“. Kai forma konvertuojama į „AcroForm“, jos elgseną valdo kiti nustatymai. „JavaScript“ paleidikliai, pateikimo (submit) veiksmai ir patikros skriptai yra aprašyti straipsnyje apie „HotPDF“ AcroForm laukus ir veiksmus.

Čia pristatyti XFA registracijos, konvertavimo ir formų kūrimo metodai yra įtraukti į „Delphi“ bei „C++Builder“ skirtą HotPDF Component, kurio dokumentacijoje aprašytos visos naujausios XFA funkcijų galimybės.