Supponi che un capitolo a due colonne metta un riferimento di nota a piè di pagina sulla penultima riga della colonna sinistra. Una nota di una riga richiede all'incirca 14 punti in fondo a quella colonna, e ne restano solo 9. Entrambi gli esiti ovvi sono sbagliati: disegnare la nota lo stesso e va a stampare sopra il testo del corpo, o spingere avanti solo la nota e finisce sotto la colonna destra, accanto a testo con cui non c'entra niente. Un browser non deve mai prendere questa decisione, perché una pagina web non ha un bordo in fondo. Flexbox e CSS Grid sono stati progettati sotto la stessa ipotesi, quindi una volta che l'HTML di un report deve atterrare su pagine di dimensioni fisse, ognuno dei due ha bisogno di una regola per ciò che accade quando il box finisce l'altezza
Una riga flex da dashboard in un box a larghezza fissa
PDF Library for Delphi tratta ogni elemento con stile display: flex o display: inline-flex come un vero contenitore flex, così una riga di card resta una riga invece di collassare in blocchi impilati. La disegni con DrawHTMLTextBox(Left, Top, Width, Height, HTMLText), che restituisce una WideString: vuota quando tutto è entrato, altrimenti la parte che deve ancora essere disegnata da qualche altra parte
Nella direzione riga ogni elemento riceve una basis, le basis e i gap tra gli elementi vengono sommati, e ciò che resta sulla riga viene distribuito. Lo spazio positivo va secondo flex-grow. Quello negativo viene ripreso da flex-shrink moltiplicato per la basis dell'elemento, che è la regola CSS e ha un effetto collaterale piacevole mostrato tra poco. Con flex-wrap impostato, gli elementi passano a una nuova riga appena la basis successiva non entra più, e ogni riga distribuisce il proprio spazio libero. justify-content, align-items, align-content, gap e le direzioni -reverse poi spostano solo box già misurati
uses
SysUtils, PDFlibrary;
var
Lib: TPDFlib;
Html, Remainder: WideString;
begin
Lib := TPDFlib.Create;
try
Lib.SetOrigin(1); // origine in alto a sinistra: Top cresce verso il fondo pagina
Lib.SetPageSize('A4');
// Le basi in percentuale mantengono il rapporto 2:1:1 esatto, gap compreso
Html :=
'<div style="display:flex; gap:12px;">' +
'<div style="flex:0 1 50%; background:#f4f6f8; padding:8px;">' +
'<b>Revenue</b><br/>EUR 4,182,300</div>' +
'<div style="flex:0 1 25%; background:#f4f6f8; padding:8px;">' +
'<b>Margin</b><br/>18.4%</div>' +
'<div style="flex:0 1 25%; background:#f4f6f8; padding:8px;">' +
'<b>Backlog</b><br/>92 days</div>' +
'</div>';
Remainder := Lib.DrawHTMLTextBox(40, 40, 515, 120, Html);
if Remainder <> '' then
raise Exception.Create('Dashboard row needs more than 120 pt');
Lib.SaveToFile('dashboard.pdf');
finally
Lib.Free;
end;
end;
Fai i conti per il box da 515 punti. Il gap di 12px converte in 9 punti, quindi due gap costano 18. Le basi sommano all'intero 515, che sfora esattamente quei 18 punti. Lo shrink è ponderato per la basis, così la card del 50% restituisce 9 punti e ogni card del 25% ne restituisce 4.5, lasciando 248.5, 124.25 e 124.25. Il rapporto resta esattamente 2:1:1, e il codice non ha mai dovuto sottrarre i gap a mano
Perché elementi con flex: 1 uguali escono disuguali?
Perché la loro basis è la larghezza del loro contenuto. Il renderer prende la basis da flex-basis, da una lunghezza dentro la scorciatoia flex (un valore con pt, px, em o %), o da width. Quando nessuna di queste produce una lunghezza positiva, la larghezza del contenuto misurato dell'elemento diventa la sua basis. Un flex: 1 nudo e l'idioma da browser flex: 1 1 0 finiscono entrambi lì, dato che uno 0 senza unità non viene letto come lunghezza. Fattori di grow uguali aggiungono allora quantità uguali di spazio libero sopra larghezze di partenza disuguali
Scrivi la stessa dashboard con flex: 1 su ogni card e la card Revenue, il cui numero a sette cifre rende il suo contenuto il più largo delle tre, parte più larga della card Margin e resta più larga di esattamente quella quantità dopo la crescita, perché ogni card riceve lo stesso terzo di qualunque spazio libero rimanga. Per toolbar, liste di tag e file di pulsanti spesso è comunque l'aspetto che vuoi. Non per una dashboard. Qualsiasi cosa debba allinearsi con una tabella sopra o sotto merita basi esplicite in percentuale o in punti con grow a 0, che è la nostra raccomandazione ed è esattamente ciò che fa l'esempio: le tre card atterrano allora a 248.5, 124.25 e 124.25 punti su ogni pagina, qualunque cosa dicano le cifre dentro
La direzione colonna segue la stessa logica sull'asse verticale. La basis viene da flex-basis o da height, altrimenti dall'altezza del contenuto misurata, e lo spazio libero esiste solo quando il contenitore dichiara una height. Senza di essa, il contenitore è alto esattamente come i suoi elementi e justify-content non ha niente da distribuire
Track della grid, posizionamento e span
Per display: grid, PDF Library for Delphi legge grid-template-columns e grid-template-rows come lunghezze fisse, percentuali, unità fr, repeat(n, track) e minmax(a, b). Le track fisse e i gap vengono sottratti dalla larghezza disponibile, e il resto viene diviso per peso fr. Una track minmax() viene dimensionata secondo il suo secondo argomento, così minmax(120px, 1fr) si comporta come 1fr, e le track auto, min-content e max-content prendono ognuna una quota dello spazio libero
Il posizionamento è deterministico. Gli elementi posizionati automaticamente percorrono la grid riga per riga (o colonna per colonna con grid-auto-flow: column) e saltano le celle già occupate. Un elemento con solo la riga data cerca in quella riga una colonna libera; uno con solo la colonna data cerca giù per quella colonna. Gli elementi con entrambe le coordinate vanno esattamente dove lo dicono, anche sopra un altro elemento, che è come un badge finisce sovrapposto a una card
Gli span chiedono un'abitudine. Il renderer legge lo span dalla parte dopo la barra, come in grid-row: 1 / span 2, o da grid-row-end: span 2 e grid-column-end: span 2. Il grid-row: span 2 nudo che i browser accettano come valore intero non è una di quelle grafie, quindi conserva la riga di inizio e la barra
// Scheda di ispezione: colonna etichetta fissa, due colonne flessibili
Html :=
'<div style="display:grid; ' +
'grid-template-columns:120pt repeat(2, 1fr); gap:6pt;">' +
'<div style="grid-row:1 / span 2; background:#eef2ff;">' +
'Site plan</div>' +
'<div>Inspector</div>' +
'<div>Date</div>' +
'<div style="grid-column:2 / span 2;">Findings summary</div>' +
'</div>';
Remainder := Lib.DrawHTMLTextBox(40, 180, 515, 260, Html);
In quel box da 515 punti la colonna delle etichette è di 120 punti, i due gap prendono 12, e ogni colonna 1fr ne prende 191.5. La cella Site plan ha una riga ma nessuna colonna, così atterra in colonna 1 e copre le righe 1 e 2. Inspector e Date riempiono il resto della riga 1. Il sommario ha una colonna ma nessuna riga, quindi il posizionamento cerca giù per la colonna 2, trova la riga 1 occupata, e si assesta nella riga 2 attraverso entrambe le colonne flessibili
Le altezze delle righe arrivano dal contenuto. Siccome un elemento in span divide la propria altezza misurata in parti uguali tra le righe che copre, e ogni riga poi prende la quota più grande che qualunque elemento al suo interno chieda, l'altezza extra di una cella alta si sparge su ogni riga che tocca invece di scaricarsi sulla prima. Una cella Site plan alta quindi alza entrambe le righe un po' invece di stirare solo la prima e lasciare Findings summary sospeso in un vuoto
I contenitori si spostano tra box in un pezzo solo
Un contenitore flex o grid non viene mai spezzato tra due box. Mai. Quando il contenitore intero non entra nello spazio rimasto, il contenitore e tutto ciò che viene dopo finiscono nella remainder restituita, e siccome quella remainder è esattamente ciò che passi al box successivo o alla pagina successiva, la riga di card apre semplicemente il frame seguente con la sua geometria misurata intatta. Mezzo tile KPI in fondo alla pagina 3 e l'altra metà sulla pagina 4 è peggio di un vuoto, ed è il compromesso che questa regola fa. Un contenitore più alto di un intero box vuoto è l'eccezione: viene disegnata in cima a quel box a prescindere e corre oltre il bordo in fondo, perché nessun box successivo sarebbe più grande
La conseguenza pratica è che conviene conoscere l'altezza di un contenitore prima di impegnarlo su una pagina. GetHTMLTextHeight(Width, HTMLText) misura senza disegnare, flex e grid inclusi
// GridHtml, Y e PageBottom appartengono al tuo codice di report
Needed := Lib.GetHTMLTextHeight(515, GridHtml);
if Y + Needed > PageBottom then
begin
Lib.NewPage;
Lib.SetPageSize('A4');
Y := 40;
end;
Lib.DrawHTMLTextBox(40, Y, 515, Needed, GridHtml);
Y := Y + Needed + 12;
La misurazione è delimitata di proposito, il che conta quando sono i clienti a modificare i template. Un contenitore flex o grid prende i primi 256 figli diretti, il posizionamento della grid funziona entro 64 righe, e una lista di track tiene al massimo 64 track, con i conteggi repeat() limitati di conseguenza. Un contenitore flex con centinaia di figli è quasi sempre una tabella di dati travestita, e il percorso tabella, con la propria misurazione delle colonne e il supporto a rowspan, la dispone comunque meglio
Come si tengono le note a piè di pagina insieme al loro riferimento?
PDF Library for Delphi misura ogni nota nel momento in cui incontra il riferimento e sottrae quell'altezza dal budget del corpo del box corrente. Una nota si scrive come <aside style="float:footnote">, <aside role="doc-footnote"> o un elemento <footnote>. Il riferimento diventa un numero in apice a due terzi della dimensione del font circostante, e il testo della nota viene composto a 8 punti su 10 di interlinea, preceduto dallo stesso numero
Se il corpo fino a lì più la nuova nota non entra più, il marcatore e tutto ciò che viene dopo si spostano insieme nella remainder. Nota e riferimento viaggiano in coppia. È questa la risposta allo scenario di apertura: la riga del riferimento e la sua nota aprono la colonna successiva, e né la sovrastampa né la nota orfana possono accadere. In un box delimitato l'area delle note è fissata in fondo sotto una sottile linea grigia lunga un quarto della larghezza del box. Nella misurazione senza limiti, come GetHTMLTextHeight, non c'è un fondo a cui fissarla, quindi le note seguono direttamente il corpo
La numerazione riparte da 1 per ogni stringa HTML nuova. Il numero successivo è conservato dentro la stringa di remainder stessa, così le catene di DrawHTMLTextBox e DrawHTMLStory mantengono un'unica sequenza continua attraverso colonne e pagine, purché la remainder venga ripassata esattamente come è stata restituita. Ricostruire la continuazione dal tuo testo sorgente fa ripartire il conteggio
Chapter :=
'<p>The bearing stayed within tolerance for the full six hours' +
'<aside style="float:footnote">Ambient temperature held at ' +
'21 °C throughout the run.</aside> of the load test.</p>' +
MoreChapterHtml; // il resto del tuo capitolo
// 2 colonne, canale di 16 pt, al massimo 20 pagine; la story aggiunge pagine da sola
Rest := Lib.DrawHTMLStory(40, 40, 515, 760, 2, 16, 20, Chapter);
Err := Lib.LastErrorCode; // leggi una sola volta: leggerlo lo azzera
if Err = PDFLIB_ERROR_HTML_STORY_INVALID then
// geometria sbagliata: Columns 1..64, MaxPages 1..10000, canali più stretti di Width
else if Err = PDFLIB_ERROR_HTML_STORY then
// due frame di fila senza progressi
else if Rest <> '' then
// 20 pagine usate e testo avanzato: continua dopo con Rest
;
DrawHTMLStory(Left, Top, Width, Height, Columns, Gutter, MaxPages, HTMLText) parte dalla pagina corrente, riempie le colonne da sinistra a destra, e aggiunge pagine con le stesse dimensioni finché il testo non finisce o non si raggiunge MaxPages. Distinguere quei tre esiti è il motivo per cui si legge LastErrorCode prima di testare la stringa restituita. Argomenti non validi restituiscono l'input invariato, che altrimenti assomiglia esattamente a una story rimasta senza pagine
Nutrire il layout con contenuto reale
Per il testo del corpo multi-colonna, il comportamento di colonne e sillabazione descritto in sillabazione e colonne di testo bilanciate governa l'aspetto del flusso dentro ogni colonna. Dove il markup arriva dai dati invece che da template scritti a mano, il motore di report basato su dataset è la strada che lo genera prima che flex e grid lo dispongano sulla pagina. Il contenuto che poi deve uscire di nuovo dal PDF passa per esportazione da PDF a Markdown e DOCX
Il layout HTML con flex, grid e note a piè di pagina, la generazione di report e l'esportazione semantica viaggiano in un'unica libreria per Delphi, C++Builder e Free Pascal. La pagina prodotto di PDF Library for Delphi elenca il resto del renderer HTML e l'API di disegno