Import a export PDF anotací jako XFDF v Delphi

HotPDF exportuje a importuje PDF anotace jako XFDF prostřednictvím dvou funkcí, které působí na aktuálně načtený dokument: `ExportLoadedAnnotationsToXFDF` a `ImportLoadedAnnotationsFromXFDF`. XFDF je XML formát pro výměnu anotací standardizovaný jako ISO 19444-1, a tato dvojice umožňuje programu v Delphi nebo C++Builderu předat své komentáře Acrobat nebo nástroji pro recenze třetí strany a získat zpět označené výsledky, to vše bez přepisu obsahu stránky, na které anotace sedí

Představte si dva směry, které to řeší. Recenzent otevře váš vygenerovaný report v programu Acrobat, umístí červenou šipku na špatně zarovnaný obrázek, zakroužkuje nesprávný celkový součet a napíše poznámku na okraj, načež exportuje komentáře do malého souboru XFDF. Nebo naopak: váš program sám vygeneruje označení a vy je potřebujete poslat někomu, jehož nástrojem není HotPDF. V obou případech anotace putují jako XML, kterému obě strany rozumí, a stránky PDF zůstávají bajt po bajtu stejné, jaké byly

Jaký je rozdíl mezi FDF a XFDF?

FDF a XFDF přenášejí stejná data ve dvou různých syntaxích a tento rozdíl je důležitý v momentě, kdy se rozhodujete, který soubor předáte jinému nástroji. FDF je starší formát Forms Data Format definovaný přímo ve specifikaci PDF: používá syntaxi objektů PDF, takže soubor FDF vypadá jako ořezané PDF a ke čtení vyžaduje analyzátor rozumějící PDF. XFDF je XML vyjádřením stejných dat, standardizovaným nezávisle jako ISO 19444-1, což znamená, že jej může otevřít, porovnat (diff) nebo vygenerovat jakákoli knihovna XML na jakékoli platformě. Oba formáty mohou nést hodnoty polí formuláře ve stromu ``, který se řídí článkem 6.3 normy ISO 19444-1, a anotace ve stromu ``. HotPDF tyto povinnosti rozděluje: data formulářů směruje přes `ExportLoadedFormToXFDF` a `ExportLoadedAnnotationsToXFDF` vyhrazuje pro stranu ``. Když si vyměňujete komentáře s webovou službou, serverem pro recenze v Javě nebo skriptem, XFDF is the XML expression of that same data, which means any XML library on any platform can open it, diff it or generate it. Both formats can carry form field values in a `` tree, which ISO 19444-1 clause 6.3 governs, and annotations in an `` tree; HotPDF splits those responsibilities, routing form data through `ExportLoadedFormToXFDF` and reserving `ExportLoadedAnnotationsToXFDF` for the `` side. Když si vyměňujete komentáře s webovou službou, serverem pro recenze v Javě nebo skriptem, XFDF je formát, který nenutí druhou stranu integrovat PDF analyzátor

Jak exportovat PDF anotace jako XFDF v Delphi?

HotPDF exportuje anotace procházením každé stránky načteného dokumentu, přičemž pro každou podporovanou anotaci vygeneruje jeden prvek XFDF a vrátí počet zapsaných anotací. Nejprve načtěte PDF a poté zavolejte `ExportLoadedAnnotationsToXFDF` s cílovou cestou. Celočíselný výsledek je počet serializovaných anotací; výsledek rovný nule nebo menší znamená, že nebylo exportováno nic a nebyl zapsán žádný soubor, což je vaším signálem, že dokument neobsahoval žádné anotace podporovaného podtypu

var
  Pdf: THotPDF;
  Written: Integer;
begin
  Pdf := THotPDF.Create(nil);
  try
    if Pdf.LoadFromFile('report-reviewed.pdf', '') > 0 then
    begin
      // Zapsat jeden prvek XFDF na podporovanou anotaci na každé stránce
      Written := Pdf.ExportLoadedAnnotationsToXFDF('comments.xfdf');
      if Written <= 0 then
        ShowMessage('No supported annotations were found');
    end;
  finally
    Pdf.Free;
  end;
end;

XFDF, které vyjde, je prosté, čitelné XML. HotPDF zapisuje kořen `` v jmenném prostoru ISO 19444-1, kontejner `` a jednoho potomka pro každou anotaci s jejím indexem stránky od nuly, barvou a geometrií jako atributy nebo dceřinými prvky. Čára se žlutou výplní a otevřeným hrotem šipky ležící vedle vyplněného polygonu se serializuje následovně:

<?xml version="1.0" encoding="UTF-8"?>
<xfdf xmlns="http://ns.adobe.com/xfdf/">
  <annots>
    <line page="0" start="72,700" end="220,700"
          color="#FF0000" interior-color="#FFFF00"
          head="OpenArrow" tail="None">
      <contents-richtext>Základní čára vypadá posunutě</contents-richtext>
    </line>
    <polygon page="0" color="#0000FF" interior-color="#CCE5FF">
      <vertices>72,120;180,120;180,200;72,200</vertices>
    </polygon>
  </annots>
</xfdf>

Jak se podtypy anotací mapují na prvky XFDF

Každý podtyp anotace se mapuje na konkrétní prvek ISO 19444-1 s vlastní konvencí geometrie a HotPDF tyto struktury dodržuje, místo aby si vymýšlelo vlastní. Čárové anotace nesou atributy `start` a `end` obsahující dvě dvojice souřadnic koncových bodů, převzaté přímo z pole anotace `L`, zatímco styly zakončení čáry `LE` se stávají atributy `head` a `tail`. Polygonové a polyline anotace přesouvají svůj seznam bodů do dceřiného prvku `` jako dvojice `x,y` oddělené středníkem, nikoli jako atribut, protože čtečka, která dceřiný prvek očekává, tiše zahodí body skryté kdekoli jinde. Inkoustové anotace (ink), které mohou obsahovat několik samostatných tahů, vnořují prvek `` s jedním dceřiným prvkem `` pro každý tah, takže podpis s více tahy přežije cestu jako samostatná gesta, a nikoli jako jedna sloučená skvrna

Formátovaný text (rich text), barva a styl ohraničení přežívají spolu s geometrií. Tělo poznámky s formátovaným textem se zapisuje jako dceřiný prvek ``; vnitřní výplň, kterou PDF ukládá v poli `IC` (barva uvnitř kruhu, čtverce, polygonu nebo hrotu šipky a výplň redakčního pole), se přenáší jako atribut `interior-color` ve formátu `#RRGGBB`; a šířka ohraničení, vzor čárek a efekt oblačného ohraničení (cloudy) se mapují na atributy `width`, `dashes`, `style` a `intensity`, takže popisek s oblačným obrysem se na druhém konci stále zobrazuje jako oblačný. HotPDF také zachovává vyskakovací okno (popup) připojené k označené anotaci, přičemž geometrii vyskakovacího prvku a jeho otevřený či zavřený stav importuje do slovníku anotace `Popup`, a přenáší otevřené a recenzní stavy textových anotací, takže recenzovaný dokument si zachovává nejen své tvary, ale i metadata pracovního postupu (workflow), na která se recenzenti spoléhají

Import XFDF zpět do načteného dokumentu

HotPDF importuje XFDF analýzou XML, vytvořením nové anotace pro každý prvek prostřednictvím `NewLoadedAnnotation`, jejím připojením ke stránce, kterou prvek pojmenovává, a vrácením počtu přidaných anotací. Pracovní postup je symetrický s exportem: načtěte výchozí PDF, zavolejte `ImportLoadedAnnotationsFromXFDF` se souborem recenzenta a poté uložte načtený dokument, aby se nová označení uložila. Pokud soubor chybí nebo XML nelze analyzovat, funkce vrátí nulu a načtený dokument zůstane nedotčen

Vzhledem k tomu, že každý prvek XFDF pojmenovává svůj vlastní index stránky, anotace přistanou na stránkách, pro které byly vytvořeny, i když importujete několik souborů za sebou, což umožňuje bezpečně shromáždit komentáře od více než jednoho recenzenta do stejného načteného dokumentu před jediným uložením. Níže uvedený příklad spojuje dva recenzenty do jedné sloučené kopie. Pro vytváření a úpravu samotných objektů anotací v kódu, spíše než pro jejich výměnu jako souborů, se podívejte na to, jak HotPDF vytváří a upravuje objekty anotací PDF přímo z Delphi

var
  Pdf: THotPDF;
  Added: Integer;
begin
  Pdf := THotPDF.Create(nil);
  try
    if Pdf.LoadFromFile('report.pdf', '') > 0 then
    begin
      Added := Pdf.ImportLoadedAnnotationsFromXFDF('comments.xfdf');
      if Added > 0 then
        Pdf.SaveLoadedDocument('report-annotated.pdf');
    end;
  finally
    Pdf.Free;
  end;
end;

Protože každý XFDF prvek nese index své stránky, anotace se dostanou na správná místa i při importu více souborů za sebou. Následující příklad slučuje dva recenzní soubory do jednoho dokumentu:

var
  Pdf: THotPDF;
  Total, I: Integer;
  Files: array[0..1] of string;
begin
  Files[0] := 'alice-comments.xfdf';
  Files[1] := 'bob-comments.xfdf';
  Pdf := THotPDF.Create(nil);
  try
    if Pdf.LoadFromFile('master.pdf', '') > 0 then
    begin
      Total := 0;
      for I := Low(Files) to High(Files) do
        Inc(Total, Pdf.ImportLoadedAnnotationsFromXFDF(Files[I]));
      if Total > 0 then
        Pdf.SaveLoadedDocument('master-merged.pdf');
    end;
  finally
    Pdf.Free;
  end;
end;

Co prochází obousměrným přenosem čistě a co ne

HotPDF přenáší oběma směry podtypy anotací, kterým dává ISO 19444-1 domov, a zbytek záměrně přeskakuje, místo aby emitovalo něco, co by si čtečka mohla špatně vyložit. Podporovaná sada zahrnuje typy označení, které dominují skutečné recenzní práci: textové poznámky, volný text, čáry, čtverce, kružnice, polygony, polylines, čtyři typy označení textu (zvýraznění, podtržení, přeškrtnutí a vlnovka), razítka, inkoust a stříšky, plus přílohy souborů, zvuk, redakce a odkazy — celkem osmnáct podtypů. Anotace, jejíž podtyp nespadá do tohoto seznamu, je při exportu vynechána, a protože je přeskočena, a nikoli zapsána prázdná, nezvyšuje počet, který funkce vrací

Formátovaný text je upřímným upozorněním. HotPDF zachovává tělo ``, takže formátovaný text i prostý obsah projdou cestu v pořádku, avšak XFDF přenáší text komentáře a jeho styl, nikoli vykreslený vzhledový tok (appearance stream), takže přijímající aplikace vykreslí vyskakovací okno s vlastními písmy a rozvržením, místo aby reprodukovala přesné pixely z HotPDF. Považujte obousměrný přenos za věrný obsahu a záměru, nikoli za vykreslování na obrazovce na úrovni pixelů. Pokud vaše formátované texty žijí v datech formuláře XFA spíše než v anotačních tocích, pravidla se liší a jak HotPDF zpracovává XFA exData, formátovaný text a hyperodkazy pokrývá tuto samostatnou cestu

Zpracování na úrovni znaků je přísnější, než se zdá, což je přesně to, co chcete. HotPDF při zápisu textu uplatňuje pravidla escapování dle článku 5.8.2 normy ISO 19444-1, přičemž kóduje významné znaky XML a kontrolní bajty, takže komentář obsahující ampersand, lomenou závorku nebo konec řádku produkuje správně formátované XML, které jakýkoli vyhovující analyzátor přijme, a při importu tatáž pravidla obrací. Proto se poznámka zkopírovaná z tabulky, včetně interpunkce, vrací neporušená, místo aby soubor poškodila

Výměna anotací je jednou částí toho, co API pro načtené dokumenty dělá, a doplňuje se se zbytkem: importujte XFDF recenzenta, upravte stránky nebo upravte metadata dokumentu, zploštěte soubor nebo upravte jeho oprávnění a poté exportujte čerstvé XFDF pro další kolo. To vše se dodává ve standardní komponentě HotPDF Component pro Delphi a C++Builder, jejíž referenční příručka dokumentuje kompletní pokrytí podtypů anotací a doprovodné funkce XFDF pro formulářová data