Articolo tecnico

Layout PDF dichiarativo in Delphi con output taggato

Un paragrafo che inizia in fondo alla pagina 4 e finisce in cima alla pagina 5 è un paragrafo unico per chi lo legge. In un PDF taggato vive in due content stream, e ogni pagina numera le proprie sequenze di marked-content in autonomia, quindi l'albero di struttura ha bisogno di un unico elemento P il cui array /K punta, per esempio, a MCID 7 sulla pagina 4 e a MCID 3 sulla pagina 5. Disegnate le pagine con codice a coordinate e aggiungete il tagging dopo, e l'albero dei tag in un checker di accessibilità di norma mostra due paragrafi dove ce n'era uno, più una serie di titoli di colonna ripetuti dentro i dati di ogni tabella continuata

L'approccio a coordinate ha un secondo costo, che arriva prima. La prima versione di un report funziona. Poi l'indirizzo di un cliente cresce a tre righe, un'intestazione localizzata va a capo, una tabella guadagna quaranta righe, e ogni posizione y sotto quel punto è sbagliata. I controlli di interruzione pagina finiscono sparsi nella logica di business, e il codice che ha sempre saputo solo di x e y non ha la minima idea di dove inizi un paragrafo quando il requisito di accessibilità si presenta due anni dopo

Costruire un albero di layout HotPDF in Delphi

HotPDF risponde a entrambi i problemi con un albero di layout dichiarativo nella unit HPDFLayoutDOM. Un THPDFDOMDocument contiene sezioni; ogni THPDFDOMSection ha una dimensione pagina, margini, un'intestazione e un piè di pagina opzionali, e uno stack Body in cui aggiungete testo, titoli, spaziatori, elenchi, immagini, contenitori e tabelle. Niente nell'albero porta una coordinata y. THPDFDOMRenderer misura l'albero, decide le interruzioni di pagina, disegna intestazione e piè di pagina su ogni pagina e, poiché GenerateStructure vale True per impostazione predefinita, scrive l'albero di struttura mentre procede

La proprietà nell'albero è rigida. Il documento possiede le proprie sezioni, una sezione possiede il proprio corpo, intestazione e piè di pagina, e stack, contenitori e tabelle possiedono i propri figli, quindi Section.Body.Add(Table) consegna la tabella per sempre. Un componente collegato a due genitori verrebbe misurato due volte con vincoli diversi e liberato due volte alla distruzione. I pezzi ripetuti come un blocco firma arrivano quindi da Clone, da SetHeaderClone / SetFooterClone, o da una factory registrata con RegisterComponent, dopodiché ogni chiamata a CreateComponent('signature') restituisce un'istanza nuova

Albero di proprietà di un documento di layout dichiarativo HotPDF in cui sezioni, intestazioni, piè di pagina e righe di tabella hanno ciascuno esattamente un proprietario
Ogni nodo dell'albero di layout ha esattamente un proprietario, così gli helper restituiscono istanze fresche invece di riferimenti condivisi, e l'arredo ripetuto arriva da una factory registrata come nuovo componente a ogni chiamata
uses
  SysUtils, HPDFDoc, HPDFLayoutDOM;

type
  TAssetRow = record                    // il tuo tipo di dati
    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 verticale, margini di 36 pt predefiniti
    Section.MarginLeft := 56;
    Section.MarginRight := 56;
    Section.Style.FontName := 'Helvetica';
    Section.Style.FontSize := 10;
    Section.Style.LineHeight := 13;
    Section.Body.Style.Spacing := 6;    // spazio tra i figli del corpo
    Section.Footer := THPDFDOMText.Create('Plant maintenance - internal');

    Heading := Section.Body.AddHeading('Annual maintenance report', 1);
    Heading.Style.FontSize := 18;
    Heading.Style.LineHeight := 22;     // LineHeight non segue FontSize
    Section.Body.AddText('Every asset inspected during the reporting ' +
      'period is listed below, grouped by site.');

    Table := THPDFDOMTable.Create('assets');  // RepeatHeaders è True predefinito
    Table.AddColumn(3);                 // pesi, non larghezze in punti
    Table.AddColumn(1);
    Table.AddColumn(1);
    Row := Table.AddRow(18, True);      // le righe di intestazione vengono prima
    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);            // da qui in poi il corpo possiede la tabella
    Result := Doc;
  except
    Doc.Free;
    raise;
  end;
end;

Due valori predefiniti di quel listato prendono in contropiede. LineHeight si risolve in 12 punti se nessuno stile della catena lo imposta, qualunque cosa dica FontSize, quindi un titolo di 18 pt senza un proprio LineHeight ottiene righe da 12 pt e sovrappone la successiva. E una riga di tabella è alta esattamente quanto l'altezza passata a AddRow: il testo della cella esce su una sola riga, quindi dimensionate le righe in base al font scelto

Render apre e chiude il documento da solo

THPDFDOMRenderer.Render(Doc, Pdf) chiama BeginDoc sul target, renderizza ogni sezione e chiama EndDoc prima di ritornare. Non avvolgetelo in una vostra coppia BeginDoc / EndDoc. Tutto ciò che va impostato prima che il documento parta va impostato prima sull'istanza THotPDF: FileName, Title, e PDFUACompliance se l'output deve dichiarare PDF/UA. Con la generazione della struttura attiva, Render accende anche EnableTaggedPDF e copia Doc.Language in Pdf.Lang se l'avete lasciato vuoto

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;        // abilita anche il controllo alt delle figure
    // niente BeginDoc / EndDoc qui: Render apre e chiude il documento
    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;

Loggate il record delle statistiche a ogni esecuzione, perché mostra regressioni del template che non causano mai un'eccezione. Un SplitCount che salta dopo una modifica al template di solito significa che qualche componente ora misura più alto dello spazio in cui prima ci stava. Un MaximumContinuationDepth che sale di poco in punta di piedi punta a un componente il cui Split sposta troppo poco contenuto per pagina. ArtifactCount copre intestazioni e piè di pagina, i bordi decorativi come la cornice predefinita da 0,5 pt della tabella, e le righe di intestazione ripetute, quindi confrontatelo tra esecuzioni dello stesso template invece che contro un obiettivo calcolato a mano

Come fa una tabella lunga a paginare senza copiarsi su ogni pagina?

Il renderer divide solo ciò che cavalca il confine di pagina. Il modo ingenuo di paginare un albero è clonare ciò che non è entrato e portare la copia alla pagina successiva; per una tabella con 10.000 righe significa clonare le righe rimanenti una volta per pagina e trasformare un lavoro lineare in uno quadratico. HotPDF percorre i figli del corpo per indice e non clona mai un'intera sezione o corpo. Uno stack o un contenitore annidato che attraversa un confine di pagina fa clonare solo il proprio sottoalbero interessato, e i due tipi di foglia più pesanti portano un cursore invece di una copia

Un paragrafo continuato è un riferimento al testo originale più l'intervallo di caratteri che deve ancora produrre, e riusa le interruzioni di riga già calcolate per quella larghezza. Una tabella continuata è un riferimento alla tabella originale più la fetta di righe ancora da collocare. Un paragrafo di 300 righe costa lo stesso sia che si interrompa una volta sia che si interrompa cinque

Grafico a barre che contrappone il costo quadratico di paginazione della clonazione dell'intero sottoalbero al costo lineare costante delle divisioni ristrette al confine di pagina in HotPDF
Clonare l'intero sottoalbero non posizionato su ogni pagina a cavallo trasforma le righe extra in lavoro quadratico, mentre uno split stretto lascia che il testo lungo porti un cursore per intervallo di caratteri e le tabelle un cursore per fetta di righe

Il posizionamento in sé passa attraverso la THotPDF.PlaceLayoutElement pubblica. Misura l'elemento rispetto all'altezza rimanente del corpo, lo disegna intero se ci sta, altrimenti gli chiede di Split, rimisura la metà posizionata, la disegna, e restituisce il resto come oggetto di overflow che il renderer porta a una pagina nuova. Measure non deve mai disegnare nulla; può girare più volte per un solo posizionamento. Il renderer DOM aggiunge a quella routine gli elementi di cornice della pagina, la spaziatura tra figli e le decisioni di pagina nuova

Perché una singola riga di intestazione può fermare l'intero render?

Le intestazioni di tabella ripetute portano con sé due regole, ed entrambe esistono per impedire a un report di produrre pagine senza dati. Le righe di intestazione devono formare la prima sequenza di righe: AddRow(Height, True) dopo una riga di corpo qualsiasi solleva EInvalidOpException con "Table header rows must precede body rows". E il primo split di una tabella deve far entrare ogni riga di intestazione più almeno una riga di corpo. Una tabella che lascerebbe l'intestazione arenata in fondo a una pagina passa invece alla pagina successiva

La seconda regola ha un bordo duro. Se le righe di intestazione più una riga di corpo non entrano nemmeno su una pagina vuota, non esiste una pagina su cui la tabella possa iniziare, e Render solleva "Layout component ... cannot fit an empty body page" con il percorso del componente, per esempio Sections[0]/Body/Items[2]/assets. È il comportamento che vale la pena avere. Un motore di layout che continuasse ad aggiungere pagine nella speranza che la successiva fosse più spaziosa trasformerebbe un'unica intestazione sovradimensionata in un loop che riempie il disco

I componenti personalizzati ricevono la stessa protezione. Derivate THPDFDOMComponent, implementate Clone, Measure, Draw e Split, e il renderer conta quante continuazioni produce ogni figlio del corpo. Sopra THPDFDOMRenderer.MaximumContinuationDepth (100.000 per impostazione predefinita) il render si ferma con "exceeded the continuation depth limit". Un Split che continua a restituire una coda equivalente, e quindi non fa mai progressi, fallisce con un percorso di componente invece di girare finché il disco non si riempie

Sulle pagine di continuazione le righe di intestazione vengono ridisegnate dentro una sequenza di marked-content /Artifact, e l'albero di struttura conserva l'originale TR una volta sola. L'estrazione del testo quindi non inserisce una riga di intestazione duplicata tra le righe di dati, e la tecnologia assistiva non annuncia di nuovo i titoli delle colonne in mezzo alla tabella. Ogni cella di intestazione è taggata TH con un attributo /Scope /Column

Un paragrafo logico, diversi frammenti di pagina

Un paragrafo diviso resta un unico elemento di struttura P. Ogni frammento visibile apre una nuova sequenza di marked-content sulla propria pagina, e HotPDF accoda un dizionario di riferimento a contenuto marcato, << /Type /MCR /Pg page /MCID n >>, all'array /K di quell'elemento e registra l'MCID nella voce ParentTree della pagina che punta di nuovo allo stesso elemento. È la disposizione che la ISO 32000-1 §14.7.4 descrive per gli elementi di contenuto sparsi su più pagine, ed è ciò che permette a una vista ad albero dei tag di mostrare un paragrafo dove le pagine mostrano due pezzi

L'identità semantica è il motivo per cui le copie di continuazione si comportano in modo diverso dai vostri cloni. Chiamare Clone significa "nuovo contenuto logico", e il risultato ottiene un nuovo elemento di struttura quando viene disegnato. Le copie fatte durante la paginazione ereditano l'identità del componente che continuano, quindi uno stack diviso su tre pagine produce comunque un solo Div, e un elenco diviso su due produce comunque un solo L. Intestazioni e piè di pagina prendono una strada diversa: su ogni pagina vengono avvolti come /Artifact << /Type /Pagination /Subtype /Header >> (o /Footer) e non entrano mai nell'albero di struttura

Diagramma HotPDF di un paragrafo taggato mantenuto come unico elemento di struttura PDF mentre i suoi due frammenti di pagina portano identificatori di contenuto marcato distinti e un'intestazione ridisegnata è taggata come artifact
I frammenti di un paragrafo condividono un unico elemento di struttura attraverso le coppie Pg e MCID raccolte nel suo array K, e l'intestazione ridisegnata sulle pagine di continuazione viaggia come artifact anziché come contenuto

Regole di struttura verificate mentre l'albero renderizza

Con GenerateStructure attivo, il renderer rifiuta la struttura che la validazione PDF/UA rifiuterebbe più avanti. Il primo titolo deve essere H1 e i titoli successivi non possono saltare un livello, quindi un H3 subito dopo un H1 solleva "Semantic heading levels cannot skip an intermediate level". LI ha bisogno di un genitore L, Lbl e LBody di un LI, TR di una tabella o di un gruppo di righe, e TH / TD di un TR. Quando il target ha PDFUACompliance impostato, viene rifiutata anche una Figure senza testo alternativo. Ogni violazione ferma Render con un'eccezione

var
  List: THPDFDOMList;
  Bmp: TBitmap;                         // Vcl.Graphics
begin
  Section.Body.AddHeading('Findings', 2);     // H1 è arrivato prima, quindi H2 è legale

  List := THPDFDOMList.Create('Decimal');     // taggato 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 costruisce LI, Lbl e LBody

  Bmp := TBitmap.Create;
  try
    Bmp.LoadFromFile('site-plan.bmp');
    // l'immagine copia la grafica; un testo alt vuoto fallisce con PDFUACompliance
    Section.Body.Add(THPDFDOMImage.Create(Bmp, 240, 160,
      'Site plan of plant 3 with the inspected pumps circled'));
  finally
    Bmp.Free;
  end;
end;

Verificare durante il render è il posto giusto per queste regole. La ragione è la tempistica. Un validatore che segnala un testo alternativo mancante dopo che il file è stato scritto vi dice che un lotto di 10.000 estratti conto va rigenerato; un'eccezione durante Render nomina la regola fallita mentre il record che l'ha prodotta è ancora nell'ambito. Il controllo formale di conformità resta comunque nella pipeline, e poiché gli oggetti del documento restano leggibili dopo che Render ha ritornato, può girare subito. La validazione PDF/A, PDF/X e PDF/UA copre quel passaggio, e ordine di struttura ed estrazione del testo mostra come l'albero dei tag guida ciò che gli strumenti di estrazione rileggono

Quando continuare a disegnare a mano

L'albero disegna sugli stessi oggetti THPDFPage dell'API diretta. Poiché Render possiede il documento da BeginDoc a EndDoc, la grafica posizionata a mano come un'immagine di firma sta dentro l'albero: la Draw di un componente personalizzato riceve la pagina e i suoi bounds e lì può chiamare i normali metodi di pagina. La chiusura delle pagine resta a AddPage e EndDoc, quindi con ImmediateFlushLayout impostato sull'istanza THotPDF le pagine finite vengono scritte mentre il render procede e il renderer non trattiene pagine completate; la memoria dipende allora dalle continuazioni aperte, dalle risorse dei font e dal grafo di oggetti del documento

Il componente testo del DOM va a capo partendo da un avanzamento medio stimato di 0,55 × dimensione del font per carattere e dà a ogni riga il LineHeight risolto. Questo mantiene la misura economica e identica su ogni macchina, e per i report guidati dai dati è più che sufficiente. Il testo con glifi larghi, come tutto maiuscolo, run in grassetto o CJK, esce più largo della stima, quindi lasciate margine in quelle larghezze di colonna e provate il layout una volta con la stringa reale più lunga. Le pagine tipografiche con metriche di glifo esatte, font misti nella stessa riga o paragrafi giustificati stanno meglio con l'API diretta del testo; la giustificazione del testo percorre quella strada, e se l'unica cosa che duole è la paginazione delle tabelle, generare tabelle in PDF è la modifica più piccola

L'albero di layout, il suo renderer, il tagging descritto qui e l'API di disegno diretto viaggiano tutti in un unico componente per Delphi e C++Builder; edizioni ed elenco completo delle funzionalità sono sulla pagina del componente PDF Delphi HotPDF