AJUDA DO .NET

Como Converter HTML para PDF em Rust

Curtis Chau
Curtis Chau
Atualizado: 18 de outubro de 2026

Converter arquivos HTML ou strings HTML brutas para PDF é um requisito comum para faturas, relatórios e recibos. Rust não possui um mecanismo de renderização embutido para isso, e escrever um não é um projeto paralelo realista. A análise de HTML é a parte fácil. A análise de CSS, layout e paginação são onde o trabalho nunca termina, o que faz de um navegador uma escolha natural para geração de PDF em Rust. Este tutorial converte HTML em PDF em Rust com o crate open-source headless_chrome, que permite que o Chrome faça a renderização e devolva o PDF finalizado para o seu programa Rust.

Crate Headless Chrome para Rust

headless_chrome é um crate Rust licenciado sob MIT que controla um navegador Chrome ou Chromium através do Chrome DevTools Protocol. Ele pode abrir páginas, clicar em elementos, tirar capturas de tela e chamar a função integrada de impressão para PDF do Chrome. Como a página é renderizada por um navegador real, layouts CSS, fontes web e JavaScript funcionam da mesma forma que no Chrome.

O Chrome também pode imprimir uma página diretamente pela linha de comando com --print-to-pdf. Isso é apenas uma chamada CLI, então os bytes vão para o disco em vez de para o seu programa, e as configurações de impressão disponíveis são limitadas. Controlar o DevTools Protocol mantém os bytes no seu programa e deixa toda a plataforma web responsável pelo layout. É o mesmo protocolo sobre o qual bibliotecas equivalentes em outras linguagens são construídas. O crate é mantido pela comunidade Rust, então o suporte vem do seu rastreador de issues no GitHub.

Pré-requisitos

Para criar um conversor de HTML para PDF em Rust, certifique-se de que os seguintes pré-requisitos estejam em vigor:

  1. Rust 1.85 ou superior. Instale o toolchain Rust com rustup. No Windows, o toolchain MSVC também precisa de uma instalação do Visual Studio, porque rustc usa seu linker e bibliotecas.
  2. Google Chrome, Chromium ou Microsoft Edge instalados. headless_chrome procura o navegador no PATH, na variável de ambiente CHROME e, no Windows, no registro, com Edge como alternativa.
  3. Conhecimento básico de Rust e Cargo.

Este tutorial foi testado com Rust 1.98.1, headless_chrome 1.0.22 e Chrome 153 no Windows 11. O mesmo código roda no Linux e macOS.

Criando um Projeto Rust HTML para PDF com Cargo

Crie o projeto binário e adicione ambas as dependências a partir de um terminal:

cargo new html_to_pdf
cd html_to_pdf
cargo add headless_chrome urlencoding
SHELL

O passo 3 usa o crate urlencoding para passar a string HTML ao Chrome como uma data URL.

Como Converter HTML para PDF em Rust: Figura 1 - Criando o projeto e adicionando dependências

Verificando o Cargo.toml

Após rodar cargo add, ambos os crates aparecem em [dependencies] no arquivo Cargo.toml:

[package]
name = "html_to_pdf"
version = "0.1.0"
edition = "2024"

[dependencies]
headless_chrome = "1.0.22"
urlencoding = "2.1.3"
Text

Como Converter HTML para PDF em Rust: Figura 2 - Dependências do Cargo.toml

O recurso padrão offline do crate usa um navegador já instalado. Se a máquina de destino não tiver o Chrome, ative o recurso fetch (cargo add headless_chrome --features fetch) e o crate pode baixar uma build do Chromium para você.

Passos para Converter HTML em PDF em Rust

Passo 1: Importando os Crates

Abra src/main.rs e substitua seu conteúdo pelos imports necessários ao programa. Browser e LaunchOptions iniciam o Chrome, e PrintToPdfOptions controla a saída em PDF:

use std::fs;

use headless_chrome::types::PrintToPdfOptions;
use headless_chrome::{Browser, LaunchOptions};
Rust

Passo 2: Iniciando o Headless Chrome

Em seguida, inicie um navegador headless e abra uma aba. main retorna um Result para que cada chamada possa usar o operador ? em vez de unwrap:

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Launch a headless Chrome instance
    let browser = Browser::new(LaunchOptions {
        headless: true,
        ..Default::default()
    })?;

    // Open a new tab to load the HTML into
    let tab = browser.new_tab()?;
Rust

Browser::default() dá o mesmo resultado com menos código. LaunchOptions é mostrado aqui porque é onde você define o tamanho da janela, o caminho do Chrome ou a flag de sandbox quando necessário.

Passo 3: Definindo o Conteúdo HTML

Agora forneça o HTML que deve virar PDF. A sintaxe de string bruta do Rust r#"..."# mantém as aspas do HTML legíveis:

    let html = r#"
        <html>
        <head>
            <style>
                body { font-family: Arial, sans-serif; margin: 40px; }
                h1 { color: #2a5db0; }
                table { border-collapse: collapse; width: 100%; }
                th, td { border: 1px solid #ccc; padding: 8px; text-align: left; }
                th { background-color: #f0f4fa; }
            </style>
        </head>
        <body>
            <h1>Hello, World!</h1>
            <p>This PDF was generated from an HTML string in Rust.</p>
            <table>
                <tr><th>Item</th><th>Quantity</th><th>Price</th></tr>
                <tr><td>Widget</td><td>2</td><td>$10.00</td></tr>
                <tr><td>Gadget</td><td>1</td><td>$25.00</td></tr>
            </table>
        </body>
        </html>
    "#;

    // Load the HTML string as a data URL and wait for the page to finish loading
    let data_url = format!("data:text/html;charset=utf-8,{}", urlencoding::encode(html));
    tab.navigate_to(&data_url)?.wait_until_navigated()?;
Rust

print_to_pdf não possui uma opção HTML. Ele imprime o que a aba está exibindo, e o crate não tem método para definir o conteúdo da página diretamente, então a string HTML é codificada em porcentagem em uma URL data: e a aba navega até ela.

wait_until_navigated então bloqueia até que a página esteja pronta, e não para no evento de carregamento. O crate ativa os eventos de ciclo de vida do Chrome e limpa sua flag de navegação em networkAlmostIdle, o marco do ciclo de vida do navegador que chega quando as requisições buscadas pela página (idle de rede) cessaram. Quando a aba relata navegação completa, geralmente fontes web e imagens tardias já estão carregadas.

Etapa 4: Convertendo HTML para PDF

Com a página carregada, chame print_to_pdf. PrintToPdfOptions corresponde às configurações de impressão do Chrome, e todos os campos são opcionais:

    // Print the page to PDF with background colors and 0.4 inch margins
    let options = PrintToPdfOptions {
        print_background: Some(true),
        margin_top: Some(0.4),
        margin_bottom: Some(0.4),
        margin_left: Some(0.4),
        margin_right: Some(0.4),
        ..Default::default()
    };
Rust

As margens e tamanhos de papel estão em polegadas. Sem paper_width e paper_height, o Chrome usa US Letter (8,5 x 11 polegadas). O Chrome não imprime cores ou imagens de fundo a menos que você solicite. print_background está desativado por padrão, e sem ela o sombreamento do cabeçalho da tabela é removido do PDF.

Os campos de configuração de página (landscape, scale, page_ranges e os modelos de cabeçalho e rodapé) terão sua própria seção mais adiante neste tutorial.

Etapa 5: Obtendo a Saída como um Vetor de Bytes

print_to_pdf retorna o documento finalizado como um Vec<u8> mantido na memória. Nada é gravado em disco ainda, então os bytes podem ir para um arquivo, corpo de resposta HTTP ou armazenamento em nuvem:

    let pdf_data: Vec<u8> = tab.print_to_pdf(Some(options))?;
Rust

Etapa 6: Salvando o Arquivo PDF

Para salvar o PDF, escreva o vetor de bytes em um arquivo com std::fs::write, que cria o arquivo, grava todos os bytes e o fecha em uma única chamada:

    // Write the PDF bytes to disk
    fs::write("output.pdf", &pdf_data)?;
    println!("PDF saved successfully ({} bytes).", pdf_data.len());

    Ok(())
}
Rust

Etapa 7: Limpando

Diferente da API C do wkhtmltopdf, não há funções destroy ou deinit para chamar. Quando browser sai do escopo ao final de main, sua implementação Drop encerra o processo do Chrome e remove a pasta de perfil temporária criada. Se uma etapa falhar e ? retornar antecipadamente, a mesma limpeza ainda será executada.

Em um serviço de longa duração, mantenha um Browser vivo e abra uma nova aba por documento em vez de iniciar um novo processo do Chrome para cada requisição.

Etapa 8: Execute o Código e Gere o Arquivo PDF

Compile e execute o projeto a partir da pasta do projeto:

cargo run
SHELL

A primeira compilação compila 143 crates, o que levou 45 segundos na máquina utilizada aqui. O programa então imprime o tamanho do arquivo gerado:

Como Converter HTML para PDF em Rust: Figura 3 - saída do cargo run

O arquivo output.pdf é salvo na pasta do projeto. Os estilos CSS, incluindo a cor do cabeçalho e as bordas e fundo da tabela, são preservados:

Como Converter HTML para PDF em Rust: Figura 4 - Saída do PDF

Aqui está o próprio output.pdf gerado:

Converter uma URL ou Arquivo HTML para PDF em Rust

As mesmas chamadas navigate_to e print_to_pdf funcionam para páginas web e arquivos HTML locais. Para arquivos locais, adicione o crate url com cargo add url para poder transformar o caminho do arquivo em uma URL file:// válida em qualquer sistema operacional.

O exemplo abaixo lê um template local, então salve isto ao lado de Cargo.toml como invoice.html:

<html>
<head>
    <style>
        body { font-family: Arial, sans-serif; margin: 30px; }
        .box { background: #2a5db0; color: #fff; padding: 16px; }
    </style>
</head>
<body>
    <div class="box"><h2>Invoice #1024</h2></div>
    <p>Loaded from a local HTML file.</p>
</body>
</html>
HTML

Salve o programa abaixo como examples/url_and_file.rs e execute-o com cargo run --example url_and_file:

use std::fs;

use headless_chrome::types::PrintToPdfOptions;
use headless_chrome::Browser;
use url::Url;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let browser = Browser::default()?;
    let tab = browser.new_tab()?;

    // Convert a live web page to PDF
    tab.navigate_to("https://doc.rust-lang.org/book/")?
        .wait_until_navigated()?;
    let url_pdf = tab.print_to_pdf(None)?;
    fs::write("url.pdf", url_pdf)?;

    // Convert a local HTML file to PDF
    let path = fs::canonicalize("invoice.html")?;
    let file_url = Url::from_file_path(&path).map_err(|_| "invalid file path")?;
    tab.navigate_to(file_url.as_str())?.wait_until_navigated()?;

    let options = PrintToPdfOptions {
        landscape: Some(true),
        print_background: Some(true),
        ..Default::default()
    };
    fs::write("invoice.pdf", tab.print_to_pdf(Some(options))?)?;

    println!("Saved url.pdf and invoice.pdf");
    Ok(())
}
Rust

Uma aba lida com ambos os documentos um após o outro. A URL é impressa com os padrões do Chrome, e a nota fiscal local é impressa em paisagem com suas cores de fundo:

Como Converter HTML para PDF em Rust: Figura 5 - URL e arquivo HTML convertidos para PDF

A página web capturada em url.pdf:

E o arquivo HTML local impresso em invoice.pdf em paisagem:

Salve templates com um nome .html, pois o Chrome decide como tratar um arquivo local a partir da extensão de entrada. O mesmo markup salvo como .txt foi impresso como tags visíveis em vez de uma página renderizada.

Tamanho da Página, Números de Página e Quebras de Página

PrintToPdfOptions espelha a caixa de diálogo de impressão do Chrome, e seus valores suportados são os mesmos oferecidos pela própria caixa de diálogo. landscape: Some(true) alterna para o modo paisagem, scale recebe um fator de zoom onde 1.0 é tamanho completo, e page_ranges recebe uma string baseada em 1, como "1-5, 8, 11-13".

Os números de página podem vir de qualquer lado. Dê ao Chrome um modelo de rodapé e ele substitui pageNumber e totalPages em cada página:

let options = PrintToPdfOptions {
    display_header_footer: Some(true),
    header_template: Some("<span></span>".into()),
    footer_template: Some(
        "<div style='font-size:10px;width:100%;text-align:center'>Page <span class='pageNumber'></span> of <span class='totalPages'></span></div>".into()),
    margin_bottom: Some(0.6),
    ..Default::default()
};
Rust

A rota CSS também funciona. O Chrome Platform Status lista as caixas de margem @page a partir do marco 131, então orientações escritas antes disso refletem um comportamento histórico. No Chrome 153, esta regra de contador de página sozinha numerou todas as páginas de um documento de quatro páginas:

@page { @bottom-center { content: "Page " counter(page); } }
CSS

Controlar onde uma quebra de página ocorre também é CSS comum. Um documento de teste com seis cartões mostrou a diferença. Sem a propriedade, a primeira página terminava no meio do terceiro cartão, e o restante desse cartão continuava na página dois. Adicionando a propriedade CSS break-inside, cada cartão foi movido inteiro para a próxima página, dois por página, sem nenhum deles dividido:

.card { break-inside: avoid; }
CSS

O que o Chrome Coloca no PDF

Duas opções alteram a estrutura do arquivo, não a aparência da página:

let options = PrintToPdfOptions {
    generate_document_outline: Some(true),
    generate_tagged_pdf: Some(true),
    ..Default::default()
};
Rust

generate_document_outline transforma seus títulos em marcadores de PDF. Um relatório com um h1 e dois títulos h2 produziu um sumário de três entradas com a opção ativada, e nenhum sumário com ela desativada.

generate_tagged_pdf solicita um PDF marcado, a estrutura que leitores de tela e verificadores PDF/UA leem. A documentação do DevTools Protocol define seu padrão como "embedder choice" em vez de desativado, e o teste aqui confirmou isso. Com ambas as opções desativadas, a saída ainda continha uma árvore de estrutura e carregava o idioma do documento de <html lang="en">. Defina esse atributo em seus modelos de qualquer forma, e verifique sua própria saída antes de confiar na flag.

As fontes são incorporadas com subconjunto de fontes, então uma página definida em Georgia produziu AAAAAA+Georgia-Bold e BAAAAA+Georgia em vez da família completa. Uma fotografia JPEG foi armazenada como JPEG, não re-codificada.

Uso do Headless Chrome em um Serviço Rust

O crate é bloqueante, por isso nenhum dos códigos acima está escrito como um async fn main. Se seu serviço já possui um runtime assíncrono como Tokio, mantenha o navegador fora do reactor chamando-o dentro de tokio::task::spawn_blocking, assim um render lento não pode travar o executor.

Nada fica em polling para sempre. Cada operação de aba roda com um tempo limite e retorna um erro em vez de travar, então uma página que nunca estabiliza não pode prender um worker.

As linhas de inicialização e encerramento do Chrome aparecem em qualquer serviço que instala um logger, porque o crate reporta através do crate log. Para remover logs da camada do navegador sem silenciar os seus próprios, filtre por target, por exemplo RUST_LOG=info,headless_chrome=warn.

Problemas Comuns ao Converter HTML para PDF em Rust

Estes são os modos de falha que aparecem em produção:

  • Conteúdo renderizado por JavaScript: wait_until_navigated retorna assim que a rede fica silenciosa, o que não é o mesmo que um gráfico terminar de ser desenhado. Chame tab.wait_for_element("#report-ready") em um elemento que a página adiciona quando termina, depois imprima.
  • Timeouts: operações de aba expiram após 20 segundos por padrão. Aumente o limite com tab.set_default_timeout(std::time::Duration::from_secs(60)) para páginas lentas.
  • Strings HTML grandes: o Chrome limita URLs a 2 MB, e isso inclui URLs data:. Para documentos maiores, escreva o HTML em um arquivo temporário e carregue-o com uma URL file:// como mostrado acima.
  • Docker e containers Linux: o sandbox do Chrome falha ao iniciar quando o processo roda como root, e o guia de solução de problemas do Puppeteer recomenda fortemente não rodar sem sandbox. Adicione um usuário não privilegiado à imagem e mantenha o sandbox ativado, e defina sandbox: false em LaunchOptions apenas quando não houver alternativa. De qualquer forma, a imagem precisa das bibliotecas de sistema do Chrome.
  • Deploy: todo servidor que executa o programa precisa de um navegador compatível, então o Chrome passa a fazer parte do seu deploy mesmo que o código Rust compile para um binário único.

Outras Formas de Converter HTML para PDF em Rust

headless_chrome não é a única rota. Qual delas se encaixa depende se seus documentos precisam de JavaScript e quantos você renderiza de uma vez.

Baseados em Chromium, como este tutorial

html2pdf se define apenas como um CLI sobre o crate headless_chrome, e também é distribuído como uma biblioteca cuja API é assíncrona e roda em tokio, o que evita que você precise escrever o wrapper spawn_blocking.

Gotenberg move o navegador completamente para fora do seu processo. É uma API baseada em Docker para converter documentos em PDF: o Chromium lida com URLs, HTML e Markdown, o LibreOffice lida com formatos de escritório, e seu serviço Rust envia um arquivo via HTTP e recebe um PDF de volta. Isso mantém o Chrome fora do deploy do seu binário ao custo de rodar um serviço ao lado dele.

Engines Rust sem navegador

O Headless Chrome pode ser intensivo em recursos para geração concorrente de PDFs, pois cada conversão precisa de um processo de navegador e da memória associada. Dois projetos em Rust abordam esse ponto diretamente.

htmltopdf é um engine licenciado pelo MIT que renderiza em uma única thread sem subprocessos, e seu README o descreve como construído para alta concorrência e baixo uso de RAM. O README relata cerca de 92 MB de pico de RAM contra cerca de 846 MB do processo principal do Chromium em um único documento de 1,8 MB. Para 20 conversões concorrentes, relata 12,75 PDF/s a 1,25 GiB contra 1,18 PDF/s do Chromium a 9,35 GiB, medido com /usr/bin/time -l em Apple Silicon. Estes são benchmarks do próprio projeto em seus próprios fixtures, e não foram reproduzidos para este artigo. O crate não está no crates.io, então você o instala a partir do repositório, e o tratamento de JavaScript é uma etapa pré-layout opcional e limitada, não um engine completo.

Fulgur é outro engine de HTML para PDF em Rust que dispensa o navegador. Ele é Apache-2.0, e integra o Blitz para parsing de HTML, resolução de estilos e layout com o Krilla para geração de PDF. O Fulgur suporta um subconjunto selecionado de HTML e CSS, acompanhado propriedade por propriedade em seu documento de suporte a CSS, e sua lista de recursos não inclui engine de JavaScript. O que ele cobre é o lado paginado, incluindo contadores de página, cabeçalhos dinâmicos, caixas de margem, break-inside, PDF com tags e subsetting de fontes. O pipeline de renderização do Fulgur inclui uma renderização em 2 passes para precisão, então referências cruzadas como target-counter() são resolvidas antes que o PDF seja escrito.

Engines comerciais

Prince suporta CSS Paged Media para criação complexa de PDFs, incluindo regras @page, caixas de margem de página e um contador de página predefinido para cabeçalhos e rodapés dinâmicos. O Prince é um software comercial que você licencia, não um crate que adiciona com o Cargo.

Qual se encaixa

Por anos, a regra era que as opções nativas em Rust para HTML para PDF tinham suporte limitado a CSS e JavaScript, então engines puros em Rust serviam apenas para documentos simples. A parte do CSS já está desatualizada. O htmltopdf lista flexbox, grid, tabelas com rowspans e @font-face, e o Fulgur cobre mídia paginada de ponta a ponta. O JavaScript ainda é onde está a lacuna.

O que gera seu documento decide a escolha. Se um servidor renderiza o HTML e o estilo é CSS, um engine sem navegador elimina o Chrome do seu deployment junto com sua memória. Se suas páginas desenham gráficos no navegador ou dependem dos próprios scripts de um web app, mantenha um navegador no pipeline, que é o que este tutorial faz.

IronPDF para Rust (Em breve)

O IronPDF para Rust está em desenvolvimento. A biblioteca planejada irá criar PDFs a partir de HTML e manipular PDFs existentes, tudo a partir de código Rust.

Participe do programa beta do IronPDF para Rust para obter acesso antecipado e ajudar a moldar a API.

Arquivo HTML para Arquivo PDF em C#

IronPDF

A biblioteca de conversão de HTML para PDF IronPDF é uma biblioteca C# para .NET e .NET Core que gera documentos PDF a partir de conteúdo HTML. Ela traz seu próprio engine de renderização Chrome, então não há navegador separado para instalar, iniciar ou encerrar.

O IronPDF lida com mais do que documentos HTML simples. Ele renderiza páginas web complexas com estilização CSS e JavaScript, e também edita, mescla, assina e protege PDFs após sua criação.

O mesmo trabalho com IronPDF, convertendo uma string HTML para PDF em C#:

using IronPdf;

// Instantiate Renderer
var renderer = new ChromePdfRenderer();

// Create PDF content from an HTML string using C#
var pdf = renderer.RenderHtmlAsPdf("<h1>Hello World</h1>");

// Export to a file or Stream
pdf.SaveAs("output.pdf");

A saída em PDF:

Como Converter HTML para PDF em Rust: Figura 6 - Saída do IronPDF

Os passos deste tutorial em Rust correspondem a configurações únicas do IronPDF. A configuração de página é abordada em margens personalizadas e tamanho de papel personalizado, e o problema de espera pelo JavaScript é tratado pelos delays de renderização WaitFor. Converter uma URL para PDF ou um arquivo HTML para PDF requer apenas uma chamada de método cada, e cabeçalhos e rodapés com números de página não precisam de templates HTML. Para um passo a passo completo, veja o tutorial de HTML para PDF, ou leia como a mesma tarefa funciona em HTML para PDF em C++.

Você pode experimentar tudo isso com uma Avaliação Gratuita da Funcionalidade Completa do IronPDF. Ela dura 30 dias, não exige cartão de crédito e funciona em servidores reais sem marcas d'água enquanto você avalia. A licença após esse período é perpétua, sem taxas recorrentes, dimensionada por desenvolvedores, projetos e locais, e conta com garantia de devolução do dinheiro em 30 dias. Para começar, baixe o IronPDF.

Curtis Chau é bacharel em Ciência da Computação (Universidade Carleton) e se especializa em desenvolvimento front-end, com experiência em Node.js, TypeScript, JavaScript e React. Apaixonado por criar interfaces de usuário intuitivas e esteticamente agradáveis, Curtis gosta de trabalhar com frameworks modernos e criar manuais bem estruturados e visualmente atraentes.

Leia Mais

Artigos Relacionados