Artigo Técnico

Layout declarativo de PDF com saída marcada

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

Árvore de propriedade de um documento de layout declarativo do HotPDF em que seções, cabeçalhos, rodapés e linhas de tabela têm cada um exatamente um proprietário
Todo nó na árvore de layout tem exatamente um dono, então os auxiliares retornam instâncias novas em vez de referências compartilhadas, e elementos repetidos vêm de uma factory registrada como um novo componente a cada chamada
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

Gráfico de barras contrastando o custo quadrático de paginação da clonagem de subárvores inteiras com o custo linear constante de divisões estreitas na fronteira de páginas no HotPDF
Clonar toda a subárvore não posicionada em cada página que atravessa transforma linhas extras em trabalho quadrático, enquanto uma divisão estreita deixa textos longos carregar um cursor de intervalo de caracteres e tabelas carregarem um cursor de fatia de linhas

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

Diagrama HotPDF de um parágrafo etiquetado mantido como um único elemento de estrutura de PDF enquanto seus dois fragmentos de página carregam identificadores de marked content separados e um cabeçalho redesenhado é etiquetado como artifact
Fragmentos de um parágrafo compartilham um único elemento de estrutura através dos pares Pg e MCID coletados em seu array K, e o cabeçalho redesenhado nas páginas de continuação acompanha como artifact em vez de conteúdo

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