rustedf.cloud
Menu

HTML e CSS para PDF: o que funciona e como conferir

Publicado em 3 min de leitura

Uma página feita para o navegador rola sem fim. Um PDF não: ele tem um tamanho de papel fixo, margens, quebras de página e um cabeçalho e um rodapé que se repetem. É por isso que o mesmo HTML pode parecer certo na tela e errado no papel, e por isso ajuda saber o que um gerador de PDF suporta antes de desenhar para ele.

Isto é o que o gerador do rustedf.cloud suporta, com as armadilhas que vêm junto.

Layout que funciona

  • O modelo de caixas do CSS, incluindo box-sizing, margens e tamanhos min- e max-.
  • Tabelas com colspan e rowspan, e linhas de cabeçalho que se repetem em cada página que a tabela ocupa. É isso que mantém legível uma fatura ou um extrato longo.
  • Flexbox e um subconjunto de grid (grid-template-columns com comprimentos, fr, auto e repeat(), além de gap).
  • position: relative e absolute, z-index, texto em colunas e listas.

Mídia paginada

Esta é a parte que a maioria das páginas web nunca usa, e é o que um documento precisa.

@page {
size: A4;
margin: 20mm;
@bottom-center { content: "Página " counter(page) " de " counter(pages); }
}
.assinatura { break-inside: avoid; }
h2 { break-after: avoid; }
  • @page define o tamanho, a orientação e as margens, e as caixas de margem superiores e inferiores guardam cabeçalhos e rodapés, com o número da página e o total de páginas.
  • break-before, break-after e break-inside controlam onde uma página pode terminar. Use break-inside: avoid para que um bloco de assinatura ou um total nunca seja dividido em duas páginas.
  • Os títulos viram o sumário do PDF, e os links <a href> continuam clicáveis.

Pintura

Cores, fundos, linear-gradient(), bordas sólidas, tracejadas e pontilhadas, border-radius, box-shadow, opacity e overflow: hidden funcionam. As transformações 2D, como rotate() e scale(), também, mas uma transformação só move a pintura de um elemento: ele mantém o espaço que tinha. As transformações 3D são ignoradas.

As imagens são PNG e JPEG, enviadas para a sua conta (asset:<id>) ou embutidas como URLs data:. Formas SVG simples (rect, circle, line) são desenhadas como vetores.

O que deixar de fora

  • JavaScript.
  • Animações e transições.
  • Pseudoclasses como :hover e tudo o mais que só faz sentido em uma tela.
  • @font-face e @import. Você não precisa deles: cite uma família de fontes no seu CSS e o serviço a disponibiliza. Veja o guia de Fontes.
  • Imagens que apontam para um endereço da web. O serviço nunca busca um endereço vindo de um template.

Nada disso quebra a geração por padrão. Um recurso não suportado é ignorado e reportado.

Confira antes de enviar

Ler uma lista não é o mesmo que saber que o seu documento está limpo. POST /v1/validate recebe o mesmo corpo de uma geração e monta o documento, mas devolve um relatório em vez de um PDF, e não usa crédito.

{
"ok": false,
"pages": 1,
"diagnostics": [
{
"kind": "UnsupportedProperty",
"text": "filter",
"context": "inside <p class=\"note\">",
"count": 2
}
]
}

ok é true quando não há nada a reportar. Cada aviso diz o tipo do problema, a propriedade ou a tag envolvida, onde ela estava e quantas vezes aconteceu. Entre os tipos estão UnsupportedTag, UnsupportedProperty, UnsupportedSelector, ImageLoadFailed e LayoutOverflow, que aponta uma caixa mais alta ou mais larga que a página.

Nos testes, acrescente "strict": true a uma geração. Os mesmos avisos passam a falhar a requisição com um 422, e nenhum crédito é usado. Um template que fica limpo na sua suíte de testes fica limpo em produção.

Veja a lista completa em HTML e CSS suportados e em Validar um documento.

← Todos os posts