Un paragraphe qui commence en bas de la page 4 et se termine en haut de la page 5 reste un seul paragraphe pour le lecteur. Dans un PDF balisé, il vit dans deux flux de contenus, et chaque page numérote ses séquences de contenu marqué pour son propre compte, si bien que l'arbre de structure a besoin d'un unique élément P dont le tableau /K pointe, par exemple, vers le MCID 7 de la page 4 et le MCID 3 de la page 5. Dessinez vos pages avec du code de coordonnées et ajoutez le balisage après coup, et l'arbre de balises d'un vérificateur d'accessibilité affichera généralement deux paragraphes là où il n'y en avait qu'un, sans compter une série de titres de colonnes répétés dans les données de chaque tableau poursuivi
L'approche par coordonnées a un second coût, qui se manifeste plus tôt. La première version d'un rapport fonctionne. Puis une adresse client s'étale sur trois lignes, un titre localisé passe sur plusieurs lignes, un tableau gagne quarante lignes, et toute position y en aval devient fausse. Les vérifications de saut de page finissent éparpillées dans la logique métier, et un code qui n'a jamais connu que x et y ne sait pas où commence un paragraphe lorsque l'exigence d'accessibilité se présente deux ans plus tard
Construire un arbre de mise en page HotPDF en Delphi
HotPDF répond à ces deux problèmes avec un arbre de mise en page déclaratif hébergé dans l'unité HPDFLayoutDOM. Un THPDFDOMDocument contient des sections ; chaque THPDFDOMSection définit un format de page, des marges, un en-tête et un pied de page optionnels, et une pile Body dans laquelle vous ajoutez texte, titres, espacements, listes, images, conteneurs et tableaux. Rien dans l'arbre ne porte de coordonnée y. THPDFDOMRenderer mesure l'arbre, décide des sauts de page, dessine l'en-tête et le pied de chaque page et, comme GenerateStructure vaut True par défaut, écrit l'arbre de structure au fil du dessin
La propriété dans l'arbre est stricte. Le document possède ses sections, une section possède son corps, son en-tête et son pied de page, et les piles, conteneurs et tableaux possèdent leurs enfants ; Section.Body.Add(Table) confie donc le tableau définitivement. Un composant rattaché à deux parents serait mesuré deux fois sous des contraintes différentes et libéré deux fois au démontage. Les éléments répétés comme un bloc de signature proviennent donc de Clone, de SetHeaderClone / SetFooterClone, ou d'une fabrique enregistrée avec RegisterComponent, après quoi chaque appel à CreateComponent('signature') renvoie une instance fraîche
uses
SysUtils, HPDFDoc, HPDFLayoutDOM;
type
TAssetRow = record // votre propre type de données
Name, ServiceDate, Status: WideString;
end;
function BuildMaintenanceReport(const Assets: array of TAssetRow): THPDFDOMDocument;
var
Doc: THPDFDOMDocument;
Section: THPDFDOMSection;
Heading: THPDFDOMText;
Table: THPDFDOMTable;
Row: THPDFDOMTableRow;
I: Integer;
begin
Doc := THPDFDOMDocument.Create; // GenerateStructure = True, Language = 'en-US'
try
Section := Doc.AddSection; // A4 portrait, marges de 36 pt par défaut
Section.MarginLeft := 56;
Section.MarginRight := 56;
Section.Style.FontName := 'Helvetica';
Section.Style.FontSize := 10;
Section.Style.LineHeight := 13;
Section.Body.Style.Spacing := 6; // écart entre les enfants du corps
Section.Footer := THPDFDOMText.Create('Plant maintenance - internal');
Heading := Section.Body.AddHeading('Annual maintenance report', 1);
Heading.Style.FontSize := 18;
Heading.Style.LineHeight := 22; // LineHeight ne suit pas FontSize
Section.Body.AddText('Every asset inspected during the reporting ' +
'period is listed below, grouped by site.');
Table := THPDFDOMTable.Create('assets'); // RepeatHeaders vaut True par défaut
Table.AddColumn(3); // pondérations, pas des largeurs en points
Table.AddColumn(1);
Table.AddColumn(1);
Row := Table.AddRow(18, True); // les lignes d'en-tête doivent venir en premier
Row[0].Text := 'Asset';
Row[1].Text := 'Last service';
Row[2].Text := 'Status';
for I := 0 to High(Assets) do
begin
Row := Table.AddRow(16);
Row[0].Text := Assets[I].Name;
Row[1].Text := Assets[I].ServiceDate;
Row[2].Text := Assets[I].Status;
end;
Section.Body.Add(Table); // le corps possède le tableau à partir d'ici
Result := Doc;
except
Doc.Free;
raise;
end;
end;
Deux valeurs par défaut de ce listing piègent du monde. LineHeight vaut 12 points tant qu'aucun style de la chaîne ne le définit, quel que soit le FontSize ; un titre de 18 pt sans LineHeight propre se retrouve donc avec des lignes de 12 pt et chevauche le suivant. Et une ligne de tableau fait exactement la hauteur passée à AddRow : le texte d'une cellule tient sur une seule ligne, dimensionnez donc vos lignes pour la police choisie
Render ouvre et ferme le document lui-même
THPDFDOMRenderer.Render(Doc, Pdf) appelle BeginDoc sur la cible, rend chaque section, puis appelle EndDoc avant de revenir. Ne l'encadrez pas de votre propre paire BeginDoc / EndDoc. Tout ce qui doit être réglé avant le début du document se règle d'abord sur l'instance THotPDF : FileName, Title, et PDFUACompliance si la sortie doit revendiquer PDF/UA. Quand la génération de structure est active, Render active aussi EnableTaggedPDF et recopie Doc.Language dans Pdf.Lang si vous l'avez laissé vide
var
Doc: THPDFDOMDocument;
Pdf: THotPDF;
Renderer: THPDFDOMRenderer;
Stats: THPDFDOMRenderStatistics;
begin
Doc := BuildMaintenanceReport(Assets);
Pdf := THotPDF.Create(nil);
Renderer := THPDFDOMRenderer.Create;
try
Pdf.FileName := 'maintenance-report.pdf';
Pdf.Title := 'Annual maintenance report';
Pdf.PDFUACompliance := True; // active aussi la vérification du texte alternatif des figures
// Pas de BeginDoc / EndDoc ici : Render ouvre et ferme le document
Stats := Renderer.Render(Doc, Pdf);
Writeln(Format('%d page(s), %d placement(s), %d split(s)',
[Stats.PageCount, Stats.PlacementCount, Stats.SplitCount]));
Writeln(Format('structure elements=%d marked content=%d artifacts=%d',
[Stats.StructureElementCount, Stats.MarkedContentCount,
Stats.ArtifactCount]));
Writeln(Format('header draws=%d footer draws=%d deepest chain=%d',
[Stats.HeaderDrawCount, Stats.FooterDrawCount,
Stats.MaximumContinuationDepth]));
finally
Renderer.Free;
Doc.Free;
Pdf.Free;
end;
end;
Journalisez l'enregistrement de statistiques à chaque exécution, car il révèle des régressions de gabarit qui ne lèvent jamais d'exception. Un SplitCount qui bondit après un changement de gabarit signifie généralement qu'un composant se mesure désormais plus haut que l'espace qu'il occupait auparavant. Un MaximumContinuationDepth qui grimpe progressivement désigne un composant dont le Split déplace trop peu de contenu par page. ArtifactCount couvre les en-têtes et pieds de page, les bordures décoratives comme le cadre de 0,5 pt par défaut des tableaux et les lignes d'en-tête répétées ; comparez-le donc entre des exécutions du même gabarit plutôt qu'à une cible calculée à la main
Comment un long tableau se pagine-t-il sans se copier à chaque page ?
Le moteur de rendu ne scinde que ce qui chevauche la limite de page. La façon naïve de paginer un arbre consiste à cloner ce qui n'a pas tenu et à reporter la copie sur la page suivante ; pour un tableau de 10 000 lignes, cela clone les lignes restantes à chaque page et transforme un travail linéaire en travail quadratique. HotPDF parcourt les enfants du corps par index et ne clone jamais une section ou un corps entier. Une pile ou un conteneur imbriqué qui franchit une limite de page ne voit que son sous-arbre affecté cloné, et les deux types de feuilles lourdes portent un curseur plutôt qu'une copie
Un paragraphe poursuivi est une référence au texte d'origine accompagnée de la plage de caractères encore due, et il réutilise les sauts de ligne déjà calculés pour cette largeur. Un tableau poursuivi est une référence au tableau d'origine accompagnée de la tranche de lignes restant à placer. Un paragraphe de 300 lignes coûte la même chose qu'il se coupe une fois ou cinq fois
Le placement lui-même passe par la méthode publique THotPDF.PlaceLayoutElement. Elle mesure l'élément par rapport à la hauteur de corps restante, le dessine en entier s'il tient, lui demande sinon de se Split, mesure à nouveau la moitié placée, la dessine, et renvoie le reste sous forme d'objet de débordement que le moteur de rendu transporte vers une page neuve. Measure ne doit jamais rien dessiner ; elle peut être appelée plusieurs fois pour un même placement. Le moteur du DOM ajoute par-dessus cette routine les éléments récurrents de page, l'espacement entre enfants et les décisions de nouvelle page
Pourquoi une seule ligne d'en-tête peut-elle arrêter tout le rendu ?
Les lignes d'en-tête répétées obéissent à deux règles, et toutes deux existent pour éviter qu'un rapport produise des pages sans données. Les lignes d'en-tête doivent former la première série de lignes : un AddRow(Height, True) après une ligne de corps lève une EInvalidOpException avec « Table header rows must precede body rows ». Et la première scission d'un tableau doit faire tenir toutes les lignes d'en-tête plus au moins une ligne de corps. Un tableau qui laisserait son en-tête abandonné au bas d'une page passe plutôt à la page suivante
La seconde règle a un bord dur. Si les lignes d'en-tête plus une ligne de corps ne tiennent même pas sur une page vide, il n'existe aucune page où le tableau puisse commencer, et Render lève « Layout component ... cannot fit an empty body page » avec le chemin du composant, par exemple Sections[0]/Body/Items[2]/assets. C'est le comportement qu'on veut. Un moteur de mise en page qui continuerait d'ajouter des pages en espérant que la prochaine serait plus spacieuse transformerait un en-tête trop grand en boucle qui remplit le disque
Les composants personnalisés bénéficient de la même protection. Dérivez THPDFDOMComponent, implémentez Clone, Measure, Draw et Split, et le moteur de rendu compte combien de continuations chaque enfant du corps produit. Au-delà de THPDFDOMRenderer.MaximumContinuationDepth (100 000 par défaut), le rendu s'arrête avec « exceeded the continuation depth limit ». Un Split qui renvoie indéfiniment une queue équivalente, donc ne progresse jamais, échoue avec un chemin de composant au lieu de tourner jusqu'à remplir le disque
Sur les pages de continuation, les lignes d'en-tête sont redessinées à l'intérieur d'une séquence de contenu marqué /Artifact, et l'arbre de structure ne conserve le TR d'origine qu'une seule fois. L'extraction de texte n'insère donc pas de ligne d'en-tête en double entre les lignes de données, et les technologies d'assistance n'annoncent pas une seconde fois les titres de colonnes au milieu du tableau. Chaque cellule d'en-tête est balisée TH avec un attribut /Scope /Column
Un paragraphe logique, plusieurs fragments de page
Un paragraphe scindé reste un unique élément de structure P. Chaque fragment visible ouvre sa propre séquence de contenu marqué sur sa page, et HotPDF ajoute un dictionnaire de référence de contenu marqué, << /Type /MCR /Pg page /MCID n >>, au tableau /K de cet élément et enregistre le MCID dans l'entrée ParentTree de la page, qui pointe en retour vers le même élément. C'est l'agencement que décrit la norme ISO 32000-1 §14.7.4 pour des éléments de contenu répartis sur plusieurs pages, et c'est ce qui permet à une vue de l'arbre de balises d'afficher un seul paragraphe là où les pages en montrent deux morceaux
L'identité sémantique explique pourquoi les copies de continuation se comportent différemment de vos propres clones. Appeler Clone signifie « nouveau contenu logique », et le résultat reçoit un nouvel élément de structure quand il est dessiné. Les copies créées pendant la pagination héritent de l'identité du composant qu'elles prolongent, si bien qu'une pile répartie sur trois pages produit toujours un seul Div, et une liste répartie sur deux un seul L. Les en-têtes et pieds de page empruntent une autre voie : ils sont enveloppés en /Artifact << /Type /Pagination /Subtype /Header >> (ou /Footer) sur chaque page et n'entrent jamais dans l'arbre de structure
Des règles de structure vérifiées pendant le rendu de l'arbre
Avec GenerateStructure actif, le moteur de rendu refuse toute structure qu'une validation PDF/UA rejetterait plus tard. Le premier titre doit être H1 et les titres suivants ne peuvent pas sauter de niveau, si bien qu'un H3 juste après un H1 lève « Semantic heading levels cannot skip an intermediate level ». LI exige un parent L, Lbl et LBody exigent un LI, TR exige un tableau ou un groupe de lignes, et TH / TD exigent un TR. Quand la cible a PDFUACompliance défini, une Figure sans texte alternatif est rejetée elle aussi. Chaque violation arrête Render par une exception
var
List: THPDFDOMList;
Bmp: TBitmap; // Vcl.Graphics
begin
Section.Body.AddHeading('Findings', 2); // H1 est déjà là, donc H2 est légal
List := THPDFDOMList.Create('Decimal'); // balisé L, ListNumbering /Decimal
List.AddItem('1.', 'Replace the intake filter on pump P-14');
List.AddItem('2.', 'Re-torque the flange bolts on line 3');
Section.Body.Add(List); // AddItem construit LI, Lbl et LBody
Bmp := TBitmap.Create;
try
Bmp.LoadFromFile('site-plan.bmp');
// L'image copie le graphique ; un texte alt vide échoue sous PDFUACompliance
Section.Body.Add(THPDFDOMImage.Create(Bmp, 240, 160,
'Site plan of plant 3 with the inspected pumps circled'));
finally
Bmp.Free;
end;
end;
Vérifier pendant le rendu est la bonne place pour ces règles. La raison, c'est le moment. Un validateur qui signale un texte alternatif manquant une fois le fichier écrit vous apprend qu'un lot de 10 000 relevés doit être régénéré ; une exception pendant Render nomme la règle en défaut alors que l'enregistrement qui l'a provoquée est encore dans la portée. La vérification formelle de conformité reste une étape du pipeline, et comme les objets du document restent lisibles après le retour de Render, elle peut tourner immédiatement. La validation PDF/A, PDF/X et PDF/UA couvre cette étape, et l'ordre de structure et l'extraction de texte montre comment l'arbre de balises pilote ce que les outils d'extraction lisent en retour
Quand continuer à dessiner à la main
L'arbre dessine sur les mêmes objets THPDFPage que l'API directe. Comme Render possède le document de BeginDoc à EndDoc, les visuels positionnés à la main, comme une image de signature, prennent place dans l'arbre : le Draw d'un composant personnalisé reçoit la page et ses limites et peut y appeler les méthodes ordinaires de la page. La fermeture des pages reste le fait d'AddPage et d'EndDoc ; avec ImmediateFlushLayout défini sur l'instance THotPDF, les pages terminées sont écrites au fil du rendu et le moteur ne retient aucune page achevée ; la mémoire dépend alors des continuations ouvertes, des ressources de polices et du graphe d'objets du document
Le composant de texte du DOM coupe les lignes à partir d'une avance moyenne estimée de 0,55 × la taille de police par caractère et donne à chaque ligne le LineHeight résolu. La mesure reste économique et identique sur toutes les machines, ce qui suffit largement aux rapports pilotés par les données. Un texte aux glyphes larges — tout en capitales, en gras ou en CJK — sort plus large que l'estimation ; laissez donc du jeu dans ces largeurs de colonnes et testez la mise en page une fois avec la plus longue chaîne réelle. Les pages typographiées avec des métriques de glyphes exactes, plusieurs polices dans une même ligne ou des paragraphes justifiés sont mieux servies par l'API de texte directe ; la justification de texte décrit cette voie, et si seule la pagination de tableaux vous fait souffrir, la génération de tableaux en PDF est le changement plus limité
L'arbre de mise en page, son moteur de rendu, le balisage décrit ici et l'API de dessin direct sont livrés dans un seul composant pour Delphi et C++Builder ; les éditions et la liste complète des fonctionnalités figurent sur la page du composant PDF Delphi HotPDF