Processamento de dados

O DataProcessor recebe a definição e o payload, e produz um ProcessedData com:

• detailRows: registros resolvidos para cada data source
• aggregates: valores calculados (SUM, COUNT, AVG, MAX, MIN)
• calculated: campos de expressão resolvidos
• errors: erros encontrados em modo resilient

Bindings

Um FieldElement usa a propriedade binding para referenciar campos do registro:

{ "type": "field", "id": "f1", "x": 0, "y": 0, "width": 200, "binding": "product" }

O engine substitui product pelo valor do registro atual na detail band.

Expressões em bindings

O binding aceita expressões aritméticas:

{ "binding": "quantity * price" }

Variáveis de contexto

O engine disponibiliza variáveis automáticas que podem ser usadas em bindings, expressões e condições. O escopo depende do tipo de band e do tipo de elemento:

Variável	Disponível em	Sintaxe
Campo do registro	FieldElement em detail	binding: "campo"
Campo do payload global (dot-path)	FieldElement em header/footer/summary	binding: "empresa.nome"
Número de página	FieldElement e TextElement — somente PDF	binding: "page" ou {page} no content
Total de páginas	FieldElement e TextElement — somente PDF	binding: "totalPages" ou {totalPages} no content
Número de página (expressão)	printWhen de bands — somente PDF	pageNumber
Total de páginas (expressão)	printWhen de bands — somente PDF	totalPages
Data atual	bindings e printWhen	TODAY()
Data e hora atual	bindings e printWhen	NOW()

Ver a referência completa de expressões →

Formatação

A propriedade format controla como o valor é exibido:

Format	Exemplo de saída	Descrição
""	2500	Sem formatação (toString)
"currency:BRL"	R$ 2.500,00	Real brasileiro
"currency:USD"	$2,500.00	Dólar americano
"date:dd/MM/yyyy"	16/02/2026	Data formatada
"datetime:dd/MM/yyyy HH:mm"	16/02/2026 14:30	Data e hora
"integer"	42	Sem casas decimais
"number:2"	42.50	2 casas decimais
"#,##0.00"	1.250,75	Padrão estilo Excel/JasperReports
"#,##0"	1.250	Inteiro com separador de milhar
"0.00"	250,75	Decimal sem separador de milhar

Tokens de data: dd (dia), MM (mês), yyyy (ano), HH (hora 24h), mm (minuto), ss (segundo).

Padrões numéricos estilo Excel

O engine aceita padrões no formato #,##0.00, #,##0, 0.00, etc. (mesmo estilo do Excel e JasperReports). A vírgula (,) ativa o separador de milhar (ponto .) e o ponto (.) determina a quantidade de casas decimais:

Padrão	Entrada	Saída
#,##0.00	1250.75	1.250,75
#,##0	1250	1.250
0.00	250.75	250,75
#,##0.000	1250.7	1.250,700

O separador de milhar usa . e o decimal usa , (convenção brasileira). Para outros separadores use currency:BRL ou currency:USD.

{
  "type": "field",
  "id": "price",
  "x": 300,
  "y": 5,
  "width": 100,
  "binding": "amount",
  "format": "currency:BRL"
}

Arredondamento

Para campos numéricos, é possível configurar o arredondamento:

{
  "type": "field",
  "id": "avg",
  "x": 0,
  "y": 0,
  "width": 100,
  "binding": "value",
  "format": "number:2",
  "rounding": {
    "precision": 2,
    "mode": "half_even"
  }
}

Modos de arredondamento (exemplos com precisão 2):

Modo	O que faz	2.545 →	2.534 →
half_even	No empate (dígito 5), vai para o par mais próximo. Padrão bancário, evita viés.	2.54	2.53
half_up	No empate, arredonda para cima. O arredondamento clássico.	2.55	2.53
half_down	No empate, arredonda para baixo.	2.54	2.53
up	Sempre para cima (direção +∞).	2.55	2.54
down	Sempre para baixo (direção −∞).	2.54	2.53
truncate	Corta as casas decimais excedentes.	2.54	2.53

Agregados

AggregateElement calcula valores sobre todos os registros de um data source:

{
  "type": "aggregate",
  "id": "total",
  "x": 300,
  "y": 10,
  "width": 100,
  "verb": "SUM",
  "dataSourceId": "items",
  "targetKey": "price",
  "format": "currency:BRL"
}

Verbos disponíveis: SUM, COUNT, AVG, MAX, MIN.

Expressões avançadas

O ExpressionEvaluator suporta funções, comparações e ternários. Ver a referência completa de expressões.

Exemplos rápidos:

quantity * price           → aritmética
UPPER(customer)            → texto
if(amount > 1000, 'VIP', 'Regular') → ternário
TODAY()                    → data atual

Pipeline no código

final engine = SulfiteEngineImpl();
final report = await engine.parseReport(jsonString);
final context = await engine.processData(report, payload);

// context contém '_processedData', 'detailRows', 'aggregates', etc.
// Passe direto para qualquer renderer:
final pdf = await engine.renderToPdf(context);

O processData retorna um Map<String, dynamic> que deve ser passado intacto ao renderer.

Próximo passo

Visão geral dos elementos →