🚀 Apresentando Papiro: Uma Biblioteca Nativa e Gratuita de HTML para PDF no .NET MAUI

Desenvolver aplicativos móveis muitas vezes exige a geração de relatórios em PDF — notas fiscais, ordens de serviço, recibos ou documentos personalizados. O problema? As soluções existentes costumam ser complexas, caras ou excessivamente pesadas para necessidades simples.

É por isso que criei o Papiro, uma biblioteca gratuita e totalmente nativa para converter HTML em PDF em aplicações .NET MAUI, sem dependências externas, navegadores embutidos ou licenças comerciais caríssimas.

Logo Papiro

😩 O Problema das Soluções Atuais

Se você já tentou gerar PDFs em aplicativos móveis, provavelmente esbarrou em um destes cenários:

Bibliotecas comerciais caras: Ferramentas como iText ou Syncfusion exigem licenças que podem custar milhares de dólares anualmente.
APIs de baixo nível tediosas: Desenhar cada elemento do PDF manualmente (traçar linhas, calcular coordenadas x/y) é trabalhoso e torna a estilização um pesadelo.
Soluções baseadas em navegador: Embarcar dependências pesadas como Chromium aumenta drasticamente o tamanho do seu app.
Excesso de recursos desnecessários: Muitas bibliotecas MAUI são projetadas para cenários corporativos complexos quando tudo que você precisa é de um relatório simples.

💡 Por Que HTML é a Solução Ideal

HTML é a linguagem de templates perfeita para relatórios. Todo desenvolvedor conhece, é fácil de estilizar com CSS, pode ser pré-visualizado em qualquer navegador e oferece total flexibilidade de design.

O Papiro preenche essa lacuna: você escreve seu relatório em HTML, usa placeholders simples como {{nome_cliente}} para dados dinâmicos e gera um PDF nativo em segundos.

✨ Principais Funcionalidades

Funcionalidade	Descrição
🆓 100% Gratuito	Usa APIs nativas das plataformas Android e iOS. Sem iText, sem Chromium, sem Syncfusion.
⚡ Extremamente Leve	Sem dependências externas pesadas. A biblioteca adiciona menos de 100KB ao seu app.
📄 Paginação Automática	Divide automaticamente conteúdo longo em múltiplas páginas A4.
🎨 Alta Qualidade Visual	Usa fator de escala 3x para garantir texto e imagens nítidos (~220 DPI).
📱 Renderização Nativa	Utiliza o motor WebView da plataforma subjacente para renderização consistente.
🔄 Async/Await Moderno	Interface assíncrona moderna com objetos de resultado detalhados.
🏷️ Sistema de Templates	Suporte integrado para substituição de tags `{{variavel}}`.
⏱️ Proteção contra Travamentos	Timeout embutido de 30 segundos previne travamentos infinitos na renderização.

📦 Instalação Rápida

Adicione o pacote NuGet ao seu projeto .NET MAUI:

<PackageReference Include="CwSoftware.Papiro" Version="1.0.0" />

Registre o serviço no MauiProgram.cs:

using CwSoftware.Papiro;

public static MauiApp CreateMauiApp()
{
    var builder = MauiApp.CreateBuilder();

    builder
        .UseMauiApp<App>()
        .UsePapiro();  // ✅ Adicione esta linha

    return builder.Build();
}

🛠️ Exemplo Prático: Gerando uma Nota Fiscal

Veja como é simples gerar um PDF com dados dinâmicos usando o Papiro:

using CwSoftware.Papiro;
using System.Globalization;

public class InvoiceService
{
    private readonly IHtmlToPdfService _pdfService;

    public InvoiceService(IHtmlToPdfService pdfService)
    {
        _pdfService = pdfService;
    }

    public async Task<string?> GerarNotaFiscalAsync(string cliente, decimal total)
    {
        // 1. Defina seu template HTML
        string template = @"
            <html>
            <head>
                <style>
                    body { font-family: Helvetica, Arial, sans-serif; padding: 40px; }
                    h1 { color: #2c3e50; border-bottom: 3px solid #3498db; padding-bottom: 10px; }
                    .info { margin: 20px 0; background: #f8f9fa; padding: 15px; border-radius: 5px; }
                    .total { font-size: 24px; font-weight: bold; color: #27ae60; margin-top: 30px; text-align: right; }
                    table { width: 100%; border-collapse: collapse; margin-top: 20px; }
                    th { background: #3498db; color: white; padding: 10px; text-align: left; }
                    td { border-bottom: 1px solid #ddd; padding: 10px; }
                </style>
            </head>
            <body>
                <h1>📋 Nota Fiscal de Serviço</h1>

                <div class='info'>
                    <p><strong>Cliente:</strong> {{Cliente}}</p>
                    <p><strong>Data:</strong> {{Data}}</p>
                    <p><strong>Nº Nota:</strong> #{{Id}}</p>
                </div>

                <table>
                    <tr><th>Descrição</th><th>Valor</th></tr>
                    <tr><td>Consultoria Técnica</td><td>{{Total}}</td></tr>
                </table>

                <p class='total'>Valor Total: {{Total}}</p>
            </body>
            </html>";

        // 2. Substitua as tags por dados reais
        string html = HtmlTemplateHelper.ReplaceTags(template, new 
        {
            Cliente = cliente,
            Id = new Random().Next(1000, 9999),
            Data = DateTime.Now.ToString("dd/MM/yyyy"),
            Total = total.ToString("C2", new CultureInfo("pt-BR"))
        });

        // 3. Gere o PDF
        var result = await _pdfService.ConvertAndSaveAsync(html, "nota-fiscal.pdf");

        if (result.IsSuccess)
        {
            // Abra o PDF gerado usando o launcher nativo
            await Launcher.Default.OpenAsync(new OpenFileRequest
            {
                Title = "Nota Fiscal",
                File = new ReadOnlyFile(result.FilePath!)
            });
            return result.FilePath;
        }

        Console.WriteLine($"Erro: {result.ErrorMessage}");
        return null;
    }
}

🖼️ Lidando com Imagens e Logos

Usar imagens locais na geração de HTML para PDF pode ser complicado devido a restrições de acesso a arquivos em dispositivos móveis. O Papiro facilita isso fornecendo helpers para converter imagens em strings Base64, que podem ser incorporadas diretamente no seu HTML.

// De um arquivo local
string logoBase64 = await HtmlTemplateHelper.ImageToBase64Async("/storage/emulated/0/logo.png");

// De um recurso embutido no seu app
string logoBase64 = await HtmlTemplateHelper.EmbeddedResourceToBase64Async("MeuProjeto.Resources.Images.logo.png");

// Use no seu HTML
string template = @"<img src='{{LogoBase64}}' alt='Logo' width='150' />";
string html = HtmlTemplateHelper.ReplaceTags(template, new { LogoBase64 = logoBase64 });

📱 Suporte de Plataforma

Android: API 21+ (Lollipop). Usa PdfDocument e paginação manual via Canvas.
iOS: iOS 11+. Usa UIMarkupTextPrintFormatter e UIPrintPageRenderer.

📂 Conclusão

Gerar PDFs em aplicativos móveis não precisa ser caro ou complicado. O Papiro oferece uma solução simples, nativa e gratuita que aproveita o HTML — uma tecnologia que todo desenvolvedor já conhece — para criar documentos profissionais em segundos.

Se você está construindo aplicativos comerciais com .NET MAUI e precisa de relatórios, notas fiscais ou recibos, experimente o Papiro.

🔗 Links Úteis

Repositório GitHub: CW-Software-Apps/Papiro-MAUI-HtmlToPDF
Pacote NuGet: CwSoftware.Papiro
App de Exemplo: Ver Exemplos

Se você achou esta biblioteca útil, por favor deixe uma estrela ⭐ no GitHub!