Handlebars模板支持多种功能,可以帮助您正确渲染文本。在本文中,我们将介绍一些最常用的功能以及如何在 Workiva 中使用它们。
注:虽然我们在这里分别列出了每个函数,但许多 Handlebars 函数可以“堆叠”使用,或者在其他函数中使用。
每个
EACH 函数最常用,其用途是处理 JSON。该函数循环遍历 JSON 对象或数组;该函数的语法采用开始和结束代码块。数组中的每个元素都可以在 EACH 循环块中进行操作:
{{#each object }}
{{object element}}
{{/each}} 在 渲染文本模板 和 渲染文件模板 命令中,要处理的 JSON 对象/数组在 JSON 变量部分中指定:
命令的 JSON 变量部分中指定的名称将用于模板的 EACH 起始块中。对于如下所示的简单 JSON 数组,每个键(以下示例中的Priority 和 Owner )都可以在 EACH 循环中进行处理:
[
{
"所有者姓名": "Abby Steere",
"优先级": "高"
},
{
"所有者姓名": "Jeff Hickey",
"优先级": "高"
},
{
"所有者姓名": "Ryan Niebruegge",
"优先级": "高"
},
{
"所有者姓名": "Ryan Niebruegge",
"优先级": "低"
},
{
"所有者姓名": "Abby Steere",
"优先级": "中"
},
{
"所有者姓名": "Jeff Hickey",
"优先级": "中"
},
{
"所有者姓名": "Ryan Niebruegge",
"优先级": “中等的”
}
]
范例
任务所有者,任务优先级
{{#each object_items}}
{{所有者}},{{优先级}}
{{/each}}
渲染结果
EACH 函数还可以处理更复杂的 JSON 对象,包括包含嵌套数组的 JSON 对象。
示例 JSON 对象(产品列表)
{
"products": [
{
"id": 1,
"title": "iPhone 14",
"price": 799,
"brand": "Apple",
"category": "smartphones",
"images": [
"/products/1/1.jpg",
"/products/1/2.jpg",
"/products/1/3.jpg",
"/products/1/4.jpg",
"/products/1/thumbnail.jpg"
]
},
{
"id": 2,
"title": "iPhone 15",
"price": 899,
"brand": "Apple",
"category": "smartphones",
"images": [
"/products/2/1.jpg",
"/products/2/2.jpg",
"/products/2/3.jpg",
"/products/2/thumbnail.jpg"
]
},
{
"id": 3,
"title": "S23 Ultra",
"price": 1249,
"brand": "Samsung",
"category": "smartphones",
"images": [
"/products/3/1.jpg"
]
},
{
"id": 4,
"title": "Pixel 8",
"price": 799,
"brand": "Google",
"category": "smartphones",
"images": [
"/products/4/1.jpg",
] "/products/4/2.jpg", "/products/4/thumbnail.jpg"
] }
]
"limit":100
,"总计":4
,"还有更多":false
} 范例
在这个模板中,我们既要访问根元素(总计)中的一个元素,又要遍历元素数组(产品)中的元素:
JSON 对象包含 {{response.total}} 个项目:
{{#each response.products}}
{{title}}
{{/each}} 渲染结果
除非和 @FIRST / @LAST
UNLESS 函数最常与 @FIRST 或 @LAST 运算符结合使用,以控制最终渲染输出。
例如,在创建以逗号分隔的迭代值列表时,列表中的最后一个项目后面不需要逗号。通过结合使用 UNLESS 和 @LAST,可以轻松生成一个以逗号分隔但不以逗号结尾的列表。
范例
{{#each response.products}}{{title}}{{#unless @last}},{{/unless}{/each}} 使用产品列表对象渲染的结果
如果/否则如果/否则和等于
IF、ELSEIF 和 ELSE 函数允许向模板添加逻辑,以应对不同的情况。如果函数与 EQUAL 运算符结合使用,则使用 IF 时不需要使用 ELSEIF 或 ELSE。
等于运算符可用于比较文本或数值。比较文本值时,如果其中一个值是显式指定的而不是从变量中检索的,则必须将其用双引号括起来。
范例
在这个例子中,IF 函数中的“brand”是从 JSON 变量中检索出来的。执行时,该变量将被替换为对象品牌元素中的值。
{{brand}},{{#if (equal brand "Apple")}}iOS{{else}}Android{{/if}} 使用产品列表对象渲染的结果
@KEY / THIS / @INDEX
当与键名变化或未知的 JSON 对象交互时,@KEY 和 THIS 函数非常有用。
@INDEX 函数返回 each 操作中正在处理的项目的位置。
注:@INDEX 函数的索引从零开始,因此列表中的第一个元素的索引值为 0,第二个元素的索引值为 1,依此类推。
示例 JSON 正文
这是 Workiva 连接器的 获取文件属性 命令的响应:
{
"created": "2023-11-20T21:02:09.000Z",
"id": "91af3ec18c554d5a81fd4ec4edc3a897",
"metadata": {
"account": {},
"amount": {
"numberFormat": ","."
},
"entity": {}
},
"name": "Sample.csv",
"numRecords": 3,
"originalFileSize": 72,
"status": "IMPORTED",
"tableId": "d1463c30226445819b0dddf57226ccf7",
"tags": {
"WK-Chains-Source": "https://h.sandbox.wdesk.com/s/wdata/oc/app/workiva-chains/find/executor?chainId=95631\u0026chainExecutorId=4217258"
},
"updated": "2023-11-20T21:02:18.000Z",
"userId": "V0ZVc2VyHzU1OTQwMTMxODMzMTE4NzI",
"版本": 1
} 范例
{{#each properties.tags}}
{{@key}},{{{this}}}
{{/each}} 渲染结果
组合功能
本文中介绍的所有功能都可以相互结合使用。EACH 函数可以嵌套在其他 EACH 函数中;UNLESS、IF、@KEY、THIS 或 @INDEX 函数可以在 EACH 函数中使用,以有条件地控制渲染的输出。
范例
此模板结合了多种功能,用于创建 HTML 格式的表格:
- EACH 函数用于遍历产品。
- @INDEX 用于检索产品在数组中的位置。
- IF 函数会评估产品品牌,并根据条件格式化文本。
- 嵌套的 EACH 语句处理每个产品的图像。
- UNLESS 语句会在每个图像链接后添加一个换行符(
)(列表中的最后一个图像链接除外)。
| 物品 ID | 产品 | 品牌 | 价格 | 影像 |
|---|---|---|---|---|
| {{@指数}} | {{标题}} | {{品牌}} | {{价格}} | {{#each images}}{{this}}{{#unless @last}} {{/unless}{/each}} |
渲染结果
在网页或HTML兼容的电子邮件中查看时,生成的表格如下所示: