PDFium Component pre Delphi a Lazarus si vymieňa formulárové údaje a anotácie prostredníctvom formátu XFDF, XML výmenného formátu definovaného normou ISO 19444-1. Metóda TPdf.ExportXFDF serializuje každú hodnotu formulárového poľa a každú podporovanú anotáciu v načítanom dokumente do súboru XFDF alebo prúdu TStream; metóda TPdf.ImportXFDF načíta dokument XFDF späť, pričom znovu vytvorí anotácie na ich stránkach a aplikuje hodnoty polí. Tento prechod tam a späť pokrýva dva pracovné postupy, ktoré nakoniec potrebuje každá dokumentová aplikácia: posudzovateľ pridá poznámky do PDF v programe Acrobat a pošle vám komentáre na zlúčenie, alebo pravidlo zhody vyžaduje, aby údaje formulárov žili v samostatnom, porovnateľnom a auditovateľnom súbore namiesto toho, aby boli zapečené priamo v PDF
Podporuje PDFium import a export XFDF?
Samotná knižnica PDFium to nepodporuje. Natívne C API neobsahuje vôbec žiadne funkcie pre XFDF ani FDF — nič v jeho verejných hlavičkových súboroch nečíta ani nezapisuje tieto formáty, takže žiadne balenie (wrapping) vás k nim nedostane. PDFium Component preto implementuje celý engine XFDF priamo v Pascale, vo vyhradenej jednotke, ktorá vytvára a analyzuje XML nad existujúcim dátovým modelom anotácií a formulárových polí triedy TPdf. Zapisovač generuje XML ručne a čítač je ručne napísaný stavový parser, takže táto funkcia nepridáva žiadnu závislosť na jednotkách Delphi XMLDoc ani FPC DOM a správa sa rovnako v Delphi aj v Lazaruse
Toto rozhodnutie o návrhu je dôležité pri vyhodnocovaní alternatív. Ak ste doteraz z Pascalu volali čisté funkcie FPDF_*, XFDF je pre vás prekážkou: táto schopnosť v DLL súbore jednoducho chýba. Komponent túto prekážku prekonáva tým, že s XFDF zaobchádza ako s čistým problémom serializácie — zhromaždí hodnoty polí a záznamy anotácií, ktoré už wrapper dokáže prečítať, zapíše ich ako štandardné XML a pri importe tento proces obráti
Čo obsahuje súbor XFDF?
Čo obsahuje súbor XFDF?
Norma ISO 19444-1 definuje XFDF ako XML reprezentáciu FDF a jeho obsah sa delí na dva hlavné bloky. Element <fields> nesie hierarchické názvy formulárových polí a ich hodnoty — všetko, čo používateľ zadal, vybral alebo začiarkol v AcroFormulári. Element <annots> nesie anotácie: metóda TPdf.ExportXFDF generuje 18 subtypov — text, highlight (zvýraznenie), underline (podčiarknutie), strikeout (prečiarknutie), squiggly (vlnovka), line (čiara), circle (kruh), square (štvorec), caret, polygon, polyline, stamp (pečiatka), ink (pero), freetext, fileattachment (príloha), sound (zvuk), link (odkaz) a redact (redigovanie). Anotácie typu Widget v elemente <annots> zámerne chýbajú, pretože ich dáta sa prenášajú v elemente <fields>, a interné subtypy prehliadača ako Popup nie sú súčasťou slovníka XFDF
Pre zabezpečenie vernosti prenosu bol záznam TPdfAnnotation rozšírený o metadáta, ktoré XFDF očakáva: Name (unikátny identifikátor NM), Subject (predmet), ModificationDate (dátum úpravy), CreationDate (dátum vytvorenia), Icon (ikona), Opacity (priehľadnosť), koncové body čiar, vrcholy polygónov a polylínií a cesty kreslenia perom (ink gesture paths). Každé nové pole sa páruje s logickým (boolean) prepínačom Has*, takže kód zostavený pre staršie verzie sa naďalej bez problémov kompiluje a produkuje rovnaké slovníky — nenastavené pole sa nikdy nezapíše. Ak už anotácie vytvárate programovo, rovnaký záznam, aký používate na textové anotácie so súradnicovými bodmi (quad points), teraz nesie všetko, čo XFDF potrebuje
Ako exportovať formulárové údaje a anotácie do XFDF?
Jedno volanie spracuje celý dokument. Načítajte PDF s povoleným vypĺňaním formulárov, zavolajte ExportXFDF, a komponent prejde každú stránku, zhromaždí hodnoty polí a anotácie a zapíše XML. Návratovou hodnotou je počet zapísaných bajtov v kódovaní UTF-8, čo poslúži ako jednoduchá kontrola v denníkoch (logs)
var
Pdf: TPdf;
Bytes: Integer;
begin
Pdf := TPdf.Create(Self);
Pdf.FormFill := True; // needed so field values are live
Pdf.FileName := 'expense-report.pdf';
Pdf.Active := True;
Bytes := Pdf.ExportXFDF('expense-report.xfdf');
ShowMessage(Format('%d bytes of XFDF written', [Bytes]));
end;Oba smery majú preťaženie pre prúd TStream, takže nič vás nenúti vytvárať dočasný súbor na disku. Export do TMemoryStream je ideálnym riešením, ak XFDF smeruje do HTTP odpovede, databázového stĺpca typu blob alebo do komprimovaného archívu
var
Buffer: TMemoryStream;
begin
Buffer := TMemoryStream.Create;
try
Pdf.ExportXFDF(Buffer); // same XML, no file involved
Buffer.Position := 0;
// hand the stream to a web response, blob column, or zip entry
finally
Buffer.Free;
end;
end;Ako ImportXFDF zlučuje komentáre späť do dokumentu?
Strana importu uzatvára pracovný postup posudzovateľa. Kolega označí zmluvy v programe Acrobat, exportuje komentáre ako XFDF a pošle vám niekoľko kilobajtov XML namiesto druhej kópie PDF. Metóda TPdf.ImportXFDF analyzuje tento súbor, vytvorí každú anotáciu na stránke, ktorú určuje atribút page, a zapíše hodnoty polí do zodpovedajúcich interaktívnych anotácií (widgets). Funkcia vracia kombinovaný počet aplikovaných polí a anotácií, so používateľské rozhranie môže presne potvrdiť, koľko zmien pribudlo
var
Applied: Integer;
begin
Applied := Pdf.ImportXFDF('review-comments.xfdf');
StatusBar.SimpleText :=
Format('%d fields and annotations merged', [Applied]);
end;Parser je ručne napísaný skener tagov navrhnutý pre toleranciu a nie pre prísnosť: neznáme prvky sa preskakujú, inštrukcie na spracovanie, deklarácie DOCTYPE a komentáre sa ignorujú, nerozpoznané názvy príznakov sa zahadzujú a hodnoty atribútov sa dekódujú cez kompletnú sadu XML entít a číselných znakových referencií, vrátane párov UTF-16. XFDF vyprodukované Acrobatom, webovým prehliadačom alebo iným nástrojom sa zlúči bez akýchkoľvek komplikácií. Po prenesení anotácií do dokumentu pokračuje cyklus posudzovania s využitím aparátu odpovedí a stavov popísaných v zostavení procesu posudzovania anotácií s PDFium Component, pričom importované hodnoty polí sa zapájajú do bežnej logiky navigácie tabulátorom opísanej v navigácii vo formulárových poliach
Prečo pri XFDF záleží na desatinných oddeľovačoch?
Každá anotácia v XFDF je pozicionovaná pomocou reťazcov súradníc — napríklad rect="70.5,540,200,560" — a norma ISO 19444-1 vyžaduje ako desatinný oddeľovač bodku. Predvolené formátovanie čísel v Delphi sa riadi nastavením Windows (locale), so na slovenskom alebo nemeckom systéme by bežná funkcia FloatToStr premenila 70.5 na 70,5, čo poškodí čiarkami oddelený zoznam súradníc a premení ho na nepoužiteľný text, ktorý iné procesory odmietnu alebo nesprávne prečítajú. PDFium Component normalizuje každé číslo, ktoré zapisuje: desatinný oddeľovač systému sa prepíše na bodku a koncové nuly sa odrežú, takže exportovaný súbor je bajtovo identický bez ohľadu na to, či bol vygenerovaný na en-US alebo sk-SK počítači. Ak ste niekedy debugovali PDF nástroj, ktorý v kancelárii fungoval, ale u európskeho zákazníka zlyhal, stretli ste sa presne s touto kategóriou chýb — je dobré vedieť, že komponent ju rieši za vás
Aké sú limity prenosu tam a späť?
Dve obmedzenia je potrebné uviesť na rovinu. Po prvé, XFDF prenáša údaje o anotáciách, nie ich vykreslený vzhľad — prúdy vzhľadu (appearance streams) nie sú súčasťou formátu, takže prijímajúci prehliadač generuje vzhľad každej anotácie z jej vlastností. Zvýraznenie alebo obdĺžnik sa vykreslia správne všade; pečiatka s vlastným vzhľadom prejde na to, čo pre daný názov pečiatky nakreslí cieľový prehliadač. Po druhé, podkladové API PDFium obsahuje settery pre reťazce, no žiadne pre čísla anotácií ani geometriu ciest, so Opacity (priehľadnosť), koncové body čiar, vrcholy a pero (ink gestures) sú určené len na export: komponent ich pri zápise do XFDF zachová, ale pri importe ich nedokáže zapísať späť do PDF. Hodnoty polí, obsah, farby, obdĺžniky (rects), body quad points, dátumy a metadáta identity sa úspešne prenášajú v oboch smeroch
Pre rýchly začiatok sa v balíkoch ukážok pre Delphi, C++Builder a Lazarus dodáva príklad XfdfLab, ktorý prepája obe volania s tlačidlami nad akýmkoľvek otvoreným PDF. Podpora XFDF je súčasťou aktuálneho vydania komponentu PDFium Component, spolu s rozhraniami pre anotácie a formuláre, na ktorých stavia