La generación de documentos con combinación de correspondencia consiste en leer valores de una fuente de datos y colocar cada uno en el marcador de posición correspondiente de una plantilla. Usted mantiene dos cosas: una plantilla que contiene los campos de combinación (las variables a la espera de rellenarse) y una fuente de datos que aporta los valores más todo lo que se repite igual en cada copia. El motor de informes de PDF4me toma esos dos archivos y devuelve un documento terminado.
PDF4me acepta plantillas de Word, HTML y PDF, y la más rica de las tres es Word. Con una sintaxis breve y legible puede diseñar una sola plantilla de Word que cubra facturas, recibos, contratos, presupuestos o cualquier documento personalizado, y generar miles a partir de datos. Esta guía recorre toda la sintaxis — campos de combinación, condiciones, formato, tablas, imágenes y HTML en línea — con ejemplos listos para copiar y una plantilla de ejemplo que puede descargar y ejecutar. Cada enlace de sintaxis apunta a la página exacta de la documentación de sintaxis de plantillas de Word.
Escriba marcadores de posición como <<[FieldName]>> en un documento de Word. Añada condiciones, formato, bucles, imágenes y HTML con unos pocos tokens más. Envíe esa plantilla junto con un archivo de datos JSON (o XML) a la acción Generate Document de PDF4me y recibirá de vuelta un documento personalizado y terminado — una vez o miles.
¿Cómo se diseña una plantilla de Word?
Todo empieza con un marcador de posición. Dondequiera que quiera insertar un valor, escriba el nombre del campo entre dobles corchetes angulares y corchetes:
<<[FieldName]>>
El nombre entre corchetes debe coincidir con una propiedad de su fuente de datos. Mantenga nombres descriptivos, use una sola convención (camelCase o PascalCase) y evite caracteres especiales. Aquí tiene una plantilla mínima y los datos que la rellenan:
Dear <<[CustomerName]>>,
Thank you for your order #<<[OrderNumber]>>.
{
"CustomerName": "John Smith",
"OrderNumber": "12345"
}
El motor devuelve:
Dear John Smith,
Thank you for your order #12345.
Esa es toda la idea. Todo lo que sigue es una variación del mismo principio — condiciones, bucles y formato envuelven siempre campos de combinación normales. Los detalles completos están en la Visión general de la sintaxis.
¿Cómo se añaden condiciones a una plantilla?
La acción Generate Document puede ramificar según sus datos. Según si una condición es verdadera, inserta un bloque de contenido u otro. La estructura básica if / elseif / else se lee así:
<<if [condition1]>> Add the first block
<<elseif [condition2]>> Add the second block
<<else>> Add the fallback block
<</if>>
Las condiciones pueden comprobar un valor directamente o apoyarse en los métodos de enumeración (más sobre esto abajo), por ejemplo <<if [employees.Any(p => p.Age > 50)]>>. Encontrará el conjunto completo de operadores de comparación y lógicos en Lógica condicional.
¿Cómo se da formato a los valores de una plantilla?
A menudo un valor en bruto necesita ajustarse antes de colocarse — una fecha con un estilo concreto, un número redondeado, texto en mayúsculas. Añada una especificación de formato después del nombre del campo, separada por dos puntos y entre comillas:
<<[token]:"format">>
Las fechas usan un patrón al estilo .NET:
Invoice Date: <<[invoiceDate]:"dd.MM.yyyy">>
Due Date: <<[dueDate]:"MMMM dd, yyyy">>
Las mayúsculas y minúsculas tienen sus propios modificadores cortos — :upper, :caps (poner en mayúscula cada palabra) y :firstCap:
Customer: <<[customerName]:upper>>
Product: <<[productName]:caps>>
Los números usan formatos numéricos estándar, de modo que <<[price]:"F2">> fija un valor a dos decimales. La lista completa de patrones de fecha, texto y número está en Formato en plantillas.
¿Cómo se construyen tablas a partir de una lista?
En las tablas es donde la generación de documentos demuestra su valor — una fila de la plantilla se expande en tantas filas como tengan sus datos. Cree una tabla de Word normal, abra un bucle <<foreach>> en la primera celda, añada un campo de combinación en cada celda siguiente y cierre el bucle en la última celda:
Column 1: <<foreach [product in products]>><<[product.productName]>>
Column 2: <<[product.manufactured]:"yyyy.MM.dd">>
Column 3: <<[product.price]>><</foreach>>
Cada objeto del array products se convierte en una fila, y puede dar formato a las celdas en línea como en cualquier otro sitio. Más patrones de tabla, incluidas filas filtradas y agregadas, se tratan en Tablas en plantillas.
¿Cómo se repiten párrafos y secciones?
El mismo bucle <<foreach>> funciona también fuera de las tablas. Envuelva cualquier bloque de contenido — un párrafo, un encabezado con su cuerpo, una sección entera — y se repetirá una vez por cada elemento de la colección:
<<foreach [item in collection]>>
Content with <<[item.property]>>
<</foreach>>
Los bucles pueden anidarse (una sección por departamento, una línea por empleado dentro) y pueden filtrar u ordenar la colección sobre la marcha. Consulte Repetir párrafos y secciones para ver ejemplos anidados y condicionales.
¿Cómo se añaden imágenes a una plantilla?
PDF4me puede incorporar imágenes a un documento generado desde una URL pública o una cadena Base64. Una regla importa: el campo de imagen debe estar dentro de un Cuadro de texto de Word. Cree el cuadro de texto donde quiera la imagen y luego añada el campo.
Desde una URL pública:
<<image [imageUrl]>>
Desde una cadena codificada en Base64:
<<image [imageBase64]>>
Puede controlar el tamaño con modificadores como -keepRatio, -fitHeight, -fitWidth y -fitSize, p. ej. <<image [companyLogo] -keepRatio>>. La referencia completa de tamaños y ejemplos de imágenes por fila están en Insertar imágenes.
¿Cómo se inserta HTML en una plantilla?
Si sus datos ya contienen HTML con formato, renderícelo en el sitio con el modificador -html en lugar de escaparlo como texto plano:
<<[token] -html>>
El motor analiza el valor del campo como HTML y aplica el formato — negrita, cursiva, listas, encabezados, spans coloreados y más — dentro del documento generado. Las etiquetas y estilos admitidos se enumeran en Insertar HTML.
Trabaje con sus datos usando métodos de enumeración
Más allá de los campos simples, el motor expone métodos al estilo IEnumerable que puede invocar directamente dentro de un token — filtrar, ordenar, contar, promediar y más. Algunos ejemplos:
Total products: <<[products.Count()]>>
Average price: $<<[products.Average(p => p.price)]:"F2">>
Top items: <<foreach [p in products.OrderByDescending(x => x.price).Take(5)]>><<[p.name]>><</foreach>>
Se combinan de forma natural con condiciones y bucles. La lista completa de métodos — Where, OrderBy, GroupBy, Sum, Any, First y el resto — está en Enumeración en plantillas.
Los datos de ejemplo tienen este aspecto — un proveedor, un cliente y una lista de productos sobre la que la plantilla itera:
{
"VendorName": "PDF4me",
"VendorCity": "Zurich",
"VendorCountry": "Switzerland",
"VendorZip": "8630",
"VendorContact": "123456",
"InvoiceDate": "22-08-2022",
"CustomerName": "John Doe",
"CustomerCity": "Start City",
"CustomerCountry": "US",
"CustomerZip": "3214",
"products": [
{ "productName": "PDF Converter", "value": 2000, "expires": "01/08/2025" },
{ "productName": "PDF API", "value": 1250, "expires": "18/02/2029" },
{ "productName": "PDF Editor", "value": 1999, "expires": "12/12/2027" }
],
"comments": "This document is <b>computer generated</b> and does not require a signature."
}
Observe que comments lleva HTML — combínelo con el modificador <<[comments] -html>> y la etiqueta <b> se mostrará en negrita en la salida.
Enlaces rápidos para diseñar su plantilla
Preguntas frecuentes
¿Cómo creo campos de combinación en una plantilla de Word?
Escriba el nombre del campo entre dobles corchetes angulares y corchetes, como <<[CustomerName]>>, dondequiera que quiera insertar un valor. El nombre debe coincidir con una propiedad de su fuente de datos JSON o XML. Puede añadir campos manualmente en cualquier lugar — encabezados, párrafos, celdas de tabla o cuadros de texto.
¿Qué formatos de plantilla admite PDF4me?
Word (.docx, .doc), HTML y PDF. Los tres usan la misma sintaxis de campos de combinación, así que lo que aprenda para una plantilla de Word se traslada. Word ofrece el control más completo sobre diseño, condiciones, tablas e imágenes.
¿Puedo añadir condiciones if/else a una plantilla de Word?
Sí. Envuelva el contenido con <<if [condition]>> ... <<elseif [condition]>> ... <<else>> ... <</if>>. Una condición puede comparar un campo directamente o llamar a un método de enumeración como Any() o Count(). Así una sola plantilla maneja cada variación de sus datos en lugar de mantener un archivo por caso.
¿Cómo doy formato a fechas y números en una plantilla?
Ponga el formato tras el nombre del campo entre comillas: <<[invoiceDate]:"dd.MM.yyyy">> para una fecha, <<[price]:"F2">> para un número con dos decimales. Las mayúsculas y minúsculas tienen modificadores cortos — :upper, :caps y :firstCap.
¿Cómo genero una tabla que crece con mis datos?
Cree una tabla de Word, abra <<foreach [item in collection]>> en la primera celda, ponga un campo de combinación en cada celda restante y cierre con <</foreach>> en la última celda. Cada elemento de la colección se convierte automáticamente en una fila.
Solución de problemas
Próximos pasos
Diseñe la plantilla una vez, conéctela a sus datos y PDF4me producirá facturas, contratos e informes personalizados a demanda — desde una única llamada a la API o una automatización que procesa miles a la vez.