Tutorial: Exportação multi-formato#

O Sulfite gera o mesmo relatório em 4 formatos a partir de uma única definição JSON. Neste tutorial você vai entender como cada formato renderiza os elementos e como tirar o melhor proveito de cada um.

Formatos disponíveis#

Gerar todos os formatos#

import 'dart:convert';
import 'dart:io';
import 'package:sulfite_core/sulfite_core.dart';

void main() async {
  final engine = SulfiteEngineImpl();

  final report = await engine.parseReport(
    File('report.json').readAsStringSync(),
  );
  final data = jsonDecode(File('data.json').readAsStringSync());
  final ctx = await engine.processData(report, data);

  // PDF — layout pixelPerfeito
  final pdf = await engine.renderToPdf(ctx);
  File('relatorio.pdf').writeAsBytesSync(pdf);

  // HTML — visualização web com Chart.js
  final html = await engine.renderToHtml(ctx);
  File('relatorio.html').writeAsStringSync(html);

  // CSV — dados tabulares puros (RFC 4180)
  final csv = await engine.renderToCsv(ctx);
  File('relatorio.csv').writeAsStringSync(csv);

  // Excel — planilha .xlsx
  final xlsx = await engine.renderToExcel(ctx);
  File('relatorio.xlsx').writeAsBytesSync(xlsx);
}

O que cada formato renderiza#

Elementos visuais vs. tabulares#

Detalhes por formato#

PDF

• Layout posicional exato (coordenadas x, y)
• Multi-página automática com header/footer repetidos
• Fontes customizadas via FontLoader
• Gráficos renderizados nativamente via package:pdf

HTML

• Layout posicional via CSS absolute/relative
• Gráficos renderizados com Chart.js 4 (CDN) — interativos com hover e tooltips
• Multi-página representada como seções <div>
• Responsivo quando desejado

CSV

• Segue RFC 4180 (compatível com Excel, Google Sheets)
• Apenas dados tabulares das bands detail
• Campos do esquema viram colunas
• Formato puro, sem estilo visual

Excel

• Arquivo .xlsx válido
• Dados das bands detail com formatação básica
• Compatível com Excel, LibreOffice, Google Sheets
• Suporta múltiplas linhas de agregação

Comparando saídas#

Uma boa prática é validar que todos os formatos produzem dados consistentes:

// Verificar que nenhum formato está vazio
assert(pdf.isNotEmpty);
assert(html.isNotEmpty);
assert(csv.isNotEmpty);
assert(xlsx.isNotEmpty);

// CSV e Excel devem ter o mesmo número de linhas de dados
final csvLines = csv.split('\n').where((l) => l.trim().isNotEmpty).length;
// csvLines inclui header + registros

Dicas#

• Use PDF para relatórios que serão impressos ou enviados por email
• Use HTML quando quiser gráficos interativos ou embedding em sistemas web
• Use CSV para importação em outros sistemas ou pipelines de dados
• Use Excel quando o destinatário precisa de filtros e fórmulas nativas
• Todos os formatos respeitam os mesmos dados e parâmetros — a diferença é apenas visual

Exemplo prático: comparação de 3 relatórios#

O projeto inclui testes automatizados que geram todos os exemplos em todos os formatos e comparam a consistência:

examples/
├── 06-grouped-sales/    → GroupBands + Expressões
├── 07-dashboard/        → Charts + RichText + Table
└── 08-hr-report/        → Parameters + Validação

Cada exemplo é testado em:

• Parse correto do JSON
• Geração PDF, HTML, CSV e Excel (todos não-vazio)
• Contagem de linhas CSV vs Excel (consistência)
• HTML contém <table> ou <th> esperados

Próximos passos#

• PDF (referência) →
• HTML (referência) →
• CSV (referência) →
• Excel (referência) →