HotPDF exporte et importe les annotations PDF au format XFDF via deux fonctions qui agissent sur le document actuellement chargé, ExportLoadedAnnotationsToXFDF et ImportLoadedAnnotationsFromXFDF. XFDF is le format XML d'échange d'annotations standardisé sous la norme ISO 19444-1, et ce binôme permet à un programme Delphi ou C++Builder de transmettre ses commentaires à Acrobat ou à un outil de révision tiers et d'en récupérer les résultats annotés, le tout sans réécrire le contenu de la page sur lequel reposent les annotations
Imaginez les deux directions que cela résout. Un réviseur ouvre votre rapport généré dans Acrobat, place une flèche rouge sur une figure mal alignée, entoure un total erroné et rédige une note dans la marge, puis exporte les commentaires dans un petit fichier XFDF. Ou l'inverse : votre programme produit lui-même les annotations et vous devez les transmettre à une personne dont l'outil n'est pas HotPDF. Dans les deux cas, les annotations transitent sous forme de XML que les deux parties comprennent, et les pages PDF restent identiques au bit près
Quelle est la différence entre FDF et XFDF ?
FDF et XFDF transportent la même charge utile dans deux syntaxes différentes, et cette distinction importe dès que vous décidez du fichier à transmettre à un autre outil. Le FDF est l'ancien format Forms Data Format défini au sein de la spécification PDF elle-même : il utilise la syntaxe des objets PDF, ainsi, un fichier FDF ressemble à un PDF allégé et nécessite un analyseur compatible PDF pour être lu. L'XFDF est la transcription XML de ces mêmes données, standardisée de manière indépendante sous la norme ISO 19444-1, ce qu'il convient de noter car cela signifie que toute bibliothèque XML sur n'importe quelle plateforme peut l'ouvrir, le comparer ou le générer. Les deux formats peuvent transporter des valeurs de champs de formulaire dans une arborescence <fields>, régie par la clause 6.3 de l'ISO 19444-1, et des annotations dans une arborescence <annots> ; HotPDF sépare ces responsabilités, en acheminant les données de formulaire via ExportLoadedFormToXFDF et en réservant ExportLoadedAnnotationsToXFDF pour la partie <annots>. Lorsque vous échangez des commentaires avec un service Web, un serveur de révision Java ou un script, l'XFDF est le format qui évite à l'autre partie d'avoir à intégrer un analyseur PDF
Comment exporter des annotations PDF au format XFDF dans Delphi ?
HotPDF exporte les annotations en parcourant chaque page du document chargé, en émettant un élément XFDF pour chaque annotation prise en charge, et renvoie le nombre d'annotations écrites. Chargez d'abord le PDF, puis appelez ExportLoadedAnnotationsToXFDF avec un chemin cible. Le résultat entier correspond au nombre d'annotations sérialisées ; un résultat inférieur ou égal à zéro signifie que rien n'a été exporté et qu'aucun fichier n'a été écrit, vous indiquant que le document ne comportait aucune annotation d'un sous-type pris en charge
L'XFDF généré est du XML simple et lisible. HotPDF écrit une racine <xfdf> dans l'espace de noms de l'ISO 19444-1, un conteneur <annots>, et un enfant par annotation avec son index de page basé sur 0, sa couleur et sa géométrie comme attributs ou éléments enfants. Une ligne avec un remplissage jaune et une pointe de flèche ouverte, placée à côté d'un polygone rempli, se sérialise ainsi
<?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>Baseline looks off</contents-richtext>
</line>
<polygon page="0" color="#0000FF" interior-color="#CCE5FF">
<vertices>72,120;180,120;180,200;72,200</vertices>
</polygon>
</annots>
</xfdf>Comment les sous-types d'annotations s'associent aux éléments XFDF
Chaque sous-type d'annotation est associé à un élément ISO 19444-1 spécifique avec sa propre convention géométrique, et HotPDF respecte ces structures plutôt que d'en inventer de nouvelles. Les annotations de ligne comportent un attribut start et end contenant les deux paires de coordonnées d'extrémité, directement extraites du tableau L de l'annotation, tandis que les styles d'extrémité de ligne LE deviennent les attributs head et tail. Les annotations de polygones et de lignes brisées insèrent leur liste de points dans un élément enfant <vertices> sous forme de paires x,y séparées par des points-virgules, et non sous forme d'attribut, car un lecteur qui attend l'élément enfant ignorera silencieusement les points dissimulés ailleurs. Les annotations d'encre (ink), qui peuvent contenir plusieurs tracés distincts, intègrent un élément <inklist> avec un enfant <gesture> par tracé, garantissant qu'une signature à plusieurs tracés survive au transfert sous forme de gestes distincts plutôt que d'un bloc fusionné
Le texte enrichi, la couleur et le style de bordure subsistent parallèlement à la géométrie. Le corps en texte enrichi d'une note est écrit sous forme d'enfant <contents-richtext> ; le remplissage intérieur que le PDF stocke dans le tableau IC, la couleur à l'intérieur d'un cercle, d'un carré, d'un polygone ou d'une pointe de flèche et le remplissage d'une zone de caviardage, apparaissent sous forme d'attribut interior-color sous la forme #RRGGBB ; et la largeur de bordure, le motif de tirets et un effet de bordure nuageuse correspondent aux attributs width, dashes, style et intensity, pour qu'un appel avec contour nuageux s'affiche toujours comme tel à destination. HotPDF préserve également la fenêtre contextuelle associée à une annotation graphique, en important la géométrie de l'onglet contextuel ainsi que son état ouvert ou fermé dans le dictionnaire Popup de l'annotation, et prend en charge les états d'ouverture et de révision de l'annotation de texte, de sorte qu'un document révisé conserve non seulement ses tracés, mais aussi les métadonnées de flux de travail sur lesquelles s'appuient les réviseurs
Réimporter de l'XFDF sur un document chargé
HotPDF importe l'XFDF en analysant le XML, en créant une nouvelle annotation pour chaque élément via NewLoadedAnnotation, en l'associant à la page nommée par l'élément, et renvoie le nombre d'annotations ajoutées. Le flux de travail est symétrique de l'exportation : chargez le PDF de base, appelez ImportLoadedAnnotationsFromXFDF avec le fichier du réviseur, puis enregistrez le document chargé pour conserver les nouvelles annotations. Si le fichier est manquant ou si le XML ne peut être analysé, la fonction renvoie zéro et le document chargé reste inchangé
Chaque élément XFDF spécifiant son index de page, les annotations se positionnent sur les pages pour lesquelles elles ont été conçues, même si vous importez plusieurs fichiers successivement. Cela permet de regrouper les commentaires de plusieurs réviseurs sur le même document chargé avant de procéder à un enregistrement unique. L'exemple ci-dessous fusionne les contributions de deux réviseurs en une seule copie. Pour créer et modifier les objets d'annotations directement en code plutôt que sous forme de fichiers d'échange, consultez la manière dont HotPDF crée et modifie les objets d'annotations PDF directement depuis 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;Chaque élément XFDF spécifiant son index de page, les annotations se positionnent sur les pages pour lesquelles elles ont été conçues, même si vous importez plusieurs fichiers successivement. Cela permet de regrouper les commentaires de plusieurs réviseurs sur le même document chargé avant de procéder à un enregistrement unique. L'exemple ci-dessous fusionne les contributions de deux réviseurs en une seule copie. Pour créer et modifier les objets d'annotations directement en code plutôt que sous forme de fichiers d'échange, consultez la manière dont HotPDF crée et modifie les objets d'annotations PDF directement depuis Delphi
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;Ce qui effectue un aller-retour propre, et ce qui ne le fait pas
HotPDF gère l'aller-retour des sous-types d'annotations pris en charge par l'ISO 19444-1, et ignore délibérément les autres plutôt que d'émettre un élément qu'un lecteur interpréterait mal. Le jeu pris en charge englobe les types de balisage prépondérants dans les tâches de révision réelles : notes de texte, texte libre, ligne, carré, cercle, polygone, ligne brisée, les quatre types de balisage de texte (surlignement, soulignement, barré et ondulation), tampon, encre (ink) et accent circonflexe (caret), ainsi que les pièces jointes, le son, le caviardage et les liens, soit dix-huit sous-types au total. Une annotation dont le sous-type ne figure pas dans cette liste est ignorée lors de l'exportation et, comme elle est omise plutôt qu'écrite vide, elle n'augmente pas le décompte renvoyé par la fonction
Le texte enrichi constitue la seule réserve. HotPDF préserve le corps <contents-richtext> afin que le texte stylisé et le contenu brut effectuent le transfert, mais l'XFDF transporte le texte et le balisage de style d'un commentaire, et non un flux d'apparence rendu. L'application réceptrice redessine donc la fenêtre contextuelle avec ses propres polices et sa propre mise en page plutôt que de reproduire au pixel près le rendu de HotPDF. Considérez cet aller-retour comme fidèle au contenu et à l'intention, non au rendu à l'écran. Si votre contenu stylisé réside dans des données de formulaire XFA plutôt que dans des flux d'annotations, les règles diffèrent, et l'article sur la manière dont HotPDF gère l'exData XFA, le texte enrichi et les hyperliens traite de ce chemin distinct
HotPDF applique les règles d'échappement de la clause 5.8.2 de l'ISO 19444-1 lorsqu'il écrit du texte, en encodant les caractères significatifs en XML et les octets de contrôle pour qu'un commentaire contenant une esperluette, un chevron ou un saut de ligne génère un XML bien formé que tout analyseur conforme accepte, et il applique les règles inverses à l'importation. C'est pourquoi une note collée depuis un tableur, avec sa ponctuation, revient intacte au lieu de corrompre le fichier
L'échange d'annotations est une facette des possibilités offertes par l'API des documents chargés, et s'associe au reste : importez le fichier XFDF d'un réviseur, ajustez les pages ou modifiez les métadonnées du document, aplatissez ou redéfinissez les autorisations du fichier, puis exportez un nouvel XFDF pour l'étape suivante. Tout cela est inclus dans le composant HotPDF standard pour Delphi et C++Builder, dont la référence documente la couverture complète des sous-types d'annotations et les fonctions XFDF de données de formulaire associées