XFDF:n vienti ja tuonti Delphissä PDFium-komponentilla

Delphin ja Lazaruksen PDFium-komponentti vaihtaa lomaketietoja ja huomautuksia XFDF-muodon avulla, joka on ISO 19444-1 -standardin määrittelemä XML-pohjainen vaihtomuoto. TPdf.ExportXFDF sarjallistaa jokaisen ladatun dokumentin lomakekentän arvon ja tuetun huomautuksen XFDF-tiedostoon tai TStream-virtaan. TPdf.ImportXFDF puolestaan lukee XFDF-dokumentin takaisin luoden huomautukset uudelleen omille sivuilleen ja asettaen kenttien arvot. Tämä edestakainen kierros kattaa kaksi työnkulkua, joita jokainen dokumenttisovellus aikanaan tarvitsee: tarkastaja merkitsee PDF:n Acrobatissa ja lähettää kommentit sinulle yhdistettäväksi, tai vaatimustenmukaisuussääntö edellyttää, että lomaketiedot on säilytettävä erillisessä, versioitavassa ja auditoitavassa tiedostossa sen sijaan, että ne upotettaisiin suoraan PDF-tiedostoon

Tukeeko PDFium XFDF:n tuontia ja vientiä?

Itse PDFium-kirjasto ei tue sitä. Alkuperäisessä C API:ssa ei ole lainkaan XFDF- tai FDF-funktioita – mikään sen julkisissa otsikkotiedostoissa ei lue tai kirjoita kumpaakaan muotoa, joten pelkkä kääriminen ei auta. PDFium-komponentti toteuttaa siksi koko XFDF-moottorin Pascalilla erillisessä yksikössä, joka rakentaa ja jäsentää XML:n suoraan olemassa olevan TPdf-huomautus- ja lomakekenttätietomallin päälle. Kirjoittaja tuottaa XML-koodin manuaalisesti ja lukija on käsin kirjoitettu tilakonejäsennin, joten ominaisuus ei tuo riippuvuuksia Delphin XMLDoc- tai FPC DOM -yksiköistä ja toimii identtisesti sekä Delphissä että Lazaruksessa

Tällä suunnitteluratkaisulla on merkitystä vaihtoehtoja arvioitaessa. Jos olet kutsunut suoraan FPDF_*-funktioita Pascalista, XFDF on kuin seinä vastassa: ominaisuutta ei yksinkertaisesti ole DLL-kirjastossa. Komponentti ylittää tämän esteen käsittelemällä XFDF:ää puhtaana sarjallistusongelmana – se kerää kenttien arvot ja huomautustiedot, jotka kääre osaa jo lukea, kirjoittaa ne standardina XML:nä ja tekee saman käänteisesti tuonnissa

Mitä XFDF-tiedosto sisältää?

ISO 19444-1 määrittelee XFDF:n FDF:n XML-esitykseksi, ja sen hyötykuorma jakautuu kahteen ylätason lohkoon. <fields>-elementti sisältää hierarkkiset lomakekenttien nimet ja niiden arvot – kaiken, mitä käyttäjä on AcroForm-lomakkeeseen kirjoittanut, valinnut tai ruksinut. <annots>-elementti sisältää huomautukset: TPdf.ExportXFDF vie 18 alityyppiä – text, highlight, underline, strikeout, squiggly, line, circle, square, caret, polygon, polyline, stamp, ink, freetext, fileattachment, sound, link ja redact. Widget-huomautukset puuttuvat tietoisesti <annots>-lohkosta, koska niiden tiedot kulkevat <fields>-lohkossa, eivätkä katseluohjelman sisäiset alityypit, kuten Popup, kuulu XFDF-sanastoon

Jotta edestakainen kierros olisi uskollinen, TPdfAnnotation-tietuetta laajennettiin XFDF:n odottamilla metatiedoilla: Name (yksilöllinen NM-tunniste), Subject, ModificationDate, CreationDate, Icon, Opacity, viivan päätepisteet, monikulmion ja murtoviivan kärkipisteet sekä vapaankäden piirtojen polut. Jokaisella uudella kentällä on boolean-tyyppinen Has*-vartija, joten aiemmilla versioilla luotu koodi kääntyy edelleen ja tuottaa samat sanakirjat – asettamatonta kenttää ei koskaan kirjoiteta. Jos luot merkintöjä ohjelmallisesti, sama tietue, jota käytät tekstimerkintöihin quad pointeilla, sisältää nyt kaiken mitä XFDF tarvitsee

Miten lomaketiedot ja huomautukset viedään XFDF-muotoon?

Yksi kutsu käsittelee koko dokumentin. Lataa PDF-tiedosto lomakkeiden täyttö käytössä, kutsu ExportXFDF-metodia, ja komponentti käy läpi jokaisen sivun, kerää kenttien arvot sekä huomautukset ja kirjoittaa XML-koodin. Palautusarvo on kirjoitettujen UTF-8-tavujen määrä, mikä toimii hyvänä perustarkistuksena lokeissa

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;

Molemmilla suunnilla on TStream-ylikuormitus, joten väliaikaistiedostoa ei tarvitse tallentaa levylle. Vienti TMemoryStream-virtaan on luonteva tapa, kun XFDF on matkalla HTTP-vastaukseen, tietokannan blob-sarakkeeseen tai allekirjoitettuun arkistomerkintään

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;

Miten ImportXFDF yhdistää kommentit takaisin dokumenttiin?

Tuontipuolella tarkastajan työnkulku sulkeutuu. Kollega tekee merkintöjä sopimukseen Acrobatissa, vie kommentit XFDF-muodossa ja lähettää sinulle muutaman kilotavun XML-tiedoston PDF:n toisen kopion sijasta. TPdf.ImportXFDF jäsentää tiedoston, luo kunkin huomautuksen sivulle, jonka sen page-attribuutti nimeää, ja kirjoittaa kenttien arvot vastaaviin widget-huomautuksiin. Funktio palauttaa sovellettujen kenttien ja huomautusten yhteismäärän, joten käyttöliittymä voi vahvistaa tarkalleen, kuinka paljon tietoa vastaanotettiin

var
  Applied: Integer;
begin
  Applied := Pdf.ImportXFDF('review-comments.xfdf');
  StatusBar.SimpleText :=
    Format('%d fields and annotations merged', [Applied]);
end;

Jäsennin on käsin kirjoitettu tagiskanneri, joka on rakennettu sallivaksi eikä tiukaksi: tuntemattomat elementit ohitetaan, prosessointiohjeet, DOCTYPE-määrittelyt ja kommentit jätetään huomiotta, tuntemattomat lippujen nimet jätetään pois ja attribuuttien arvot puretaan XML-entiteettien ja numeeristen merkkiviitteiden (mukaan lukien UTF-16-korvikeparit) avulla. Acrobatin, verkkokatseluohjelman tai muun työkalun tuottama XFDF yhdistyy ilman ylimääräisiä vaiheita. Kun huomautukset ovat dokumentissa, tarkastuskierto jatkuu vastaus- ja tilajärjestelmällä, joka on kuvattu artikkelissa huomautusten tarkastustyönkulun rakentamisesta PDFium-komponentilla, ja tuodut kenttäarvot osallistuvat normaaliin sarkainjärjestyksen logiikkaan, jota käsitellään artikkelissa lomakekentissä navigoinnista

Miksi desimaalierottimilla on väliä XFDF:ssä?

Jokainen huomautus sijoitetaan XFDF:ssä koordinaattimerkkijonojen – kuten rect="70.5,540,200,560" – avulla, ja ISO 19444-1 vaatii pisteen desimaalierottimeksi. Delphin oletusarvoinen liukulukujen muotoilu noudattaa Windowsin alueasetuksia, joten saksalaisessa tai ranskalaisessa järjestelmässä tavallinen FloatToStr muuttaa arvon 70.5 muotoon 70,5, mikä korruptoi pilkuilla erotetun koordinaattiluettelon roskaksi, jonka muut lukijat hylkäävät tai lukevat väärin. PDFium-komponentti normalisoi jokaisen kirjoittamansa luvun: lokaalin desimaalierotin korvataan pisteellä ja perässä olevat nollat karsitaan, joten viety tiedosto on tavuittain identtinen riippumatta siitä, onko se luotu en-US- vai de-DE-koneella. Jos olet koskaan jäljittänyt PDF-työkalun virhettä, joka toimi toimistolla mutta epäonnistui eurooppalaisella asiakkaalla, olet kohdannut juuri tämän virheluokan – on hyvä tietää, että komponentti hoitaa sen puolestasi

Mitkä ovat edestakaisen siirron rajoitukset?

Kaksi rajoitusta on syytä mainita suoraan. Ensinnäkin XFDF siirtää huomautustietoja, ei niiden piirrettyä ulkoasua – ulkoasuvirrat (appearance streams) eivät kuulu tiedostomuotoon, joten vastaanottava katseluohjelma luo kunkin huomautuksen ulkoasun uudelleen sen ominaisuuksien perusteella. Korostus tai neliö renderöityy oikein kaikkialla; mukautetun ulkoasun omaava leima palautuu siihen, mitä kohdekatseluohjelma piirtää kyseiselle leiman nimelle. Toiseksi, taustalla olevassa PDFium API:ssa on asetusfunktiot merkkijonoille, mutta ei huomautusnumeroille tai polkujen geometrialle, joten Opacity, viivojen päätepisteet, kärkipisteet ja vapaankäden piirrokset ovat vain vientiä varten: komponentti säilyttää ne uskollisesti kirjoittaessaan XFDF:ää, mutta ei voi kirjoittaa niitä takaisin PDF:ään tuonnin yhteydessä. Kenttien arvot, sisällöt, värit, suorakulmiot, quad pointit, päivämäärät ja identiteetin metatiedot kulkevat edestakisin molempiin suuntiin

Mitkä ovat edestakaisen siirron rajoitukset?

Käytännön aloitusta varten XfdfLab-esimerkki toimitetaan Delphin, C++Builderin ja Lazaruksen demopakettien mukana ja kytkee molemmat kutsut painikkeisiin minkä tahansa avaamasi PDF-tiedoston päällä. XFDF-tuki sisältyy PDFium-komponentin nykyiseen julkaisuun yhdessä sen huomautus- ja lomake-API:en kanssa