Para quem está lendo, um parágrafo que começa no fim da página 4 e termina no topo da página 5 continua sendo um parágrafo só. Em um PDF marcado ele vive em dois streams de conteúdo, e cada página numera suas sequências de marked-content por conta própria, então a árvore de estrutura precisa de um único elemento P cujo array /K aponte para, digamos, o MCID 7 na página 4 e o MCID 3 na página 5. Desenhe as páginas com código de coordenadas e pregue a marcação depois, e a tag tree em um verificador de acessibilidade normalmente mostra dois parágrafos onde havia um, além de um conjunto de títulos de coluna repetido dentro dos dados de cada tabela continuada
A abordagem por coordenadas tem um segundo custo, que chega antes. A primeira versão de um relatório funciona. Aí o endereço de um cliente cresce para três linhas, um título localizado quebra em duas, uma tabela ganha quarenta linhas, e toda posição y abaixo desse ponto fica errada. As verificações de quebra de página acabam espalhadas pela lógica de negócio, e um código que só conhecia x e y não faz ideia de onde um parágrafo começa quando a exigência de acessibilidade aparece dois anos depois
Construindo uma árvore de layout do HotPDF em Delphi
O HotPDF resolve os dois problemas com uma árvore de layout declarativa na unit HPDFLayoutDOM. Um THPDFDOMDocument guarda seções; cada THPDFDOMSection tem tamanho de página, margens, um cabeçalho e um rodapé opcionais, e uma pilha Body em que você adiciona texto, títulos, espaçadores, listas, imagens, contêineres e tabelas. Nada na árvore carrega uma coordenada y. O THPDFDOMRenderer mede a árvore, decide as quebras de página, desenha o cabeçalho e o rodapé em cada página e, como GenerateStructure vale True por padrão, vai escrevendo a árvore de estrutura no caminho
A posse na árvore é rígida. O documento é dono das suas seções, uma seção é dona do corpo, do cabeçalho e do rodapé, e pilhas, contêineres e tabelas são donos dos seus filhos, de modo que Section.Body.Add(Table) entrega a tabela de vez. Um componente anexado a dois pais seria medido duas vezes sob restrições diferentes e liberado duas vezes no final. Por isso, peças repetidas como um bloco de assinatura vêm de Clone, de SetHeaderClone / SetFooterClone ou de uma factory registrada com RegisterComponent, depois da qual cada chamada a CreateComponent('signature') devolve uma instância nova
uses
SysUtils, HPDFDoc, HPDFLayoutDOM;
type
TAssetRow = record // seu próprio tipo de dados
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 retrato, margens de 36 pt por padrão
Section.MarginLeft := 56;
Section.MarginRight := 56;
Section.Style.FontName := 'Helvetica';
Section.Style.FontSize := 10;
Section.Style.LineHeight := 13;
Section.Body.Style.Spacing := 6; // espaço entre os filhos do 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 não acompanha o FontSize
Section.Body.AddText('Every asset inspected during the reporting ' +
'period is listed below, grouped by site.');
Table := THPDFDOMTable.Create('assets'); // RepeatHeaders é True por padrão
Table.AddColumn(3); // pesos, não larguras em pontos
Table.AddColumn(1);
Table.AddColumn(1);
Row := Table.AddRow(18, True); // linhas de cabeçalho vêm primeiro
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); // o corpo passa a ser dono da tabela a partir daqui
Result := Doc;
except
Doc.Free;
raise;
end;
end;
Dois valores padrão dessa listagem pegam muita gente. O LineHeight resolve para 12 pontos a menos que um estilo na cadeia o defina, não importa o que o FontSize diz, então um título de 18 pt sem LineHeight próprio ganha linhas de 12 pt e colide com o próximo. E uma linha de tabela tem exatamente a altura passada para AddRow: o texto da célula sai em uma linha só, então dimensione as linhas para a fonte que você escolheu
O Render abre e fecha o documento por conta própria
O THPDFDOMRenderer.Render(Doc, Pdf) chama BeginDoc no alvo, renderiza todas as seções e chama EndDoc antes de retornar. Não o enrole no seu próprio par BeginDoc / EndDoc. Tudo o que precisa estar definido antes do documento começar vai primeiro na instância de THotPDF: FileName, Title e PDFUACompliance, se a saída precisa alegar PDF/UA. Com a geração de estrutura ligada, o Render também liga o EnableTaggedPDF e copia Doc.Language para Pdf.Lang se você o deixou vazio
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; // também ativa a verificação de alt text de figuras
// Sem BeginDoc / EndDoc aqui: o Render abre e fecha o 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;
Registre o record de estatísticas em toda execução, porque ele revela regressões de template que nunca viram exceção. Um SplitCount que salta depois de uma mudança de template normalmente significa que algum componente passou a medir mais alto que o espaço em que cabia antes. Um MaximumContinuationDepth subindo aos poucos aponta para um componente cujo Split move pouco conteúdo por página. O ArtifactCount cobre cabeçalhos e rodapés de página, bordas decorativas como a moldura padrão de 0,5 pt da tabela e linhas de cabeçalho repetidas, então compare-o entre execuções do mesmo template em vez de contra um alvo calculado à mão
Como uma tabela longa pagina sem se copiar em toda página?
O renderizador divide apenas o que cruza o limite da página. A forma ingênua de paginar uma árvore é clonar o que não coube e levar a cópia para a página seguinte; em uma tabela com 10.000 linhas, isso clona as linhas restantes uma vez por página e transforma um trabalho linear em quadrático. O HotPDF percorre os filhos do corpo por índice e nunca clona uma seção ou um corpo inteiro. Uma pilha ou um contêiner aninhado que cruza o limite da página tem apenas a subárvore afetada clonada, e os dois tipos de folha mais pesados carregam um cursor em vez de uma cópia
Um parágrafo continuado é uma referência ao texto original mais o intervalo de caracteres que ele ainda deve, e reaproveita as quebras de linha já calculadas para aquela largura. Uma tabela continuada é uma referência à tabela original mais a fatia de linhas que falta posicionar. Um parágrafo de 300 linhas custa o mesmo, quebre uma vez ou cinco
O posicionamento em si passa pela rotina pública THotPDF.PlaceLayoutElement. Ela mede o elemento contra a altura restante do corpo, desenha inteiro se couber e, caso contrário, pede um Split, remede a metade posicionada, desenha e devolve o restante como um objeto de overflow que o renderizador leva para uma página nova. O Measure nunca pode desenhar nada; ele pode rodar várias vezes para um único posicionamento. O renderizador DOM adiciona, por cima dessa rotina, os elementos de página, o espaçamento entre filhos e as decisões de página nova
Por que uma única linha de cabeçalho pode parar o render inteiro?
Cabeçalhos de tabela repetidos trazem duas regras, e as duas existem para impedir que um relatório produza páginas sem dados. As linhas de cabeçalho precisam formar a primeira sequência de linhas: um AddRow(Height, True) depois de qualquer linha de corpo levanta EInvalidOpException com "Table header rows must precede body rows". E a primeira divisão de uma tabela precisa comportar todas as linhas de cabeçalho mais pelo menos uma linha de corpo. Uma tabela que deixaria o cabeçalho abandonado no pé da página vai para a página seguinte em vez disso
A segunda regra tem uma borda dura. Se as linhas de cabeçalho mais uma linha de corpo não couberem nem em uma página vazia, não existe página em que a tabela possa começar, e o Render levanta "Layout component ... cannot fit an empty body page" com o caminho do componente, por exemplo Sections[0]/Body/Items[2]/assets. Esse é o comportamento que se quer ter. Um motor de layout que ficasse adicionando páginas na esperança de que a próxima fosse mais espaçosa transformaria um cabeçalho grande demais em um loop que enche o disco
Componentes personalizados recebem a mesma proteção. Crie uma subclasse de THPDFDOMComponent, implemente Clone, Measure, Draw e Split, e o renderizador conta quantas continuações cada filho do corpo produz. Acima de THPDFDOMRenderer.MaximumContinuationDepth (100.000 por padrão) o render para com "exceeded the continuation depth limit". Um Split que fica devolvendo uma cauda equivalente, sem nunca progredir, falha com o caminho do componente em vez de rodar até encher o disco
Nas páginas de continuação, as linhas de cabeçalho são desenhadas de novo dentro de uma sequência de marked-content /Artifact, e a árvore de estrutura mantém o TR original uma única vez. A extração de texto, portanto, não insere uma linha de cabeçalho duplicada entre linhas de dados, e a tecnologia assistiva não anuncia os títulos de coluna novamente no meio da tabela. Cada célula de cabeçalho é marcada como TH com um atributo /Scope /Column
Um parágrafo lógico, vários fragmentos de página
Um parágrafo dividido continua sendo um único elemento de estrutura P. Cada fragmento visível abre uma nova sequência de marked-content na própria página, e o HotPDF anexa um dicionário de referência de marked-content, << /Type /MCR /Pg page /MCID n >>, ao array /K desse elemento e registra o MCID na entrada ParentTree da página apontando de volta para o mesmo elemento. Esse é o arranjo que a ISO 32000-1 §14.7.4 descreve para itens de conteúdo espalhados por páginas, e é o que permite a uma visão de tag tree mostrar um parágrafo onde as páginas mostram dois pedaços
A identidade semântica é o motivo de as cópias de continuação se comportarem de forma diferente dos seus próprios clones. Chamar Clone significa "conteúdo lógico novo", e o resultado ganha um novo elemento de estrutura quando é desenhado. As cópias feitas durante a paginação herdam a identidade do componente que continuam, então uma pilha dividida em três páginas ainda produz um único Div, e uma lista dividida em dois ainda produz um único L. Cabeçalhos e rodapés de página seguem outro caminho: são embrulhados como /Artifact << /Type /Pagination /Subtype /Header >> (ou /Footer) em toda página e nunca entram na árvore de estrutura
Regras de estrutura verificadas enquanto a árvore renderiza
Com GenerateStructure ligado, o renderizador recusa estruturas que a validação PDF/UA rejeitaria depois. O primeiro título precisa ser H1 e os títulos seguintes não podem pular níveis, então um H3 logo depois de um H1 levanta "Semantic heading levels cannot skip an intermediate level". LI precisa de um pai L, Lbl e LBody precisam de um LI, TR precisa de uma tabela ou de um grupo de linhas, e TH / TD precisam de um TR. Quando o alvo tem PDFUACompliance definido, um Figure sem texto alternativo também é rejeitado. Cada violação interrompe o Render com uma exceção
var
List: THPDFDOMList;
Bmp: TBitmap; // Vcl.Graphics
begin
Section.Body.AddHeading('Findings', 2); // o H1 veio antes, então H2 é permitido
List := THPDFDOMList.Create('Decimal'); // marcado como 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 constrói LI, Lbl e LBody
Bmp := TBitmap.Create;
try
Bmp.LoadFromFile('site-plan.bmp');
// a imagem copia o gráfico; alt text vazio falha sob PDFUACompliance
Section.Body.Add(THPDFDOMImage.Create(Bmp, 240, 160,
'Site plan of plant 3 with the inspected pumps circled'));
finally
Bmp.Free;
end;
end;
Verificar durante o render é o lugar certo para essas regras. O motivo é o timing. Um validador que relata um texto alternativo ausente depois que o arquivo foi escrito diz que um lote de 10.000 demonstrativos precisa ser regenerado; uma exceção durante o Render nomeia a regra que falhou enquanto o record que a produziu ainda está no escopo. A checagem formal de conformidade continua fazendo parte do pipeline e, como os objetos do documento continuam legíveis depois que o Render retorna, ela pode rodar em seguida. A validação de PDF/A, PDF/X e PDF/UA cobre essa etapa, e ordem de estrutura e extração de texto mostra como a tag tree dirige o que as ferramentas de extração leem de volta
Quando continuar desenhando à mão
A árvore desenha nos mesmos objetos THPDFPage que a API direta. Como o Render é dono do documento do BeginDoc ao EndDoc, arte posicionada à mão, como uma imagem de assinatura, pertence dentro da árvore: o Draw de um componente personalizado recebe a página e seus limites e pode chamar lá os métodos comuns de página. O fechamento de páginas fica com AddPage e EndDoc, então, com ImmediateFlushLayout definido na instância de THotPDF, as páginas prontas são gravadas conforme o render avança e o renderizador não guarda páginas concluídas; a memória passa a depender das continuações abertas, dos recursos de fonte e do grafo de objetos do documento
O componente de texto do DOM quebra linhas a partir de um avanço médio estimado de 0,55 × tamanho da fonte por caractere e dá a cada linha o LineHeight resolvido. Isso mantém a medição barata e igual em qualquer máquina, e é o bastante para relatórios orientados a dados. Texto com glifos largos, como caixa alta, trechos em negrito ou CJK, sai mais largo que a estimativa, então deixe folga nessas larguras de coluna e teste o layout uma vez com a maior string real. Páginas diagramadas com métricas exatas de glifos, fontes misturadas em uma mesma linha ou parágrafos justificados ficam melhor servidas pela API direta de texto; a justificação de texto percorre esse caminho, e se o que dói é só a paginação de tabelas, a geração de tabelas em PDF é a mudança menor
A árvore de layout, seu renderizador, a marcação descrita aqui e a API de desenho direto são entregues em um único componente para Delphi e C++Builder; edições e a lista completa de recursos estão na página do componente de PDF HotPDF para Delphi