Excel Remplir la syntaxe du modèle
PDF4me Excel Peupler utilise le Marqueurs intelligents Aspose syntaxe pour fusionner JSON des données dans un système conçu Excel classeur. Vous saisissez des champs de marqueurs comme &=Items.ItemName directement dans les cellules d'une cellule normale .xlsx transmettez ensuite le classeur plus un fichier, puis le classeur. JSON Charge utile pour le moteur. Cette page constitue la référence canonique pour la syntaxe : format des marqueurs, paramètres de modification, comportement multi-feuilles, gestion des formules, mise en forme régionale et modèle d’exemple téléchargeable. JSON fichiers que vous pouvez exécuter de bout en bout.
Référence externe : le Excel Le moteur de peuplement implémente le Fonctionnalité des marqueurs intelligents Aspose.CellsLa documentation d'Aspose est la source grammaticale de référence ; cette page en donne un résumé. PDF4me utilisateurs et ajoute le JSON-conventions de charge utile spécifiques au PDF4me API.
Exemples de fichiers
Téléchargez les modèles d'exemple et les modèles correspondants JSON Les fichiers de données utilisés sur cette page. Déposez-les directement dans le PDF4me Excel Peupler REST point final, Power Automate action, ou l'une des plateformes d'intégration.
&=Articles.* marqueurs utilisés dans l'échantillon de la feuille 1.RootData.Items[] avec description, quantité, prix unitaire, remise et prix.Articles[] avec des valeurs de chaîne pour exercer le Strict JSON Paramétrage des chaînes de caractères.Produits[]) pour la troisième feuille.Employés[]) pour remplir la liste du personnel.Sélectionnez le format
Le marqueur intelligent de base est une valeur de cellule unique qui commence par &= (esperluette = égal) et est suivi du nom de la source de données, d'un point et du nom du champ.
&=DataSource.FieldName
Placez le marqueur dans la cellule où le premier enregistrement doit apparaître. Lorsque vous fournissez un JSON tableau sous DataSourceLe moteur écrit le premier enregistrement dans cette cellule et insère de nouvelles lignes en dessous pour chaque enregistrement supplémentaire. Les cellules adjacentes contenant des marqueurs sur la même ligne sont développées simultanément afin que chaque enregistrement reste aligné.
Exemple minimal
Modèle (Feuille 1 de template.xlsx) est exactement ceci :
| UN | B | C |
|---|---|---|
| Nom de l'article | Quantité | Prix unitaire |
&=Items.ItemName | &=Items.Qty | &=Items.UnitPrice |
JSON charge utile (sheet23-data.json, l'échantillon correspondant) :
{
"Items": [
{ "ItemName": "A123", "Qty": "55", "UnitPrice": "3.05" },
{ "ItemName": "B456", "Qty": "20", "UnitPrice": "5.50" },
{ "ItemName": "C789", "Qty": "10", "UnitPrice": "12.99" }
]
}
Résultat généré : Le moteur inscrit le premier enregistrement dans la ligne 2, insère deux lignes supplémentaires en dessous et aligne les colonnes en fonction de la position du marqueur adjacent. La ligne d'en-tête de la ligne 1 reste inchangée.
Paramètres de modification
Les marqueurs intelligents acceptent une liste de paramètres séparés par des virgules, placée entre parenthèses immédiatement après le nom du champ, afin de contrôler la mise en page et le comportement.
&=DataSource.FieldName(parameter1, parameter2, ...)
Les paramètres les plus utiles :
| Paramètre | Ce que cela fait | Exemple |
|---|---|---|
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) |
Les paramètres peuvent être combinés : &=Items.ItemName(dynamic, copystyle) crée une plage dynamique ET copie le style de ligne à chaque enregistrement inséré.
Sources de données imbriquées
Quand le JSON Enveloppez votre tableau sous un objet parent, accédez-y avec un chemin pointillé. Facture feuille de template.xlsx est l'exemple canonique. Ses marqueurs dans la ligne 2 se lisent jusqu'à RootData dans 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
La charge utile correspondante est 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 }
]
}
}
Notez l'apostrophe incluse dans "Mouse's"Les marqueurs intelligents préservent par défaut les primitives de chaîne entre guillemets (le StrictJsonStrings les paramètres par défaut vrai). Réglez-le sur FAUX lorsque vous souhaitez que le moteur convertisse les chaînes numériques ou de dates entre guillemets en caractères typés Excel valeurs des cellules lors de la fusion.
Excel Tableaux et références structurées
La facture de template.xlsx démontre un modèle Smart Markers puissant : la rangée de marqueurs se trouve à l’intérieur d’un Excel Tableau (nommé SimpleInvoiceLes cellules de formule font référence aux colonnes du tableau par une référence structurée au lieu des adresses A1, et la plage du tableau s'étend automatiquement à mesure que les marqueurs intelligents insèrent de nouvelles lignes.
Exemple de cellule de formule extraite de la feuille de facturation :
=IFERROR(IF(SimpleInvoice[[#This Row],[Unit price]]="","",
(SimpleInvoice[[#This Row],[Qty]] * SimpleInvoice[[#This Row],[Unit price]])
- SimpleInvoice[[#This Row],[Discount]]
), "")
Les cellules d'agrégation situées en dehors du tableau font référence à des colonnes entières :
G7: =SUM(SimpleInvoice[Price]) // Invoice subtotal
G9: =IFERROR(G7*G8,"") // Sales tax (G8 is rate)
G11: =SUM(G2:G4)-G10 // Total (G10 is deposit)
Pourquoi c'est important : lorsque le moteur étend la ligne de marqueurs de 1 enregistrement à N enregistrements, SimpleInvoice La plage de la table s'étend automatiquement. SUM(SimpleInvoice[Price]) Le calcul de la somme de la colonne de droite se poursuit, et les formules par ligne se propagent vers le bas sans que vous ayez à les saisir pour chaque enregistrement.
Modèles multi-feuilles
Excel La fonction Populate permet de remplir toutes les feuilles d'un classeur en un seul appel, ou de limiter la fusion à un sous-ensemble. Index des feuilles de travail paramètre (indexé à partir de 1, séparé par des virgules). template-3-sheets.xlsx L'échantillon contient trois feuilles, dans cet ordre précis:
| Position | Nom de la feuille | Marqueurs utilisés | Échantillon 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 |
Pour remplir les trois feuilles en un seul appel, fusionnez les trois JSON les données utiles sont regroupées dans un seul objet dont les clés de niveau supérieur correspondent aux noms des sources de données des marqueurs :
{
"Items": [ { "ItemName": "A123", "Qty": "55", "UnitPrice": "3.05" }, ... ],
"Employees": [ { "EmployeeName": "John Doe", "Department": "IT", "Salary": "5000" }, ... ],
"Products": [ { "ProductName": "Laptop", "Category": "Electronics", "Stock": "15" }, ... ]
}
Pour remplir uniquement la feuille des employés, passez Worksheet Indexes = 2 dans l'appel d'action. Les positions 1 et 3 restent inchangées. Pour renseigner uniquement les articles et les produits, transmettez : 1,3.
Gestion des formules
Les marqueurs intelligents coopèrent avec les systèmes natifs Excel Formules. Deux règles importantes :
- Les formules statiques résistent à l'expansion. Une formule comme
=B2*C2dans une ligne qui est étendue, des copies sont créées pour chaque ligne remplie, les références de cellules étant ajustées de manière classique. Excel Vous n'avez pas besoin de marqueur pour la cellule contenant la formule. - Le recalcul est activé par défaut. Le
Calculate FormulasCe paramètre détermine si le classeur est recalculé après le remplissage. Laissez-le tel quel. vrai pour recevoir un classeur dont les totaux et les agrégats sont exacts dès son ouverture. Configurez-le pour FAUX lorsque vous prévoyez de recalculer ultérieurement dans votre propre processus et que vous souhaitez éviter les coûts.
Formatage de la culture et des paramètres régionaux
Le Culture & Language Settings Ce paramètre accepte un nom de culture standard (en-US, fr-FR, de-DE, ja-JP, etc.) et contrôle la manière dont les nombres, les dates et les devises sont formatés lorsque le moteur écrit JSON valeurs dans Excel cellules. Configurez-le pour qu'il corresponde aux paramètres régionaux attendus par vos destinataires. La valeur par défaut est en-US.
Les éléments connexes Préfixe de citation au style Le décor porte le Excel L'indicateur quote-prefix est appliqué aux valeurs stylisées lorsqu'il est présent, afin que les valeurs qui ressemblent à des nombres mais qui devraient s'afficher comme du texte (numéros de compte, codes postaux avec des zéros non significatifs) restent du texte.
Modèles courants
Lignes de facture avec lignes de totaux
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)
Lorsque le moteur développe la ligne 5 pour chaque élément, la plage SUM de la ligne 6 s'étend avec elle car elle se trouve en dessous des lignes de marqueurs.
Tableau comparatif côte à côte (horizontal)
A1: Metric B1: &=Months.Name(horizontal)
A2: Revenue B2: &=Months.Revenue(horizontal)
A3: Expenses B3: &=Months.Expenses(horizontal)
Chaque mois devient une nouvelle colonne à droite de B au lieu d'une nouvelle ligne en dessous.
Étiquettes pré-imprimées (sans ajout)
Lorsque vous avez 24 cellules d'étiquettes préformatées sur une feuille et que vous souhaitez que les données s'y insèrent sans ajouter de lignes :
&=Labels.Name(noadd)
&=Labels.Address(noadd)
Le moteur remplit les 24 lignes existantes dans l'ordre et tronque silencieusement tous les enregistrements qui dépassent ce qui tient.
Liste de contrôle rapide
&=&= dans la cellule A1 (ou toute autre cellule). Toute autre valeur est considérée comme une valeur cellulaire normale.Nom de l'article ne correspond pas au modèle nom_de_l'article dans le JSON.