Excel Sintassi per popolare il modello
PDF4me Excel Popola usa il Marcatori intelligenti Aspose sintassi per unire JSON dati in un formato progettato Excel cartella di lavoro. Digiti campi marcatore come &=Items.ItemName direttamente nelle cellule di un normale .xlsx file, quindi passa la cartella di lavoro più un JSON payload per il motore. Questa pagina è il riferimento canonico per la sintassi: formato del marcatore, parametri del modificatore, comportamento multi-foglio, gestione delle formule, formattazione della cultura e modello di esempio scaricabile + JSON file che è possibile eseguire dall'inizio alla fine.
Riferimento esterno: IL Excel Il motore di popolamento implementa il Funzionalità Smart Markers di Aspose.Cells. La documentazione di Aspose è la fonte grammaticale autorevole; questa pagina la distilla per PDF4me utenti e aggiunge il JSON-convenzioni di payload specifiche per il PDF4me API.
File di esempio
Scarica i modelli di esempio e i relativi abbinamenti JSON file di dati utilizzati in questa pagina. Trascinali direttamente nel PDF4me Excel Popola REST punto finale, Power Automate azione o una qualsiasi delle piattaforme di integrazione.
&=Elementi.* marcatori utilizzati nel campione del Foglio1.RootData.Items[] con descrizione, quantità, prezzo unitario, sconto e prezzo.Elementi[] con valori stringa per esercitare lo Stretto JSON Impostazione delle stringhe.Prodotti[]) per il terzo foglio.Dipendenti[]) per compilare il foglio con l'elenco del personale.Seleziona il formato
Il marcatore intelligente di base è un singolo valore di cella che inizia con &= (e commerciale-uguale) ed è seguito dal nome dell'origine dati, un punto e il nome del campo.
&=DataSource.FieldName
Posiziona il marcatore nella cella in cui dovrebbe trovarsi il primo record. Quando fornisci un JSON matrice sotto DataSourceIl motore scrive il primo record in quella cella e inserisce nuove righe sottostanti per ogni record aggiuntivo. Le celle adiacenti che contengono marcatori sulla stessa riga vengono espanse insieme in modo che ogni record rimanga allineato.
Esempio minimo
Modello (Foglio1 di template.xlsx) è esattamente questo:
| UN | B | C |
|---|---|---|
| Nome dell'articolo | Quantità | Prezzo unitario |
&=Items.ItemName | &=Items.Qty | &=Items.UnitPrice |
JSON carico utile sheet23-data.json, il campione corrispondente):
{
"Items": [
{ "ItemName": "A123", "Qty": "55", "UnitPrice": "3.05" },
{ "ItemName": "B456", "Qty": "20", "UnitPrice": "5.50" },
{ "ItemName": "C789", "Qty": "10", "UnitPrice": "12.99" }
]
}
Output popolato: Il motore scrive il primo record nella riga 2, inserisce due righe aggiuntive sottostanti e allinea le colonne in base alla posizione del marcatore adiacente. La riga di intestazione nella riga 1 rimane al suo posto.
Parametri modificatori
Gli Smart Marker accettano un elenco di parametri separati da virgole tra parentesi immediatamente dopo il nome del campo per controllare il layout e il comportamento.
&=DataSource.FieldName(parameter1, parameter2, ...)
I parametri più utili:
| Parametro | Cosa fa | Esempio |
|---|---|---|
dynamic | Creates a dynamic range (and named formulas) around the populated cells. Use for output that feeds PivotTables, charts, or named-range formulas downstream. | &=Items.ItemName(dynamic) |
horizontal | Lays the records out left-to-right across columns instead of top-to-bottom down rows. Use for compact summaries or single-row dashboards. | &=Items.ItemName(horizontal) |
noadd | Replaces values in place without adding any new rows. Use when the template already contains enough pre-formatted rows and you do not want the layout to grow. | &=Items.ItemName(noadd) |
skip:N | Inserts N blank rows between each record. Useful for spaced-out reports such as packing slips or labels. | &=Items.ItemName(skip:1) |
copystyle | Copies the formatting of the marker cell down onto every populated row. Without it the first row keeps its style and the inserted rows pick up the default. | &=Items.ItemName(copystyle) |
shift | Shifts cells (right or down) when inserting populated rows so existing content below is preserved instead of overwritten. | &=Items.ItemName(shift) |
repeat | Repeats a header or section for each grouping. Used together with subtotal-style templates. | &=Items.ItemName(repeat) |
I parametri possono essere combinati: &=Items.ItemName(dynamic, copystyle) crea un intervallo dinamico E copia lo stile di riga in ogni record inserito.
Fonti di dati nidificate
Quando il JSON racchiude il tuo array sotto un oggetto padre, accedendovi con un percorso tratteggiato. Fattura foglio di template.xlsx è l'esempio canonico. I suoi marcatori nella riga 2 leggono attraverso RootData in Items:
B2: &=RootData.Items.ItemName
C2: &=RootData.Items.Description
D2: &=RootData.Items.Qty
E2: &=RootData.Items.UnitPrice
F2: &=RootData.Items.Discount
G2: &=RootData.Items.Price
Il payload corrispondente è sheet1-data.json:
{
"RootData": {
"Items": [
{ "ItemName": "Laptop", "Description": "Dell Inspiron 15", "Qty": 2, "UnitPrice": 750, "Discount": 50, "Price": 1450 },
{ "ItemName": "Mouse's", "Description": "Wireless Mouse", "Qty": 3, "UnitPrice": 25, "Discount": 0, "Price": 75 },
{ "ItemName": "Keyboard", "Description": "Mechanical Keyboard", "Qty": 1, "UnitPrice": 120, "Discount": 10, "Price": 110 }
]
}
}
Nota l'apostrofo incorporato in "Mouse's". Gli Smart Marker preservano per impostazione predefinita le primitive di stringa tra virgolette (il StrictJsonStrings impostazione predefinita su VERO). Impostalo su falso quando si desidera che il motore converta le stringhe numeriche o di data racchiuse tra virgolette in stringhe digitate Excel valori delle celle durante l'unione.
Excel Tabelle e riferimenti strutturati
Il foglio delle fatture di template.xlsx dimostra un potente modello Smart Markers: la riga del marcatore si trova all'interno di un Excel Tavolo (denominato) SimpleInvoiceLe celle formula fanno riferimento alle colonne della tabella tramite riferimenti strutturati anziché indirizzi A1 e l'intervallo della tabella si espande automaticamente man mano che i marcatori intelligenti inseriscono nuove righe.
Una cella con una formula rappresentativa tratta dal foglio Fattura:
=IFERROR(IF(SimpleInvoice[[#This Row],[Unit price]]="","",
(SimpleInvoice[[#This Row],[Qty]] * SimpleInvoice[[#This Row],[Unit price]])
- SimpleInvoice[[#This Row],[Discount]]
), "")
Le celle di aggregazione al di fuori della tabella fanno riferimento a intere colonne:
G7: =SUM(SimpleInvoice[Price]) // Invoice subtotal
G9: =IFERROR(G7*G8,"") // Sales tax (G8 is rate)
G11: =SUM(G2:G4)-G10 // Total (G10 is deposit)
Perché questo è importante: quando il motore espande la riga del marcatore da 1 record a N record, il SimpleInvoice L'intervallo della tabella si espande automaticamente, SUM(SimpleInvoice[Price]) Il calcolo continua a sommare la colonna di destra e le formule per riga si propagano automaticamente verso il basso, senza che sia necessario inserirle per ogni singolo record.
Modelli multi-foglio
Excel Populate può popolare ogni foglio in una cartella di lavoro in una singola chiamata oppure limitare l'unione a un sottoinsieme utilizzando Indici dei fogli di lavoro parametro (basato su 1, separato da virgole). Il template-3-sheets.xlsx il campione contiene tre fogli, in quest'ordine preciso:
| Posizione | Nome del foglio | Pennarelli utilizzati | Campione JSON |
|---|---|---|---|
| 1 | Items | &=Items.ItemName, &=Items.Qty, &=Items.UnitPrice | items-data.json |
| 2 | Employees | &=Employees.EmployeeName, &=Employees.Department, &=Employees.Salary | employees-data.json |
| 3 | Products | &=Products.ProductName, &=Products.Category, &=Products.Stock | products-data.json |
Per popolare tutti e tre i fogli in una sola chiamata, unisci i tre JSON raggruppare i payload in un singolo oggetto le cui chiavi di livello superiore corrispondono ai nomi delle origini dati dei marcatori:
{
"Items": [ { "ItemName": "A123", "Qty": "55", "UnitPrice": "3.05" }, ... ],
"Employees": [ { "EmployeeName": "John Doe", "Department": "IT", "Salary": "5000" }, ... ],
"Products": [ { "ProductName": "Laptop", "Category": "Electronics", "Stock": "15" }, ... ]
}
Per popolare solo il foglio Dipendenti, passare Worksheet Indexes = 2 nella chiamata di azione. Le posizioni 1 e 3 rimangono invariate. Per popolare solo Articoli + Prodotti, passare 1,3.
Gestione della formula
I marcatori intelligenti collaborano con i marcatori nativi Excel formule. Due regole importanti:
- Le formule statiche resistono all'espansione. Una formula come
=B2*C2in una riga che ottiene copie espanse fino a ogni riga popolata con i riferimenti di cella regolati nel solito Excel In questo modo non è necessario un indicatore per la cella della formula. - Il ricalcolo è attivo per impostazione predefinita. IL
Calculate FormulasL'impostazione controlla se la cartella di lavoro viene ricalcolata dopo il popolamento. Lasciala così. VERO per ricevere una cartella di lavoro i cui totali e aggregati siano accurati nel momento stesso in cui la apri. Impostalo su falso quando si prevede di ricalcolare in seguito nella propria pipeline e si desidera evitare il costo.
Formattazione della cultura e della lingua
IL Culture & Language Settings il parametro accetta un nome cultura standard (en-US, fr-FR, de-DE, ja-JP, ecc.) e controlla come vengono formattati numeri, date e valute quando il motore scrive JSON valori in Excel celle. Impostalo in modo che corrisponda alle impostazioni locali previste dai destinatari. L'impostazione predefinita è en-US.
Il correlato Prefisso di citazione per lo stile l'impostazione porta il Excel Il flag quote-prefix viene applicato ai valori stilizzati quando presente, in modo che i valori che sembrano numeri ma dovrebbero essere visualizzati come testo (numeri di conto, codici postali con zeri iniziali) rimangano testo.
Modelli comuni
Voci della fattura con riga dei totali
A1: Invoice number B1: &=Invoice.Number
A2: Date B2: &=Invoice.Date
A4: Item B4: Qty C4: Unit price D4: Total
A5: &=Items.ItemName B5: &=Items.Qty C5: &=Items.UnitPrice D5: =B5*C5
A6: Grand total D6: =SUM(D5:D5)
Quando il motore espande la riga 5 per ogni elemento, l'intervallo SOMMA nella riga 6 si espande di conseguenza perché si trova al di sotto delle righe dei marcatori.
Tabella comparativa affiancata (orizzontale)
A1: Metric B1: &=Months.Name(horizontal)
A2: Revenue B2: &=Months.Revenue(horizontal)
A3: Expenses B3: &=Months.Expenses(horizontal)
Ogni mese diventa una nuova colonna a destra di B anziché una nuova riga sottostante.
Etichette prestampate (noadd)
Quando si hanno 24 celle di etichetta preformattate su un foglio e si desidera che i dati fluiscano in esse senza aggiungere righe:
&=Labels.Name(noadd)
&=Labels.Address(noadd)
Il motore riempie le 24 righe esistenti in ordine e tronca silenziosamente i record che superano lo spazio disponibile.
Lista di controllo rapida
&=&= nella cella A1 (o in qualsiasi altra cella). Qualsiasi altro valore viene trattato come un normale valore di cella.Nome articolo nel modello NON corrisponde itemMaking nel JSON.