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 tamanhosmin-emax-. - Tabelas com
colspanerowspan, 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-columnscom comprimentos,fr,autoerepeat(), além degap). position: relativeeabsolute,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; }@pagedefine 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-afterebreak-insidecontrolam onde uma página pode terminar. Usebreak-inside: avoidpara 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
:hovere tudo o mais que só faz sentido em uma tela. @font-facee@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.
Continue lendo
Primeiros passos
HTML para PDF: biblioteca, navegador headless ou API? Como escolher
Três jeitos de transformar HTML em PDF, o que cada um pede para rodar e manter, que HTML e CSS você recebe, e uma lista curta de perguntas que decidem.
4 min de leitura
Primeiros passos
Como gerar fatura em PDF com uma API
Monte um template de fatura com itens em loop, moeda e data por país, e gere o PDF com uma requisição. Exemplo completo em HTML e curl.
2 min de leitura
Primeiros passos
Como gerar PDF a partir de HTML com uma única requisição
Envie HTML e dados em um POST e receba o PDF. Exemplo em curl e Node.js, e o que saber sobre imagens, limites e créditos.
2 min de leitura
Código e integrações
Gerar PDF no ASP.NET Core: MVC, Razor Pages e minimal APIs
Transforme uma view Razor em PDF no ASP.NET Core com uma chamada de API: renderizador de views, view pronta para impressão, action MVC e handler do Razor Pages.
3 min de leitura