Inserir imagens - Guia de imagens dinâmico

PDF4me Permite a inserção dinâmica de imagens em documentos gerados, possibilitando o preenchimento de modelos com logotipos, fotografias, gráficos, diagramas e outros conteúdos visuais provenientes de suas fontes de dados. As imagens podem ser fornecidas por meio de fontes públicas. URLs ou Base64-cadeias codificadas.

---

Requisitos de sintaxe de imagem

The image syntax must be placed inside a Text Box in Word for proper image population. Create a text box at the desired location in your template before adding image merge fields.

---

Métodos de Inserção de Imagens

PDF4me Suporta dois métodos para fornecer dados de imagem aos modelos:

Método 1: Imagem Pública URL

Utilizar imagem de acesso público URLs Para inserir imagens de fontes da web.

Sintaxe:

<<image [imageUrl]>>

Exemplo de dados:

{
  "imageUrl": "https://public-url/image.png"
}

Casos de uso:

• Logotipos de empresas hospedados em servidores públicos
• Imagens de produtos provenientes de plataformas de comércio eletrônico
• Gráficos e tabelas gerados e hospedados online
• Imagens de recursos públicos

---

Método 2: Base64 Imagens codificadas

Insira imagens usando Base64Representação em string codificada do arquivo de imagem.

Sintaxe:

<<image [imageBase64]>>

Exemplo de dados:

{
  "imageBase64": "iVBORw0KGgoAAAANSUhEUgAAAfQAAAH0CAYAAADL1t+KAAAACXBIWXMAABcSAAAXEgFnn9JSAACU6ElEQVR4nOz953tjR5bn+34jtoMn6D2ZSaaRL5lSmR5z5t5/+9xzZqZ7qktSeksmvfcG3mzsveO+2ACVUklKUspMksj1eZ7qqpZECCCZ+CEiVqyljDEGIYQQQlxr+rKfgBBCCCH+OAl0IYQQogtIoAshhBBdQAJdCCGE6AIS6EIIIUQXkEAXQggh..."
}

Vantagens:

• Funciona sem conexão com a internet.
• Seguro - sem dependências externas
• Controle total sobre os dados da imagem
• Adequado para documentos confidenciais.

---

Opções de formatação de imagem

Controle o ajuste das imagens dentro das caixas de texto usando opções de formatação. Essas opções determinam o tamanho e a proporção da imagem.

Manter a proporção da tela

Sintaxe: <<image [imageUrl] -keepRatio>>

Comportamento:

• Preserva o tamanho da caixa de texto.
• Ajusta a imagem para caber dentro dos limites da caixa de texto.
• Mantém a proporção original da imagem.
• A imagem pode não preencher toda a caixa de texto se as proporções forem diferentes.

Ideal para: Logotipos, ícones e imagens onde a distorção deve ser evitada.

---

Altura adequada

Sintaxe: <<image [imageUrl] -fitHeight>>

Comportamento:

• Preserva a largura da caixa de texto
• Ajusta a altura da caixa de texto para corresponder à proporção da imagem.
• A imagem preenche completamente a caixa de texto.
• As dimensões da caixa de texto são alteradas para acomodar a imagem.

Ideal para: Imagens de altura variável em layouts flexíveis

---

Largura de ajuste

Sintaxe: <<image [imageUrl] -fitWidth>>

Comportamento:

• Preserva a altura da caixa de texto
• Ajusta a largura da caixa de texto para corresponder à proporção da imagem.
• A imagem preenche completamente a caixa de texto.
• A largura da caixa de texto se ajusta para acomodar a imagem.

Ideal para: Faixas horizontais, cabeçalhos com alturas fixas

---

Tamanho ideal

Sintaxe: <<image [imageUrl] -fitSize>>

Comportamento:

• Altera as dimensões da caixa de texto para corresponder ao tamanho da imagem.
• Utiliza as dimensões originais da imagem.
• A imagem é exibida em tamanho real.
• A caixa de texto se redimensiona para as dimensões exatas da imagem.

Ideal para: Quando o tamanho original da imagem deve ser preservado exatamente.

---

Tamanhos disponíveis limitados

Sintaxe: <<image [imageUrl] -fitSizeLim>>

Comportamento:

• Ajusta a caixa de texto ao tamanho da imagem.
• Não aumentará além das dimensões originais da caixa de texto.
• É possível reduzir o tamanho da caixa de texto se a imagem for menor.
• Impede o aumento da caixa de texto

Ideal para: Limitar o tamanho máximo da imagem, permitindo ao mesmo tempo imagens menores.

---

Comparação de formatação

Opção de formato	Largura	Altura	Proporção da tela	Tamanho da caixa de texto
-keepRatio	Fixo	Fixo	Preservado	Inalterado
-fitHeight	Fixo	Variável	Preservado	Alterações de altura
-fitWidth	Variável	Fixo	Preservado	Alterações de largura
-fitSize	Variável	Variável	Preservado	Ambas mudam
-fitSizeLim	Variável	Variável	Preservado	Restrito

---

Exemplos práticos

Exemplo 1: Logotipo da empresa

Modelo:

[Create a text box in header]
<<image [companyLogo] -keepRatio>>

Dados:

{
  "companyLogo": "https://company.com/images/logo.png"
}

---

Exemplo 2: Imagens do produto

Modelo:

<<foreach [product in products]>>
Product: <<[product.name]>>
[Text box:] <<image [product.imageUrl] -fitHeight>>
Price: $<<[product.price]>>

<</foreach>>

Dados:

{
  "products": [
    {
      "name": "Laptop Pro",
      "imageUrl": "https://example.com/laptop.jpg",
      "price": "1299.99"
    },
    {
      "name": "Wireless Mouse",
      "imageUrl": "https://example.com/mouse.jpg",
      "price": "29.99"
    }
  ]
}

---

Exemplo 3: Imagem de assinatura (Base64)

Modelo:

Authorized Signature:
[Text box:] <<image [signatureBase64] -fitSizeLim>>

Name: <<[signatoryName]>>
Date: <<[signatureDate]:"dd.MM.yyyy">>

Dados:

{
  "signatureBase64": "iVBORw0KGgoAAAANSUhEUgA...[truncated]",
  "signatoryName": "John Smith",
  "signatureDate": "2024/01/15"
}

---

Imagem em tabelas

Combine a inserção de imagens com estruturas de tabela para apresentações visuais organizadas.

Tabela do Catálogo de Produtos

Modelo:

Product | Image | Price
<<foreach [item in catalog]>>
<<[item.name]>> | [Text box: <<image [item.imageUrl] -keepRatio>>] | $<<[item.price]>>
<</foreach>>

---

Inserção Condicional de Imagens

Insira imagens somente quando os dados da imagem estiverem disponíveis.

Exemplo de logotipo opcional

Modelo:

<<if [logoUrl != null]>>
[Text box:] <<image [logoUrl] -keepRatio>>
<</if>>

Imagem de fallback padrão

Modelo:

<<if [productImage != null]>>
[Text box:] <<image [productImage] -fitHeight>>
<<else>>
[Text box:] <<image [defaultProductImage] -fitHeight>>
<</if>>

---

Várias imagens em um documento

Gere documentos com múltiplas imagens dinâmicas a partir de uma única fonte de dados.

Exemplo: Relatório com gráficos

Modelo:

Sales Report - <<[reportMonth]:"MMMM yyyy">>

Revenue Chart:
[Text box:] <<image [revenueChartUrl] -fitWidth>>

Expense Chart:
[Text box:] <<image [expenseChartUrl] -fitWidth>>

Growth Chart:
[Text box:] <<image [growthChartUrl] -fitWidth>>

---

Considerações sobre a qualidade da imagem

Melhores práticas para imagem URLs

1. Usar HTTPS - Seguro URLs evitar avisos de segurança
2. Permanent URLs - Garantir URLs permanecer acessível
3. Tamanho adequado - Utilize imagens com tamanho adequado para a saída.
4. Compatibilidade de formato - Formatos comuns: PNG, JPG, GIF
5. Hospedagem CDN - Utilize redes de distribuição de conteúdo confiáveis

Melhores práticas para Base64 Imagens

1. Otimizar o tamanho do arquivo - Comprimir imagens antes da codificação
2. Use a resolução apropriada. - Corresponder à resolução de saída pretendida
3. Considere o tamanho dos dados - Grande Base64 strings aumentam o tamanho da carga útil
4. Seleção de formato - PNG Por transparência, JPG para fotografias
5. Qualidade de codificação - Garantir o correto Base64 codificação

---

Configuração de caixa de texto no Word

Criando espaços reservados para imagens

1. Inserir caixa de texto:

   • Faixa de opções do Word → Inserir → Caixa de texto
   • Desenhe a caixa de texto no local desejado.
   • Dimensionar a caixa de texto para aproximar as dimensões da imagem.

2. Configurar caixa de texto:

   • Remova as bordas da caixa de texto, se desejar.
   • Defina o preenchimento da caixa de texto como "Sem preenchimento" para transparência.
   • Configure a quebra de texto conforme necessário.

3. Sintaxe para adicionar imagem:

   • Clique dentro da caixa de texto
   • Digite a sintaxe do campo de mesclagem de imagens
   • Adicione a opção de formatação apropriada.

---

Solução de problemas de inserção de imagens

Problemas comuns

Emitir: A imagem não aparece no documento gerado.
Solução: Verifique se a sintaxe da imagem está dentro de uma caixa de texto e não em um parágrafo comum.

Emitir: A imagem parece distorcida.
Solução: Usar -keepRatio para preservar a proporção

Emitir: Imagem muito grande ou muito pequena
Solução: Ajuste o tamanho da caixa de texto ou use a opção de ajuste apropriada.

Emitir: Base64 A imagem não carregou.
Solução: Verificar Base64 A codificação está completa e válida.

Emitir: URL A imagem não carrega.
Solução: Verificar URL acessibilidade, garantir HTTPS, verificar formato da imagem

Emitir: Posição da imagem incorreta
Solução: Reposicionar caixa de texto no modelo do Word

---

Técnicas Avançadas de Imagem

Dimensionamento responsivo de imagens

Para documentos que podem ser visualizados em tamanhos diferentes:

[Large text box:] <<image [headerImage] -fitSizeLim>>

Isso permite que a imagem diminua de tamanho, se necessário, mas não se expanda além dos limites da caixa de texto.

Imagem com legenda

Modelo:

[Text box:] <<image [chartUrl] -fitWidth>>

Figure <<[$index + 1]>>: <<[chartTitle]>>
Source: <<[chartSource]>>

Formatação condicional de imagens

Escolha a formatação com base nas propriedades dos dados:

<<if [imageOrientation == "landscape"]>>
[Wide text box:] <<image [imageUrl] -fitWidth>>
<<else>>
[Tall text box:] <<image [imageUrl] -fitHeight>>
<</if>>

---

Exemplo completo: Ficha de produto

Modelo:

<<[productName]:caps>>

Product Image:
[Text box 300x300:] <<image [productImageUrl] -keepRatio>>

Specifications:
• Model: <<[modelNumber]>>
• Category: <<[category]>>
• Price: $<<[price]:"F2">>

Additional Images:
<<foreach [img in additionalImages]>>
[Text box 150x150:] <<image [img.url] -keepRatio>>
<<[img.caption]>>
<</foreach>>

Company Logo:
[Text box 200x60:] <<image [companyLogoBase64] -fitHeight>>

---

:::Dica Otimização de Imagens Para obter melhores resultados, otimize as imagens antes de incluí-las na sua fonte de dados. Redimensione as imagens para as dimensões apropriadas e comprima-as para reduzir o tamanho do arquivo, mantendo a qualidade.

:::

:::aviso Requisito de Caixa de Texto As imagens DEVEM ser inseridas dentro de caixas de texto em modelos do Word. A sintaxe de imagem em parágrafos comuns não renderizará as imagens corretamente. Sempre crie um espaço reservado para caixa de texto para cada local de imagem dinâmica.

:::