Excel Sintaxis de plantilla de relleno
PDF4me Excel Poblar utiliza el Marcadores inteligentes Aspose sintaxis para fusionar JSON datos en un diseño Excel Libro de trabajo. Escribes campos de marcador como &=Items.ItemName directamente en las células de un organismo normal .xlsx archivo, luego pase el libro de trabajo más un JSON carga útil al motor. Esta página es la referencia canónica para la sintaxis: formato de marcador, parámetros modificadores, comportamiento de varias hojas, manejo de fórmulas, formato cultural y plantilla de ejemplo descargable + JSON archivos que puede ejecutar de principio a fin.
Referencia externa: el Excel El motor de población implementa el Función de marcadores inteligentes de Aspose.Cells. La documentación de Aspose es la fuente gramatical autorizada; esta página la resume para PDF4me usuarios y agrega el JSON-convenciones de carga útil específicas para el PDF4me API.
Archivos de ejemplo
Descargue las plantillas de muestra y las plantillas coincidentes. JSON archivos de datos utilizados en esta página. Colóquelos directamente en el PDF4me Excel Poblar REST punto final, Power Automate acción, o cualquiera de las plataformas de integración.
&=Elementos.* marcadores utilizados en la muestra de la Hoja1.RootData.Items[] con descripción, cantidad, precio unitario, descuento y precio.Elementos[] con valores de cadena para ejercitar el Strict JSON Configuración de cadenas.Productos[]) para la tercera hoja.Empleados[]) para completar la hoja de la lista de personal.Seleccione el formato
El marcador inteligente básico es un valor de celda única que comienza con &= (ampersand-igual) y va seguido del nombre de la fuente de datos, un punto y el nombre del campo.
&=DataSource.FieldName
Coloque el marcador en la celda donde debería ir el primer registro. Cuando proporcione un JSON matriz bajo DataSourceEl motor escribe el primer registro en esa celda e inserta nuevas filas debajo por cada registro adicional. Las celdas adyacentes que contienen marcadores en la misma fila se expanden juntas para que cada registro permanezca alineado.
Ejemplo mínimo
Plantilla (Hoja1 de template.xlsx) es exactamente esto:
| A | B | do |
|---|---|---|
| Nombre del artículo | Cantidad | Precio unitario |
&=Items.ItemName | &=Items.Qty | &=Items.UnitPrice |
JSON carga útil (sheet23-data.json, la muestra correspondiente):
{
"Items": [
{ "ItemName": "A123", "Qty": "55", "UnitPrice": "3.05" },
{ "ItemName": "B456", "Qty": "20", "UnitPrice": "5.50" },
{ "ItemName": "C789", "Qty": "10", "UnitPrice": "12.99" }
]
}
Salida poblada: El motor escribe el primer registro en la fila 2, inserta dos filas adicionales debajo y alinea las columnas según la posición del marcador adyacente. La fila de encabezado en la fila 1 permanece en su lugar.
Parámetros modificadores
Los marcadores inteligentes aceptan una lista de parámetros separados por comas entre paréntesis inmediatamente después del nombre del campo para controlar el diseño y el comportamiento.
&=DataSource.FieldName(parameter1, parameter2, ...)
Los parámetros más útiles:
| Parámetro | Lo que hace | Ejemplo |
|---|---|---|
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) |
Los parámetros se pueden combinar: &=Items.ItemName(dynamic, copystyle) crea un rango dinámico Y copia el estilo de fila a cada registro insertado.
Fuentes de datos anidadas
Cuando el JSON Envuelve tu matriz bajo un objeto padre, accede a él con una ruta punteada. El Factura hoja de template.xlsx es el ejemplo canónico. Sus marcadores en la fila 2 se leen a través de RootData en 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 carga útil correspondiente es 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 }
]
}
}
Nótese el apóstrofo incrustado en "Mouse's". Los marcadores inteligentes conservan las primitivas de cadena entre comillas por defecto (el StrictJsonStrings configuración predeterminada verdadero). Configúralo en FALSO cuando quieras que el motor convierta las cadenas numéricas o de fecha entre comillas en cadenas de texto Excel valores de celda durante la fusión.
Excel Tablas y referencias estructuradas
La hoja de factura de template.xlsx demuestra un potente patrón de marcadores inteligentes: la fila de marcadores se encuentra dentro de un Excel Mesa (nombrado SimpleInvoiceLas celdas de fórmula hacen referencia a las columnas de la tabla mediante referencias estructuradas en lugar de direcciones A1, y el rango de la tabla crece automáticamente a medida que los marcadores inteligentes insertan nuevas filas.
Una celda de fórmula representativa de la hoja de facturación:
=IFERROR(IF(SimpleInvoice[[#This Row],[Unit price]]="","",
(SimpleInvoice[[#This Row],[Qty]] * SimpleInvoice[[#This Row],[Unit price]])
- SimpleInvoice[[#This Row],[Discount]]
), "")
Las celdas de agregación fuera de la tabla hacen referencia a columnas completas:
G7: =SUM(SimpleInvoice[Price]) // Invoice subtotal
G9: =IFERROR(G7*G8,"") // Sales tax (G8 is rate)
G11: =SUM(G2:G4)-G10 // Total (G10 is deposit)
Por qué esto importa: cuando el motor expande la fila de marcadores de 1 registro a N registros, SimpleInvoice El rango de la tabla se expande automáticamente. SUM(SimpleInvoice[Price]) Sigue sumando la columna derecha, y las fórmulas por fila se propagan hacia abajo sin que tengas que crearlas para cada registro.
Plantillas de varias hojas
Excel Populate puede rellenar todas las hojas de un libro de trabajo en una sola llamada, o restringir la combinación a un subconjunto utilizando el Índices de hojas de trabajo parámetro (basado en 1, separado por comas). El template-3-sheets.xlsx La muestra contiene tres hojas, en este orden exacto:
| Posición | Nombre de la hoja | Marcadores utilizados | Muestra 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 |
Para rellenar las tres hojas en una sola llamada, combine las tres JSON cargas útiles en un único objeto cuyas claves de nivel superior coinciden con los nombres de las fuentes de datos de los marcadores:
{
"Items": [ { "ItemName": "A123", "Qty": "55", "UnitPrice": "3.05" }, ... ],
"Employees": [ { "EmployeeName": "John Doe", "Department": "IT", "Salary": "5000" }, ... ],
"Products": [ { "ProductName": "Laptop", "Category": "Electronics", "Stock": "15" }, ... ]
}
Para rellenar solo la hoja de Empleados, pase Worksheet Indexes = 2 en la llamada de acción. Las posiciones 1 y 3 se dejan sin modificar. Para rellenar solo Artículos + Productos, pase 1,3.
Manejo de fórmulas
Los marcadores inteligentes cooperan con sistemas nativos. Excel Fórmulas. Dos reglas importantes:
- Las fórmulas estáticas sobreviven a la expansión. Una fórmula como
=B2*C2en una fila que obtiene copias expandidas hasta cada fila poblada con las referencias de celda ajustadas de la forma habitual Excel De esta manera, no necesitas un marcador para la celda de la fórmula. - El recálculo está activado por defecto. El
Calculate FormulasEsta configuración controla si el libro de trabajo se recalcula después de la población. Déjelo como está. verdadero para recibir un libro de trabajo cuyos totales y agregados sean precisos en el momento en que lo abra. Configúrelo en FALSO cuando planeas recalcular más adelante en tu propio proceso y quieres evitar el costo.
Formato cultural y regional
El Culture & Language Settings El parámetro acepta un nombre de cultura estándar (en-US, fr-FR, de-DE, ja-JP, etc.) y controla cómo se formatean los números, las fechas y la moneda cuando el motor escribe. JSON valores en Excel celdas. Configúrelo para que coincida con la configuración regional que esperan sus destinatarios. El valor predeterminado es en-US.
El relacionado Prefijo de cita al estilo El entorno conlleva el Excel Se añade la etiqueta quote-prefix a los valores con formato cuando está presente, de modo que los valores que parecen números pero que deberían mostrarse como texto (números de cuenta, códigos postales con ceros iniciales) siguen siendo texto.
Patrones comunes
Partidas de factura con fila de totales
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)
Cuando el motor expande la fila 5 para cada elemento, el rango SUMA en la fila 6 se expande con él porque se encuentra debajo de las filas de marcadores.
Tabla comparativa lado a lado (horizontal)
A1: Metric B1: &=Months.Name(horizontal)
A2: Revenue B2: &=Months.Revenue(horizontal)
A3: Expenses B3: &=Months.Expenses(horizontal)
Cada mes se convierte en una nueva columna a la derecha de B en lugar de una nueva fila debajo.
Etiquetas preimpresas (noadd)
Cuando tienes 24 celdas de etiquetas preformateadas en una hoja y quieres que los datos fluyan hacia ellas sin agregar filas:
&=Labels.Name(noadd)
&=Labels.Address(noadd)
El motor rellena las 24 filas existentes en orden y trunca silenciosamente cualquier registro que exceda el espacio disponible.
Lista de verificación rápida
&=&= en la celda A1 (o en cualquier otra celda). Cualquier otro valor se trata como un valor celular normal.Nombre del artículo en la plantilla NO coincide nombre del artículo en el JSON.