Excel 填充模板语法
PDF4me Excel 填充 使用 Aspose 智能标记 合并语法 JSON 数据输入到预先设计的程序中 Excel 工作簿。您可以像这样键入标记字段 &=Items.ItemName 直接进入正常细胞 .xlsx 然后传递工作簿以及一个文件 JSON 引擎有效载荷。本页面是语法方面的权威参考：标记格式、修饰符参数、多工作表行为、公式处理、区域设置以及可下载的示例模板。 JSON 您可以进行端到端运行的文件。
外部参考资料： 这 Excel 填充引擎实现了 Aspose.Cells 智能标记功能Aspose 官方文档是权威的语法来源；本页面对其进行了精简。 PDF4me 用户并添加 JSON-特定于有效载荷约定 PDF4me API。
示例文件
下载示例模板和配套材料 JSON 本页面使用的数据文件。请直接将它们拖放到…… PDF4me Excel 填充 REST 终点， Power Automate 操作，或任何集成平台。
&=项目。* Sheet1 样本中使用的标记。RootData.Items[] 包括描述、数量、单价、折扣和价格。项目[] 使用字符串值来执行严格模式 JSON 字符串设置。产品[]）第三张纸。雇员[]) 以填写员工名册表。选择格式
基本的智能标记是一个以“ &= （& 符号表示等于），后面跟着数据源名称、一个点和字段名称。
&=DataSource.FieldName
将标记放置在第一个记录应该所在的单元格中。当您提供一个 JSON 数组 DataSource引擎会将第一条记录写入该单元格，并为每条新增记录在其下方插入新行。同一行中带有标记的相邻单元格会一起扩展，以确保每条记录保持对齐。
最小示例
模板 （第1页） template.xlsx）正是如此：
| 一个 | B | C |
|---|---|---|
| 物品名称 | 数量 | 单价 |
&=Items.ItemName | &=Items.Qty | &=Items.UnitPrice |
JSON 有效载荷 （sheet23-data.json（匹配样本）：
{
"Items": [
{ "ItemName": "A123", "Qty": "55", "UnitPrice": "3.05" },
{ "ItemName": "B456", "Qty": "20", "UnitPrice": "5.50" },
{ "ItemName": "C789", "Qty": "10", "UnitPrice": "12.99" }
]
}
输出结果： 引擎将第一条记录写入第二行，在其下方插入两行，并按相邻标记位置对齐列。第一行的标题行保持不变。
修改器参数
智能标记接受以逗号分隔的参数列表，该列表位于字段名称后的括号内，用于控制布局和行为。
&=DataSource.FieldName(parameter1, parameter2, ...)
最有用的参数：
| 范围 | 它的作用 | 例子 |
|---|---|---|
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) |
参数可以组合使用： &=Items.ItemName(dynamic, copystyle) 创建动态范围，并将行样式复制到每个插入的记录。
嵌套数据源
当 JSON 将数组包裹在一个父对象下，使用虚线路径访问该父对象。 发票 一张纸 template.xlsx 是典型的例子。它的第二行标记读到最后。 RootData 进入 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
匹配的有效载荷是 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 }
]
}
}
注意其中嵌入的撇号 "Mouse's"智能标记默认保留带引号的字符串原语（ StrictJsonStrings 设置默认值 真的将其设置为 错误的 当您希望引擎将带引号的数字或日期字符串强制转换为类型时 Excel 合并过程中的单元格值。
Excel 表格和结构化引用
发票单 template.xlsx 展示了一种强大的智能标记模式：标记行位于一个 Excel 桌子 （命名） SimpleInvoice公式单元格通过结构化引用而不是 A1 地址来引用表格列，并且随着智能标记插入新行，表格范围会自动扩展。
发票表格中的一个典型公式单元格：
=IFERROR(IF(SimpleInvoice[[#This Row],[Unit price]]="","",
(SimpleInvoice[[#This Row],[Qty]] * SimpleInvoice[[#This Row],[Unit price]])
- SimpleInvoice[[#This Row],[Discount]]
), "")
表格引用之外的聚合单元格：
G7: =SUM(SimpleInvoice[Price]) // Invoice subtotal
G9: =IFERROR(G7*G8,"") // Sales tax (G8 is rate)
G11: =SUM(G2:G4)-G10 // Total (G10 is deposit)
为什么这很重要：当引擎将标记行从 1 条记录扩展到 N 条记录时， SimpleInvoice 表格范围自动扩展， SUM(SimpleInvoice[Price]) 它会持续对右列求和，并且每行公式会向下传播，而无需您为每个记录编写公式。
多页模板
Excel Populate 函数可以一次性填充工作簿中的每个工作表，也可以使用以下方式将合并限制为子集： 工作表索引 参数（从 1 开始，逗号分隔）。 template-3-sheets.xlsx 样品包含三张纸， 完全按照这个顺序：
| 位置 | 图纸名称 | 使用的标记 | 样本 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 |
要一次性填充所有三个工作表，请合并这三个工作表。 JSON 将有效载荷整合到一个对象中，该对象的顶级键与标记中的数据源名称匹配：
{
"Items": [ { "ItemName": "A123", "Qty": "55", "UnitPrice": "3.05" }, ... ],
"Employees": [ { "EmployeeName": "John Doe", "Department": "IT", "Salary": "5000" }, ... ],
"Products": [ { "ProductName": "Laptop", "Category": "Electronics", "Stock": "15" }, ... ]
}
要仅填充“员工”工作表，请传递 Worksheet Indexes = 2 在操作调用中，位置 1 和 3 保持不变。要仅填充“项目”和“产品”，请传递 1,3。
公式处理
智能标记与原生应用协同工作 Excel 公式。两条重要规则：
- 静态公式在膨胀过程中保持不变。 类似这样的公式
=B2*C2一行会向下复制到每个已填充的行，单元格引用也会按常规方式调整。 Excel 方法很简单。公式单元格不需要标记。 - 默认情况下已启用重新计算。 这
Calculate Formulas此设置控制工作簿在填充数据后是否重新计算。保持默认设置即可。 真的 要获取一个工作簿，使其在打开时所有总计和汇总数据都准确无误。请将其设置为 错误的 当您计划稍后在自己的流程中重新计算成本并希望跳过该成本时。
文化和地区格式
这 Culture & Language Settings 参数接受一个标准文化名称（en-US， fr-FR， de-DE， ja-JP等等）并控制引擎写入数据时数字、日期和货币的格式。 JSON 将值输入 Excel 单元格。请将其设置为与收件人期望的语言环境相匹配。默认值为 en-US。
相关 引用前缀到样式 设置包含 Excel 如果存在，则将 quote-prefix 标志添加到样式化的值上，这样看起来像数字但应该显示为文本的值（账号、带前导零的邮政编码）将保持文本形式。
常见模式
发票明细及总计行
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)
当引擎为每个项目扩展第 5 行时，第 6 行中的 SUM 范围也会随之扩展，因为它位于标记行的下方。
并排比较表（横向）
A1: Metric B1: &=Months.Name(horizontal)
A2: Revenue B2: &=Months.Revenue(horizontal)
A3: Expenses B3: &=Months.Expenses(horizontal)
每个月都会成为 B 右侧的新一列，而不是下方的新行。
预印标签（无附加信息）
当您在工作表中已有 24 个预先格式化的标签单元格，并且希望数据流入这些单元格而不添加新行时：
&=Labels.Name(noadd)
&=Labels.Address(noadd)
引擎按顺序填充现有的 24 行，并默默地截断超出容纳范围的任何记录。
快速检查清单
&=&= 在单元格 A1（或任何单元格）中。其他任何值都被视为普通单元格值。物品名称 模板中的内容不匹配 物品名称 在 JSON。