Pular para o conteúdo principal
API PDF4meIntegraçõesBase de conhecimentoExtensõesTestador de APIBlog

Repetição de Parágrafos - Guia de Loop para Cada Parágrafo

Os documentos frequentemente contêm estruturas de conteúdo repetidas, como listas de itens, múltiplos registros ou seções repetidas com formatação semelhante. PDF4meO mecanismo de modelos do [nome da plataforma] oferece recursos de iteração poderosos para gerar vários parágrafos e seções dinamicamente a partir de coleções de dados.

Entendendo os Loops Foreach​

O foreach O loop é o principal mecanismo para iterar por coleções de dados e gerar conteúdo repetido. Cada iteração processa um item da coleção e gera a saída correspondente.

Sintaxe básica do comando foreach​

<<foreach [item in collection]>>
  Content with <<[item.property]>>
<</foreach>>

Componentes:

  • item - Variável que representa o elemento atual na iteração
  • collection - O array ou coleção de dados a ser iterado
  • Bloco de conteúdo - Conteúdo do modelo repetido para cada item

Parágrafos repetidos​

Gere vários parágrafos percorrendo uma coleção de dados e criando texto formatado para cada item.

Exemplo: Classificações de aplicativos​

Sintaxe do modelo:

<<foreach [app in applications]>><<[app.listAppName]>> in <<[app.listAppType]>> platform is a <<[app.category]>> app and has a <<[app.AppRating]>> rating.
<</foreach>>

Fonte de dados (JSON):

{
  "surveyName": "Top-rated Apps",
  "applications": [
    {
      "listAppName": "Instagram",
      "listAppType": "iOS",
      "category": "Social Media",
      "AppRating": "4.9"
    },
    {
      "listAppName": "Whatsapp",
      "listAppType": "iOS",
      "category": "Chat",
      "AppRating": "4.8"
    },
    {
      "listAppName": "Player UG",
      "listAppType": "Android",
      "category": "Gaming",
      "AppRating": "4.75"
    }
  ]
}

Resultado gerado:

Instagram in iOS platform is a Social Media app and has a 4.9 rating.
Whatsapp in iOS platform is a Chat app and has a 4.8 rating.
Player UG in Android platform is a Gaming app and has a 4.75 rating.

Lidando com coleções vazias​

Quando uma coleção estiver vazia, use o Any() Método para verificar a existência de dados antes de iterar. Isso evita exceções de valor nulo e permite exibir conteúdo alternativo.

Verificação básica de valores nulos​

Modelo com verificação Any():

<<if [applications.Any()]>>
<<foreach [app in applications]>><<[app.listAppName]>> in <<[app.listAppType]>> platform is a <<[app.category]>> app and has a <<[app.AppRating]>> rating.
<</foreach>>
<<else>>No applications listed
<</if>>

Esta abordagem:

  1. Verifica se a coleção contém algum item.
  2. Percorre os itens, se disponíveis.
  3. Exibe uma mensagem alternativa caso a coleção esteja vazia.

Loops foreach aninhados​

Crie estruturas hierárquicas aninhando loops foreach uns dentro dos outros. Isso é útil para exibir relações pai-filho ou estruturas de dados multiníveis.

Exemplo: Departamento e Funcionários​

Modelo:

<<foreach [dept in departments]>>
Department: <<[dept.name]>>
<<foreach [emp in dept.employees]>>
  - <<[emp.name]>> (<<[emp.position]>>)
<</foreach>>
<</foreach>>

Dados:

{
  "departments": [
    {
      "name": "Engineering",
      "employees": [
        { "name": "John Smith", "position": "Senior Developer" },
        { "name": "Jane Doe", "position": "Tech Lead" }
      ]
    },
    {
      "name": "Marketing",
      "employees": [
        { "name": "Mike Johnson", "position": "Marketing Manager" }
      ]
    }
  ]
}

Seções complexas repetidas​

Os loops foreach podem repetir seções inteiras de conteúdo, incluindo vários parágrafos, formatação e estruturas aninhadas.

Repetição de múltiplos parágrafos​

Modelo:

<<foreach [product in products]>>
Product Name: <<[product.name]>>
Description: <<[product.description]>>
Price: $<<[product.price]>>
Available: <<[product.inStock]>>

<</foreach>>

Este modelo gera um bloco de descrição completo para cada produto, mantendo toda a formatação e quebras de parágrafo.

Iteração Condicional​

Combine laços foreach com instruções condicionais para geração seletiva de conteúdo.

Exemplo: Exibição condicional​

Modelo:

<<foreach [employee in employees]>>
<<if [employee.age > 50]>>
Senior Employee: <<[employee.name]>> - Age: <<[employee.age]>>
<</if>>
<</foreach>>

Alternativamente, utilize métodos de enumeração:

Modelo:

<<foreach [employee in employees.Where(e => e.age > 50)]>>
Senior Employee: <<[employee.name]>> - Age: <<[employee.age]>>
<</foreach>>

Formatação dentro de loops​

Aplique formatação aos campos dentro dos loops foreach para obter um estilo de saída consistente.

Modelo:

<<foreach [customer in customers]>>
Customer: <<[customer.name]:caps>>
Last Visit: <<[customer.lastVisit]:"MMMM dd, yyyy">>
Status: <<[customer.status]:upper>>

<</foreach>>

Variáveis de loop e indexação​

Acesse informações sobre a posição do loop usando variáveis implícitas (se suportadas pela versão do seu mecanismo de templates).

Variáveis de Loop Comuns​

  • Índice do item atual (baseado em 0 ou em 1, dependendo da implementação)
  • Contagem de iterações do loop
  • Indicadores de primeiro/último item

Exemplo de uso (se compatível):

<<foreach [item in items]>>
<<[$index + 1]>>. <<[item.name]>>
<</foreach>>

Considerações sobre o desempenho​

Melhores práticas para loops​

  1. Limitar o tamanho da coleção - Filtrar coleções grandes antes do processamento do modelo
  2. Evite ninhos muito profundos. - Limite os loops aninhados a 2 ou 3 níveis para melhor desempenho.
  3. Dados de pré-processamento - Realizar cálculos complexos antes de passar os dados para os modelos.
  4. Utilize consultas eficientes Filtrar e classificar dados no nível da fonte de dados

Exemplo: Dados pré-filtrados​

Em vez de:

<<foreach [emp in employees.Where(e => e.age > 30).OrderBy(e => e.name)]>>

Pré-filtre os dados em sua aplicação e passe-os filtrados:

<<foreach [emp in filteredEmployees]>>

Padrões comuns​

Padrão 1: Lista Numerada​

<<foreach [item in items]>>
<<[$index]>>. <<[item.title]>>
<</foreach>>

Padrão 2: Conteúdo Agrupado​

<<foreach [category in categories]>>
## <<[category.name]>>

<<foreach [item in category.items]>>
- <<[item.name]>>
<</foreach>>
<</foreach>>

Padrão 3: Seção de Resumo​

<<foreach [report in reports]>>
Report: <<[report.title]>>
Total Records: <<[report.records.Count()]>>
Average Value: <<[report.records.Average(r => r.value)]>>
<</foreach>>

Solução de problemas​

Problemas comuns​

Emitir: Erros de referência nula Solução: Usar Any() verificar coleções antes da iteração

Emitir: Quebras de linha ou espaçamento indesejados Solução: Gerencie cuidadosamente o espaço em branco em seu modelo.

Emitir: Problemas de desempenho com coleções grandes Solução: Pré-filtre os dados e limite os tamanhos das coleções.

Emitir: Vinculação de dados incorreta Solução: Verifique se os nomes das propriedades correspondem exatamente à sua estrutura de dados.

Exemplo prático: Itens de linha da fatura​

Modelo completo:

Invoice #<<[invoiceNumber]>>
Date: <<[invoiceDate]:"dd.MM.yyyy">>

Items:
<<if [lineItems.Any()]>>
<<foreach [item in lineItems]>>
<<[item.name]:caps>> - Qty: <<[item.quantity]>> - Price: $<<[item.price]:"F2">> - Total: $<<[item.quantity * item.price]:"F2">>
<</foreach>>

Subtotal: $<<[lineItems.Sum(i => i.quantity * i.price)]:"F2">>
<<else>>
No items in this invoice.
<</if>>

:::dica Iterações Complexas Para cenários de iteração complexos, considere pré-processar seus dados na lógica do seu aplicativo antes de passá-los para o modelo. Isso melhora a legibilidade e o desempenho do modelo.

:::