Articolo tecnico

Flexbox, CSS Grid e note a piè di pagina nel PDF da Delphi

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

Diagramma PDF Library for Delphi del dimensionamento delle righe flex: basi misurate e pesi di crescita, distribuzione pesata dello spazio residuo per riga, e una passata di allineamento solo-spostamento che produce una riga dashboard da due a uno a uno
Il dimensionamento flex è un passaggio di misura delimitato seguito da una distribuzione ponderata dello spazio residuo; l'allineamento sposta le caselle misurate e non attiva mai una nuova misura
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

Diagramma PDF Library for Delphi dei valori di traccia della griglia accettati, il piazzamento deterministico dell'occupazione con sovrapposizione intenzionale consentita, e un elemento che copre più righe che restituisce la sua altezza mediata sulle righe che copre
Le tracce della griglia accettano lunghezze, percentuali, unità fr, repeat e minmax mentre il posizionamento automatico percorre la matrice di occupazione in modo deterministico

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

Diagramma PDF Library for Delphi della paginazione delle note a piè di pagina: l'area note è riservata sotto una riga in fondo al suo box, una nota che non ci sta viaggia nella stringa di continuazione insieme al suo marcatore, e la numerazione resta continua tra le pagine
Lo spazio per le note a piè di pagina viene ricavato dal budget del corpo prima che fluisca altro testo, e la numerazione sopravvive attraverso colonne e pagine

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 &deg;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