La generazione di documenti tramite stampa unione consiste nel leggere valori da un'origine dati e inserire ciascuno nel segnaposto corrispondente di un modello. Conservi due elementi: un modello che contiene i campi di unione (le variabili in attesa di essere riempite) e un'origine dati che fornisce i valori più tutto ciò che resta uguale su ogni copia. Il motore di reporting di PDF4me prende questi due file e restituisce un documento finito.
PDF4me accetta modelli Word, HTML e PDF, e il più ricco dei tre è Word. Con una sintassi breve e leggibile puoi progettare un unico modello Word che copre fatture, ricevute, contratti, preventivi o qualsiasi documento personalizzato, e generarne migliaia dai dati. Questa guida percorre tutta la sintassi — campi di unione, condizioni, formattazione, tabelle, immagini e HTML in linea — con esempi pronti da copiare e un modello di esempio che puoi scaricare ed eseguire. Ogni collegamento di sintassi punta alla pagina esatta della documentazione sulla sintassi dei modelli Word.
Scrivi i segnaposto come <<[FieldName]>> in un documento Word. Aggiungi condizioni, formattazione, cicli, immagini e HTML con una manciata di token in più. Invia quel modello insieme a un file di dati JSON (o XML) all'azione Generate Document di PDF4me e ottieni un documento personalizzato e finito — una volta o a migliaia.
Come si progetta un modello Word?
Tutto inizia con un segnaposto. Ovunque tu voglia inserire un valore, digita il nome del campo racchiuso tra doppie parentesi angolari e parentesi quadre:
<<[FieldName]>>
Il nome tra parentesi deve corrispondere a una proprietà della tua origine dati. Mantieni nomi descrittivi, usa un'unica convenzione (camelCase o PascalCase) ed evita caratteri speciali. Ecco un modello minimo e i dati che lo riempiono:
Dear <<[CustomerName]>>,
Thank you for your order #<<[OrderNumber]>>.
{
"CustomerName": "John Smith",
"OrderNumber": "12345"
}
Il motore restituisce:
Dear John Smith,
Thank you for your order #12345.
Questa è tutta l'idea. Tutto ciò che segue è una variazione dello stesso principio — condizioni, cicli e formattazione avvolgono sempre normali campi di unione. I dettagli completi si trovano nella Panoramica della sintassi.
Come si aggiungono condizioni a un modello?
L'azione Generate Document può ramificarsi in base ai tuoi dati. A seconda che una condizione sia vera, inserisce un blocco di contenuto o un altro. La struttura di base if / elseif / else si legge così:
<<if [condition1]>> Add the first block
<<elseif [condition2]>> Add the second block
<<else>> Add the fallback block
<</if>>
Le condizioni possono verificare un valore direttamente o appoggiarsi ai metodi di enumerazione (più avanti), ad esempio <<if [employees.Any(p => p.Age > 50)]>>. Trovi l'insieme completo degli operatori di confronto e logici in Logica condizionale.
Come si formattano i valori in un modello?
Spesso un valore grezzo va preparato prima di essere inserito — una data in uno stile preciso, un numero arrotondato, testo in maiuscolo. Aggiungi una specifica di formato dopo il nome del campo, separata da due punti e tra virgolette:
<<[token]:"format">>
Le date usano un pattern in stile .NET:
Invoice Date: <<[invoiceDate]:"dd.MM.yyyy">>
Due Date: <<[dueDate]:"MMMM dd, yyyy">>
Le maiuscole/minuscole hanno le proprie opzioni brevi — :upper, :caps (mettere in maiuscolo ogni parola) e :firstCap:
Customer: <<[customerName]:upper>>
Product: <<[productName]:caps>>
I numeri usano formati numerici standard, così <<[price]:"F2">> fissa un valore a due decimali. L'elenco completo dei pattern di data, testo e numero è in Formattazione nei modelli.
Come si costruiscono tabelle da un elenco?
È nelle tabelle che la generazione di documenti dà il meglio — una riga del modello si espande in tante righe quante ne hanno i dati. Crea una normale tabella Word, apri un ciclo <<foreach>> nella prima cella, aggiungi un campo di unione in ogni cella successiva e chiudi il ciclo nell'ultima cella:
Column 1: <<foreach [product in products]>><<[product.productName]>>
Column 2: <<[product.manufactured]:"yyyy.MM.dd">>
Column 3: <<[product.price]>><</foreach>>
Ogni oggetto dell'array products diventa una riga e puoi formattare le celle in linea come ovunque. Altri pattern di tabella, incluse righe filtrate e aggregate, sono trattati in Tabelle nei modelli.
Come si ripetono paragrafi e sezioni?
Lo stesso ciclo <<foreach>> funziona anche fuori dalle tabelle. Avvolgi un qualsiasi blocco di contenuto — un paragrafo, un titolo con il suo corpo, un'intera sezione — e si ripete una volta per ogni elemento della raccolta:
<<foreach [item in collection]>>
Content with <<[item.property]>>
<</foreach>>
I cicli possono essere annidati (una sezione per reparto, una riga per dipendente al suo interno) e possono filtrare o ordinare la raccolta strada facendo. Vedi Ripetere paragrafi e sezioni per esempi annidati e condizionali.
Come si aggiungono immagini a un modello?
PDF4me può inserire immagini in un documento generato da un URL pubblico o da una stringa Base64. Una regola conta: il campo immagine deve trovarsi dentro una Casella di testo di Word. Crea la casella di testo dove vuoi l'immagine, poi aggiungi il campo.
Da un URL pubblico:
<<image [imageUrl]>>
Da una stringa codificata in Base64:
<<image [imageBase64]>>
Controlli le dimensioni con opzioni come -keepRatio, -fitHeight, -fitWidth e -fitSize, ad es. <<image [companyLogo] -keepRatio>>. Il riferimento completo alle dimensioni e gli esempi di immagini per riga si trovano in Inserire immagini.
Come si inserisce HTML in un modello?
Se i tuoi dati contengono già HTML formattato, renderizzalo sul posto con l'opzione -html invece di sfuggirlo come testo semplice:
<<[token] -html>>
Il motore analizza il valore del campo come HTML e applica la formattazione — grassetto, corsivo, elenchi, titoli, span colorati e altro — all'interno del documento generato. I tag e gli stili supportati sono elencati in Inserire HTML.
Lavora sui tuoi dati con i metodi di enumerazione
Oltre ai campi semplici, il motore espone metodi in stile IEnumerable che puoi richiamare direttamente in un token — filtrare, ordinare, contare, calcolare la media e altro. Alcuni esempi:
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>>
Si combinano naturalmente con condizioni e cicli. L'elenco completo dei metodi — Where, OrderBy, GroupBy, Sum, Any, First e il resto — è in Enumerazione nei modelli.
I dati di esempio hanno questo aspetto — un fornitore, un cliente e un elenco di prodotti su cui il modello 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."
}
Nota che comments contiene HTML — abbinalo all'opzione <<[comments] -html>> e il tag <b> verrà reso in grassetto nell'output.
Link rapidi per progettare il tuo modello
Domande frequenti
Come creo i campi di unione in un modello Word?
Digita il nome del campo tra doppie parentesi angolari e parentesi quadre, come <<[CustomerName]>>, ovunque tu voglia inserire un valore. Il nome deve corrispondere a una proprietà della tua origine dati JSON o XML. Puoi aggiungere campi manualmente ovunque — titoli, paragrafi, celle di tabella o caselle di testo.
Quali formati di modello supporta PDF4me?
Word (.docx, .doc), HTML e PDF. Tutti e tre usano la stessa sintassi dei campi di unione, quindi ciò che impari per un modello Word si trasferisce. Word offre il controllo più completo su layout, condizioni, tabelle e immagini.
Posso aggiungere condizioni if/else a un modello Word?
Sì. Avvolgi il contenuto con <<if [condition]>> ... <<elseif [condition]>> ... <<else>> ... <</if>>. Una condizione può confrontare un campo direttamente o richiamare un metodo di enumerazione come Any() o Count(). Così un unico modello gestisce ogni variante dei tuoi dati invece di mantenere un file per caso.
Come formatto date e numeri in un modello?
Metti il formato dopo il nome del campo, tra virgolette: <<[invoiceDate]:"dd.MM.yyyy">> per una data, <<[price]:"F2">> per un numero con due decimali. Le maiuscole/minuscole hanno opzioni brevi — :upper, :caps e :firstCap.
Come genero una tabella che cresce con i miei dati?
Crea una tabella Word, apri <<foreach [item in collection]>> nella prima cella, metti un campo di unione in ogni cella restante e chiudi con <</foreach>> nell'ultima cella. Ogni elemento della raccolta diventa automaticamente una riga.
Risoluzione dei problemi
Passaggi successivi
Progetta il modello una volta, collegalo ai tuoi dati e PDF4me sforna fatture, contratti e report personalizzati su richiesta — da una singola chiamata API o da un'automazione che ne elabora migliaia alla volta.