Artigo Técnico

Flexbox, CSS Grid e notas de rodapé em PDF no Delphi

Suponha um capítulo em duas colunas que coloca uma referência de nota de rodapé na penúltima linha da coluna da esquerda. Uma nota de uma linha precisa de cerca de 14 points no pé dessa coluna, e restam só 9. Os dois desfechos óbvios estão errados: desenhar a nota mesmo assim e ela imprime por cima do corpo do texto, ou empurrar só a nota para a frente e ela acaba sob a coluna da direita, ao lado de um texto com que não tem nada a ver. Um navegador nunca precisa tomar essa decisão, porque uma página web não tem borda inferior. Flexbox e CSS Grid foram projetados sob a mesma suposição, então quando o HTML de um relatório precisa cair em páginas de tamanho fixo, cada um deles precisa de uma regra para o que acontece quando a caixa fica sem altura

Uma linha flex de dashboard em uma caixa de largura fixa

A PDF Library for Delphi trata qualquer elemento com estilo display: flex ou display: inline-flex como um container flex de verdade, então uma linha de cartões continua sendo uma linha em vez de colapsar em blocos empilhados. Você a desenha com DrawHTMLTextBox(Left, Top, Width, Height, HTMLText), que retorna um WideString: vazio quando tudo coube, senão a parte que ainda precisa ser desenhada em outro lugar

Na direção da linha, cada item recebe uma base, os valores de base e os gaps entre itens são somados, e o que sobra na linha é distribuído. Espaço positivo vai pelo flex-grow. Espaço negativo é retomado pelo flex-shrink multiplicado pela base do item, que é a regra do CSS e tem um efeito colateral agradável mostrado daqui a pouco. Com flex-wrap definido, os itens passam para uma nova linha quando a próxima base não cabe mais, e cada linha distribui o próprio espaço livre. justify-content, align-items, align-content, gap e as direções -reverse então só movem caixas que já estão medidas

Diagrama do PDF Library for Delphi do dimensionamento de linhas flex: bases medidas e pesos de grow, distribuição ponderada do espaço restante por linha, e uma passada de alinhamento apenas de movimento produzindo uma linha de dashboard de dois-para-um-para-um
O dimensionamento flex é uma passada de medição limitada seguida de distribuição ponderada do espaço restante; o alinhamento move as caixas medidas e nunca dispara nova medição
uses
  SysUtils, PDFlibrary;

var
  Lib: TPDFlib;
  Html, Remainder: WideString;
begin
  Lib := TPDFlib.Create;
  try
    Lib.SetOrigin(1);          // origem no topo à esquerda: Top cresce para baixo na página
    Lib.SetPageSize('A4');

    // Bases em porcentagem mantêm a razão 2:1:1 exata, gap incluído
    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;

Rode os números para a caixa de 515 points. O gap de 12px converte para 9 points, então dois gaps custam 18. As bases somam os 515 completos, o que estoura exatamente esses 18 points. O shrink é ponderado pela base, então o cartão de 50% devolve 9 points e cada cartão de 25% devolve 4.5, sobrando 248.5, 124.25 e 124.25. A razão continua exatamente 2:1:1, e o código nunca precisou subtrair os gaps à mão

Por que itens iguais com flex: 1 saem desiguais?

Porque a base deles é a largura do conteúdo. O renderizador tira uma base do flex-basis, de um comprimento dentro do atalho flex (um valor com pt, px, em ou %), ou do width. Quando nenhum desses produz um comprimento positivo, a largura do conteúdo medido do item vira a base dele. Um flex: 1 puro e o idioma de navegador flex: 1 1 0 ambos acabam aí, já que um 0 sem unidade não é lido como comprimento. Fatores de grow iguais então somam quantidades iguais de espaço livre sobre larguras iniciais desiguais

Escreva o mesmo dashboard com flex: 1 em todos os cartões e o cartão Revenue, cuja cifra de sete dígitos faz o conteúdo dele ser o mais largo dos três, começa mais largo que o cartão Margin e continua mais largo por exatamente essa quantidade depois do crescimento, porque cada cartão recebe o mesmo um terço do espaço livre que sobrar. Para toolbars, listas de tags e fileiras de botões isso costuma ser o visual que você quer de qualquer forma. Para um dashboard, não. Qualquer coisa que precise alinhar com uma tabela acima ou abaixo merece bases explícitas em porcentagem ou points com grow em 0, que é a nossa recomendação e exatamente o que o exemplo faz: os três cartões então caem em 248.5, 124.25 e 124.25 points em toda página, digam o que disserem as cifras dentro deles

A direção de coluna segue a mesma lógica no eixo vertical. A base vem do flex-basis ou do height, senão da altura do conteúdo medido, e o espaço livre só existe quando o container declara um height. Sem um, o container tem exatamente a altura dos itens dele e o justify-content não tem nada para distribuir

Tracks de grid, posicionamento e spans

Para display: grid, a PDF Library for Delphi lê grid-template-columns e grid-template-rows como comprimentos fixos, porcentagens, unidades fr, repeat(n, track) e minmax(a, b). Tracks fixas e gaps são subtraídos da largura disponível, e o resto é dividido pelo peso dos fr. Uma track minmax() é dimensionada pelo segundo argumento, então minmax(120px, 1fr) se comporta como 1fr, e tracks auto, min-content e max-content pegam cada uma uma cota do espaço livre

Diagrama do PDF Library for Delphi dos valores de track de grid aceitos, posicionamento determinístico de ocupação com sobreposição intencional permitida, e um item que abrange linhas retornando sua altura média entre as linhas que cobre
As tracks de grid aceitam comprimentos, percentuais, unidades fr, repeat e minmax, enquanto o posicionamento automático percorre a matriz de ocupação de forma determinística

O posicionamento é determinístico. Itens auto-posicionados caminham pelo grid linha por linha (ou coluna por coluna com grid-auto-flow: column) e pulam células já ocupadas. Um item com só uma linha dada procura nessa linha uma coluna livre; um item com só uma coluna dada procura descendo essa coluna. Itens com as duas coordenadas vão exatamente para onde dizem, mesmo por cima de outro item, que é como um badge fica sobreposto a um cartão

Spans pedem um hábito. O renderizador lê um span da parte depois da barra, como em grid-row: 1 / span 2, ou de grid-row-end: span 2 e grid-column-end: span 2. O grid-row: span 2 puro que navegadores aceitam como valor inteiro não está entre essas grafias, então mantenha a linha inicial e a barra

// Folha de inspeção: coluna de rótulos fixa, duas colunas flexíveis
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);

Nessa caixa de 515 points, a coluna de rótulos tem 120 points, os dois gaps levam 12, e cada coluna 1fr recebe 191.5. A célula Site plan tem linha mas não coluna, então cai na coluna 1 e cobre as linhas 1 e 2. Inspector e Date preenchem o resto da linha 1. O resumo tem coluna mas não linha, então o posicionamento procura descendo a coluna 2, acha a linha 1 ocupada e se estabelece na linha 2 atravessando as duas colunas flexíveis

As alturas de linha vêm do conteúdo. Como um item que atravessa linhas divide a altura medida igualmente pelas linhas que cobre, e cada linha então pega a maior cota que qualquer item nela pedir, a altura extra de uma célula alta se espalha por todas as linhas que ela toca em vez de desabar na primeira. Uma célula Site plan alta, portanto, levanta as duas linhas um pouco em vez de esticar só a primeira e deixar o Findings summary flutuando em um vão

Containers passam entre caixas em uma peça só

Um container flex ou grid nunca é dividido entre duas caixas. Nunca. Quando o container inteiro não cabe no espaço restante, o container e tudo depois dele vão para o remainder retornado, e como esse remainder é exatamente o que você passa para a próxima caixa ou a próxima página, a linha de cartões simplesmente abre o frame seguinte com a geometria medida intacta. Meio tile de KPI no pé da página 3 e a outra metade na página 4 é pior que um vão, e é esse o trade-off que a regra faz. Um container mais alto que uma caixa inteira vazia é a exceção: ele é desenhado no topo dessa caixa de qualquer forma e passa da borda inferior, porque nenhuma caixa posterior seria maior

A consequência prática é que você deve conhecer a altura de um container antes de comprometê-lo com uma página. GetHTMLTextHeight(Width, HTMLText) mede sem desenhar, flex e grid incluídos

// GridHtml, Y e PageBottom pertencem ao seu código de relatório
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;

A medição tem limite de propósito, o que importa quando clientes editam templates. Um container flex ou grid toma os primeiros 256 filhos diretos, o posicionamento em grid funciona dentro de 64 linhas, e uma lista de tracks guarda no máximo 64 tracks, com contagens de repeat() limitadas para acompanhar. Um container flex com centenas de filhos quase sempre é uma tabela de dados disfarçada, e o caminho de tabela, com medição de colunas própria e suporte a rowspan, o diagrama melhor de qualquer forma

Como as notas de rodapé ficam junto com a referência?

A PDF Library for Delphi mede cada nota no momento em que encontra a referência e subtrai essa altura do orçamento do corpo da caixa atual. Uma nota é escrita como <aside style="float:footnote">, <aside role="doc-footnote"> ou um elemento <footnote>. A referência vira um número em sobrescrito a dois terços do tamanho da fonte ao redor, e o texto da nota é composto a 8 points com entrelinha de 10 points, precedido do mesmo número

Se o corpo até agora mais a nota nova não couberem mais, o marcador e tudo depois dele mudam para o remainder juntos. Nota e referência viajam em par. Essa é a resposta ao cenário de abertura: a linha da referência e a nota dela abrem a próxima coluna, e nem a sobreimpressão nem a nota órfã podem acontecer. Em uma caixa limitada, a área de notas fica presa ao pé sob uma fileta cinza fina com um quarto da largura da caixa. Em medição sem limites, como GetHTMLTextHeight, não há um pé para prender, então as notas seguem o corpo diretamente

Diagrama do PDF Library for Delphi da paginação de notas de rodapé: a área de notas é reservada sob um filete na parte inferior de sua caixa, uma nota que não cabe viaja para a linha de continuação junto com seu marcador, e a numeração permanece contínua entre páginas
O espaço de notas de rodapé é reservado do orçamento do corpo antes que mais texto flua, e a numeração sobrevive entre colunas e páginas

A numeração começa em 1 para cada string HTML nova. O próximo número é guardado dentro da própria string de remainder, então cadeias de DrawHTMLTextBox e o DrawHTMLStory mantêm uma sequência contínua entre colunas e páginas, desde que o remainder seja passado de volta exatamente como foi retornado. Reconstruir a continuação a partir do seu próprio texto de origem reinicia a contagem

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;                 // o resto do seu capítulo

// 2 colunas, calha de 16 pt, no máximo 20 páginas; a story adiciona páginas sozinha
Rest := Lib.DrawHTMLStory(40, 40, 515, 760, 2, 16, 20, Chapter);
Err := Lib.LastErrorCode;          // leia uma vez: ler reseta

if Err = PDFLIB_ERROR_HTML_STORY_INVALID then
  // geometria ruim: colunas 1..64, MaxPages 1..10000, calhas mais estreitas que a largura
else if Err = PDFLIB_ERROR_HTML_STORY then
  // dois frames seguidos sem progresso
else if Rest <> '' then
  // 20 páginas usadas e texto restante: continue depois com Rest
  ;

O DrawHTMLStory(Left, Top, Width, Height, Columns, Gutter, MaxPages, HTMLText) começa na página atual, preenche as colunas da esquerda para a direita e adiciona páginas com as mesmas dimensões até o texto acabar ou o MaxPages ser alcançado. Distinguir esses três desfechos é a razão para ler o LastErrorCode antes de testar a string retornada. Argumentos inválidos retornam a entrada sem alteração, o que de resto parece exatamente com uma story que ficou sem páginas

Alimentando o layout com conteúdo real

Para corpo de texto em várias colunas, o comportamento de colunas e hifenização descrito em hifenização e colunas de texto balanceadas governa como o fluxo fica dentro de cada coluna. Quando a marcação vem de dados em vez de templates escritos à mão, o motor de relatórios de dataset é a rota que a gera antes de flex e grid a arrumar na página. Conteúdo que depois precisa sair do PDF de novo passa por exportação de PDF para Markdown e DOCX

Layout HTML com flex, grid e notas de rodapé, geração de relatórios e exportação semântica vêm em uma única biblioteca para Delphi, C++Builder e Free Pascal. A página do produto PDF Library for Delphi lista o resto do renderizador de HTML e a API de desenho