Saltar al contenido principal
PDF4me APIIntegracionesBase de conocimientosExtensionesProbador de APIBlog

Insertar imágenes - Guía de imágenes dinámicas

PDF4me Permite la inserción dinámica de imágenes dentro de los documentos generados, lo que le permite completar plantillas con logotipos, fotografías, gráficos, diagramas y otro contenido visual de sus fuentes de datos. Las imágenes se pueden proporcionar a través de fuentes públicas. URLs o Base64cadenas codificadas.

Requisitos de sintaxis de imágenes​

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 inserción de imágenes​

PDF4me Admite dos métodos para proporcionar datos de imagen a las plantillas:

Método 1: Imagen pública URL​

Utilice una imagen de acceso público. URLs para insertar imágenes desde fuentes web.

Sintaxis:

<<image [imageUrl]>>

Ejemplo de datos:

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

Casos de uso:

  • Logotipos de empresas alojados en servidores públicos
  • Imágenes de productos de plataformas de comercio electrónico
  • Gráficos y diagramas generados y alojados en línea.
  • Imágenes de recursos públicos

Método 2: Base64 Imágenes codificadas​

Insertar imágenes usando Base64Representación en cadena codificada del archivo de imagen.

Sintaxis:

<<image [imageBase64]>>

Ejemplo de datos:

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

Ventajas:

  • Funciona sin conexión a internet.
  • Seguro - sin dependencias externas
  • Control total sobre los datos de imagen.
  • Adecuado para documentos confidenciales

Opciones de formato de imagen​

Controla cómo se ajustan las imágenes a los cuadros de texto mediante los parámetros de formato. Estas opciones determinan el tamaño y la relación de aspecto de las imágenes.

Mantener la relación de aspecto​

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

Comportamiento:

  • Conserva el tamaño del cuadro de texto.
  • Ajusta la imagen para que se adapte a los límites del cuadro de texto.
  • Mantiene la relación de aspecto de la imagen original.
  • La imagen puede no llenar todo el cuadro de texto si las proporciones difieren.

Ideal para: Logotipos, iconos e imágenes donde debe evitarse la distorsión.

Altura adecuada​

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

Comportamiento:

  • Conserva el ancho del cuadro de texto
  • Ajusta la altura del cuadro de texto para que coincida con la relación de aspecto de la imagen.
  • La imagen llena completamente el cuadro de texto.
  • Las dimensiones del cuadro de texto cambian para adaptarse a la imagen.

Ideal para: Imágenes de altura variable en diseños flexibles

Ancho de ajuste​

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

Comportamiento:

  • Conserva la altura del cuadro de texto
  • Ajusta el ancho del cuadro de texto para que coincida con la relación de aspecto de la imagen.
  • La imagen llena completamente el cuadro de texto.
  • El ancho del cuadro de texto cambia para adaptarse a la imagen.

Ideal para: Banners horizontales, encabezados con altura fija

Talla adecuada​

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

Comportamiento:

  • Cambia las dimensiones del cuadro de texto para que coincidan con el tamaño de la imagen.
  • Utiliza las dimensiones originales de la imagen.
  • La imagen se muestra a tamaño real.
  • El cuadro de texto se redimensiona a las dimensiones exactas de la imagen.

Ideal para: Cuando se deba conservar exactamente el tamaño original de la imagen.

Talla limitada​

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

Comportamiento:

  • Ajusta el cuadro de texto al tamaño de la imagen.
  • No aumentará más allá de las dimensiones originales del cuadro de texto.
  • Se puede reducir el tamaño del cuadro de texto si la imagen es más pequeña.
  • Impide la ampliación del cuadro de texto.

Ideal para: Limitar el tamaño máximo de la imagen al tiempo que se permiten imágenes más pequeñas.

Comparación de formatos​

Opción de formatoAnchoAlturaRelación de aspectoTamaño del cuadro de texto
-keepRatioFijadoFijadoEn conservaSin alterar
-fitHeightFijadoVariableEn conservaCambios de altura
-fitWidthVariableFijadoEn conservaCambios de ancho
-fitSizeVariableVariableEn conservaAmbos cambios
-fitSizeLimVariableVariableEn conservaConstreñido

Ejemplos prácticos​

Ejemplo 1: Logotipo de la empresa​

Plantilla:

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

Datos:

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

Ejemplo 2: Imágenes de productos​

Plantilla:

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

<</foreach>>

Datos:

{
  "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"
    }
  ]
}

Ejemplo 3: Imagen de firma (Base64)​

Plantilla:

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

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

Datos:

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

Imagen en tablas​

Combine la inserción de imágenes con estructuras de tabla para crear presentaciones visuales organizadas.

Tabla del catálogo de productos​

Plantilla:

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

Inserción condicional de imágenes​

Inserta imágenes solo cuando haya datos de imagen disponibles.

Ejemplo de logotipo opcional​

Plantilla:

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

Imagen de reserva predeterminada​

Plantilla:

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

Varias imágenes en el documento​

Genera documentos con múltiples imágenes dinámicas a partir de una única fuente de datos.

Ejemplo: Informe con gráficos​

Plantilla:

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>>

Consideraciones sobre la calidad de la imagen​

Mejores prácticas para imágenes URLs​

  1. Usar HTTPS - Seguro URLs evitar advertencias de seguridad
  2. Permanente URLs - Asegurar URLs permanecer accesible
  3. Tamaño adecuado - Utilice imágenes con el tamaño adecuado para la salida.
  4. Compatibilidad de formato - Formatos comunes: PNG, JPG, GIF
  5. Alojamiento CDN - Utilice redes de distribución de contenido fiables

Mejores prácticas para Base64 Imágenes​

  1. Optimizar el tamaño del archivo - Comprimir las imágenes antes de codificarlas.
  2. Utilice la resolución adecuada. - Ajustar a la resolución de salida prevista
  3. Considere el tamaño de los datos. - Grande Base64 Las cadenas aumentan el tamaño de la carga útil.
  4. Selección de formato - PNG para la transparencia, JPG para fotografías
  5. Calidad de codificación - Asegurar que sea adecuado Base64 codificación

Configuración de cuadros de texto en Word​

Creación de marcadores de posición de imagen​

  1. Insertar cuadro de texto:

    • Cinta de opciones de Word → Insertar → Cuadro de texto
    • Dibujar un cuadro de texto en la ubicación deseada.
    • Ajustar el tamaño del cuadro de texto a las dimensiones aproximadas de la imagen.

  2. Configurar cuadro de texto:

    • Si lo desea, puede eliminar los bordes del cuadro de texto.
    • Para mayor transparencia, configure el relleno del cuadro de texto en "Sin relleno".
    • Configure el ajuste de texto según sea necesario.

  3. Agregar sintaxis de imagen:

    • Haz clic dentro del cuadro de texto
    • Sintaxis del campo de fusión de imágenes
    • Agregar opción de formato apropiada

Solución de problemas de inserción de imágenes​

Problemas comunes​

Asunto: La imagen no aparece en el documento generado.
Solución: Verifica que la sintaxis de la imagen esté dentro de un cuadro de texto, no en un párrafo normal.

Asunto: La imagen aparece distorsionada
Solución: Usar -keepRatio para preservar la relación de aspecto

Asunto: Imagen demasiado grande o demasiado pequeña
Solución: Ajuste el tamaño del cuadro de texto o utilice la opción de ajuste adecuada.

Asunto: Base64 La imagen no se carga
Solución: Verificar Base64 La codificación es completa y válida.

Asunto: URL La imagen no se carga
Solución: Controlar URL accesibilidad, garantizar HTTPSverificar formato de imagen

Asunto: Posición de la imagen incorrecta
Solución: Reposicionar cuadro de texto en plantilla de Word

Técnicas avanzadas de imagen​

Tamaño de imagen adaptable​

Para documentos que pueden visualizarse en diferentes tamaños:

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

Esto permite que la imagen se reduzca si es necesario, pero no se expandirá más allá de los límites del cuadro de texto.

Imagen con pie de foto​

Plantilla:

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

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

Formato de imagen condicional​

Seleccione el formato en función de las propiedades de los datos:

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

Ejemplo completo: Ficha de producto​

Plantilla:

<<[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>>

:::Consejo: Optimización de imágenes Para obtener mejores resultados, optimice las imágenes antes de incluirlas en su fuente de datos. Cambie el tamaño de las imágenes a las dimensiones adecuadas y comprímalas para reducir el tamaño del archivo sin comprometer la calidad.

:::

:::advertencia Requisito del cuadro de texto Las imágenes DEBEN insertarse dentro de cuadros de texto en las plantillas de Word. La sintaxis de imagen en párrafos normales no mostrará las imágenes correctamente. Cree siempre un cuadro de texto de marcador de posición para cada ubicación de imagen dinámica. :::