| Suite | Growth, Professional, Enterprise, or Enterprise Plus |
| Support with | Guide all plans |
本文章涵盖以下主题：
简介
每个帮助中心主题都包含一系列 可编辑的页面模板 ，用于定义帮助中心中不同类型页面的布局。包含用于知识库文章的模板、用于请求列表的模板等。
每个模板都包含 HTML 标记和类 Handlebars 的表达式，可在模板中通过双花括号识别。Handlebars 是一个简单的模板化引擎，可用于在呈现时（而不是设计时）插入或操作页面上的内容。
帮助中心中的模板化语言称为 Curlybars，实施了 Handlebars 语言的一大子集。本指南介绍了如何使用语言自定义帮助中心的页面。
帮助中心为您提供了助手和命名属性以自定义内容。有些是共享的，在所有帮助中心页面上都可用。其余的则因页面而异。
示例
{{#each comments}}
<li class="comment" id="{{comment_id}}">
<div class="comment-avatar {{#if author.agent}} comment-avatar-agent {{/if}}">
<img src="{{author.avatar_url}}" alt="Avatar" />
</div>
<div class="comment-container">
<header class="comment-header">
<strong class="comment-author">
{{author.name}}
</strong>
</header>
</div>
</li>
{{/each}}
本例生成了一个在页面上留下评论的用户列表。each 助手遍历页面的 comments 属性的每个值。对于每条评论， author.avatar_url 和 author.name 属性插入到 HTML 中。
模板化基础知识
本部分介绍了编写任何模板所需的组成部分。有关更多信息，请参阅 developer.zendesk.com 上的 帮助中心模板 。
Curlybars 模板由两部分组成：要按原样呈现的逐字文本和 Curlybars 表达式。这意味着空白模板也是有效的模板，仅包含文本的模板也是有效的模板。例如，以下是有效的模板：
<h1>Article</h1>
<p>Some details on the article</p>
当然，如果帮助中心模板仅支持逐字文本，您无法在呈现时真正对其进行自定义。要添加模板化逻辑，您需要 Curlybars 表达式，括在双花括号里（{{ 和 }}）。
要在上一个示例中添加模板化逻辑，您可以按如下方式修改模板：
<h1>Article</h1>
<p>Some details on the article</p>
{{article.author.name}}
以下各部分说明了如何编写有效的表达式以对模板进行有意义的更改。
请注意，将一对花括号嵌套在其他对花括号中不是有效的语法。例如，不允许使用以下内容：
<h1>Article</h1>
<p>Some details on the article</p>
{{ {{ ... }} }}
评论
在某些情况下，模板中的一些注释可能会派上用场，因为这些注释不会泄漏到所呈现的页面中。为此，Curlybars 允许注释时在前大花括号后添加感叹号，中间不要有空格： {{! ... }}更新。您可以使用以下语法添加代码注释，如下所示：
{{!
This template aims to
show details of an article
}}
<h1>Article</h1>
<p>Some details on the article</p>
以下是页面呈现后发送到浏览器的内容：
<h1>Article</h1>
<p>Some details on the article</p>
这种舍弃评论中所有内容的效果在开发模板时确实会派上用场。您可能需要注释一些代码以进行检查、调试等。
阻止评论
遗憾的是，上述注释语法不适合注释 Curlybars 代码。要注释 Curlybars 代码，请使用以下语法：{{!-- ... ---}}。这种注释可以跨越多行，有效地注释代码。例如：
{{!
This template aims to
show details of an article
}}
<h1>Article</h1>
<p>Some details on the article</p>
{{!--
I want to commend out the following code:
{{ ... some Curlybars expressions }}
--}}
上面的模板呈现如下：
<h1>Article</h1>
<p>Some details on the article</p>
文本
要包含您希望 Curlybars 准确解释的值，Curlybars 支持 文本的概念。文本可表示 3 种类型的值： 字符串、 布尔值或 数字。
要表达字符串，您可以使用单引号和双引号，但不能混合使用。例如 'this is a valid string'、"this is valid as well"，但不允许 "this is not valid'。
数字可以是任意正整数或负整数。 123 是有效的正数， +123 表示相同的值， 00123 仍然有效，并且 -123 也有效。
布尔值表达式为 true 和 false。不允许有其它变化。例如，TRUE 和 FALSE 在 Curlybars 中不解释为布尔值。
您可以呈现文本。例如：
A string: {{ 'hello world' }}
A boolean: {{ true }}
A number: {{ 42 }}
页面呈现如下：
A string: 'hello world'
A boolean: true
A number: 42
属性
帮助中心中的每个模板都可以访问表示帮助中心数据的 上下文 。例如，文章页面模板有一个名为 article 的对象，显示用户请求的文章的结构。有关可在模板中使用的所有属性，请参阅 developer.zendesk.com 上的 帮助中心模板 。
使用点符号从这些对象中提取特定信息。article.title 就是示例之一。
属性的完全限定名称有时称为 路径。例如，name 是 author 对象中的属性，但 article.author.name 是其路径。
显示属性值时可以将其括在双花括号中。回到这个例子，您可能想在单独的段落中打印出作者的姓名：
<h1>Article</h1>
<p>Author: {{article.author.name}}</p>
假设用户想查看一篇由专员 John Venturni 撰写的文章。模板将呈现如下：
<h1>Article</h1>
<p>Author: John Venturini</p>
您可能还想呈现文章本身。article 对象的 body 属性包含文章内容。您应按如下方式修改模板以呈现文章的正文：
<h1>Article</h1>
<p>Author: {{article.author.name}}</p>
<article>{{article.body}}</article>
条件语句
除了呈现属性值之外，模板化语言还允许您在模板中添加条件呈现逻辑。
例如，您可能想呈现一个 HTML 片段，以防请求的文章是内部文章。文章页面背景信息中有一个 article.internal 属性，如果文章是内部，则返回 true，否则返回 false。
您可以创建此信息的 if 代码块。的 if 表达式 必须指定一个为 true 或 false 的条件。其结果决定了是否呈现块中的内容。基本语法如下：
{{#if condition}}
This is rendered if the condition is true.
{{/if}}
您可以按如下方式修改示例模板：
<h1>Article</h1>
{{#if article.internal}}
<p>This article is internal.</p>
{{/if}}
<p>Author: {{article.author.name}}</p>
<article>{{article.body}}</article>
当条件为 false 时，您可能希望呈现一个块。在这种情况下，请使用 unless 代码块。语法类似于 if 代码块：
{{#unless condition}}
This is rendered if the condition is false.
{{/unless}}
回到这个例子，假设您还想在文章不是内部时呈现一条消息。您可以如下方式修改模板：
<h1>Article</h1>
{{#if article.internal}}
<p>This article is internal.</p>
{{/if}}
{{#unless article.internal}}
<p>This is a publicly visible article!</p>
{{/unless}}
<p>Author: {{article.author.name}}</p>
<article>{{article.body}}</article>
这种条件逻辑--“if true do this or else do this”--通常由 if-else 代码块处理。语法如下：
{{#if condition}}
This is rendered if the condition is true.
{{else}}
This is rendered if the condition is false.
{{/if}}
您可以按如下方式修改示例：
<h1>Article</h1>
{{#if article.internal}}
<p>This article is internal.</p>
{{else}}
<p>This is a publicly visible article!</p>
{{/if}}
<p>Author: {{article.author.name}}</p>
<article>{{article.body}}</article>
unless 内容库还有一个 unless-else 变量。您可以用其达到 if-else 代码块的相同结果：
<h1>Article</h1>
{{#unless article.internal}}
<p>This is a publicly visible article!</p>
{{else}}
<p>This article is internal.</p>
{{/unless}}
<p>Author: {{article.author.name}}</p>
<article>{{article.body}}</article>
如何评估条件
条件通常是一个帮助中心属性，例如 article.internal，其布尔值为 true 或 false。某些属性没有布尔值。这些属性的计算方式如下：
-
如果值是一个数字，则 0 为 false，任何其他数字为 true
-
如果值是一个字符串，空字符串为 false，任何其它字符串为 true
-
如果值是对象集合，空集合为 false，任何其他集合为 true
-
如果值为 null，则表达式为 false
假设您要设置一些检查数字的条件逻辑。文章页面有一个 article.comment_count 属性，包含文章中的评论总数。您可以使用 if 条件来测试计数是否为 0，并显示一些令人愉快的消息。例如：
<h1>Article</h1>
<p>Author: {{article.author.name}}</p>
<article>{{article.body}}</article>
{{#if article.comment_count}}
<p>Yahoo! This article has got some comments!</p>
{{/if}}
修剪空格
Curlybars 处理模板时会按原样显示所有逐字文本。此功能在大多数情况下正常运行。然而，有时您需要对表达式旁边的空白字符有更多的控制。以下面的代码为例：
<a href="..." class="{{#if highlighted}} highlight {{/if}}">Click me!</a>
当 highlighted 为 true 时，它会显示如下 HTML：
<a href="..." class=" highlight ">Click me!</a>
在单词 “突出显示”周围各有一个前导和一个尾随空格。这固然不错，但假如您想将空格保留在模板中而不显示。您可以使用代字号字符 (~)。
在左花括号或右大括号中添加代字号字符可以剪掉所含文本中的空格。例如：
<a href="..." class="{{#if highlighted~}} highlight {{~/if}}">Click me!</a>
波浪形字符修整单词 highlight 周围的前导和尾随空格：
<a href="..." class="highlight">Click me!</a>
代字号字符会剪裁没有图形表示形式但影响间距或分割线的任何空白字符，例如换行符、制表符、回车符、换行符、简单空格或制表符。这意味着您还可以更进一步，在更多行上表达之前的 if 代码块，使其更具可读性。例如：
<a href="..." class="
{{~#if highlighted~}}
highlight
{{~/if~}}
">Click me!</a>
该表达式仍显示如下：
<a href="..." class="highlight">Click me!</a>
这些示例在现实生活中没有多大意义，但使用代字号字符的有效性因具体情况而异。
助手
在某些模板中，您只需访问、显示数据并添加一些条件逻辑即可。尽管如此，您可能会喜欢一些额外的功能。例如，您可能想显示一个根据页面请求者的区域设置进行变化的本地化字符串。或者您可能想截断很长的文本段落。
您可以使用 助手在模板中获得此类功能。有关可以在模板中使用的所有助手的信息，请参阅 developer.zendesk.com 上的 帮助中心模板 。
例如，您可以在文章页面模板中使用一个名为 excerpt 的助手以截断字符串。以文章标题为例，假设您需要显示文章标题的删节版本。您可以通过修改模板来做到这一点，如下所示：
<h1>{{excerpt article.title characters=50}}</h1>
<p>Author: {{article.author.name}}</p>
<article>{{article.body}}</article>
从上面的例子可以看出，花括号是用来调用助手的。的 excerpt 助手接受包含可解析为字符串的表达式的参数。助手有 characters 选项以指定要保留的字符数。characters 是非必要选项。如果不指定，则使用默认值。有关更多详情，请参阅帮助中心模板中的 摘录 。
调用助手的语法是 {{<helper> [<param> ...] [<key=value> ...]}}。唯一的必填元素是助手的名称。参数和选项因助手而异。
现在，假设您要更新模板，使其显示一条欢快的消息，作者姓名是 John Venturni。很遗憾，您无法使用 if 条件检查 article.author.name 是否等于 "John Venturini"，因为 if 仅适用于一个表达式。== 之类的比较运算符不可用。
那么如何添加这样的逻辑呢？好在您可以使用 is 助手。它接收两个参数，并测试它们是否相等。例如：
<h1>{{excerpt article.title characters=50}}</h1>
{{#is article.author.name 'John Venturini'}}
<p>Cool! John Venturini is the author of this article!</p>
{{/is}}
<article>{{article.body}}</article>
如果作者是 John Venturino，上面的代码段将呈现令人愉快的消息。但是，如果您想在作者不是他的情况下呈现另一条消息，该怎么办？好消息是 is 还可以包含 else 代码块，就像 if-else 语句。要恢复旧的消息，如果作者不是 John Venturino，您可以添加 else 代码块，如下所示：
<h1>{{excerpt article.title characters=50}}</h1>
{{#is article.author.name 'John Venturini'}}
<p>Cool! John Venturini is the author of this article!</p>
{{else}}
<p>Author: {{article.author.name}}</p>
{{/is}}
<article>{{article.body}}</article>
更改范围
使用点标记法访问数据非常简单，尤其是当我们所需信息的路径不太长时。例如：article.title。但在某些情况下，您可能希望访问具有较长路径的属性。例如：article.author.name。如果需要，您可以在模板中使用更长的路径。例如，您可以添加本例中的作者姓名和头像，如下所示：
<h1>{{excerpt article.title characters=50}}</h1>
<img src="{{article.author.avatar_url}}" alt="Author's avatar" height="42" width="42">
{{#is article.author.name 'John Venturini'}}
<p>Cool! John Venturini is the author of this article!</p>
{{else}}
<p>Author: {{article.author.name}}</p>
{{/is}}
<article>{{article.body}}</article>
上面的代码段正常显示，但较长的属性路径使代码看起来有点混乱。解决此问题的方法之一是使用特殊的 with 构造函数。with 接受一个参数，表示要在关联代码块中使用的基本上下文。语法如下：
{{#with <context>}}
...
{{/with}}
您可以按如下方式改进示例：
<h1>{{excerpt article.title characters=50}}</h1>
{{#with article.author}}
<img src="{{avatar_url}}" alt="Author's avatar" height="42" width="42">
{{#is name 'John Venturini'}}
<p>Cool! John Venturini is the author of this article!</p>
{{else}}
<p>Author: {{name}}</p>
{{/is}}
{{/with}}
<article>{{article.body}}</article>
凭借 article.author 参数，用户就不必在代码块的任何路径中包含 article.author。所以代码块中的 {{name}} 等于代码块之外的 article.author.name。
您无法在代码块中使用 article.author.name，因为它可能被评估为 article.author.article.author.name。同样，您不能在包含 article.title 的代码块中访问文章标题，因为文章对象只能在代码容块外部的根上下文中访问。
要从 with 设置的上下文转义并访问外部上下文，可在路径中使用 ../ 注释。您可以在 with 代码块中显示文章标题，如下所示：
<h1>{{excerpt article.title characters=50}}</h1>
{{#with article.author}}
{{../article.title}}
<img src="{{avatar_url}}" alt="Author's avatar" height="42" width="42">
{{#is name 'John Venturini'}}
<p>Cool! John Venturini is the author of this article!</p>
{{else}}
<p>Author: {{name}}</p>
{{/is}}
{{/with}}
<article>{{article.body}}</article>
您可以相同的路径中重复使用 ../ 符号。它将跳回相同数量的上下文。例如，以下示例仍可正常工作：
<h1>{{excerpt article.title characters=50}}</h1>
{{#with article}}
{{#with author}}
{{../../article.title}}
...
{{/with}}
<article>{{article.body}}</article>
您可能需要采取防御措施，并在未指定作者时呈现特定消息。您可能会决定使用 if 代码块进行此操作，如下所示：
<h1>{{excerpt article.title characters=50}}</h1>
{{#if article.author}}
{{#with article.author}}
...
{{/with}}
{{else}}
No author is present for this article!
{{/if}}
<article>{{article.body}}</article>
请注意，在帮助中心里，article.author 实际上决不会为空。我们在这里这样假设只是为了方便举例。
上面的代码段是对的，但是您也可以通过 else 代码块在 with 构造函数中实现相同结果。如果参数为 false，则执行 else 块。您可以如下修改示例：
<h1>{{excerpt article.title characters=50}}</h1>
{{#with article.author}}
...
{{else}}
No author is present for this article!
{{/with}}
<article>{{article.body}}</article>
使用 else 代码块也会让代码更具可读性。
将根上下文传递给助手
使用 this 关键字以将当前的根上下文传递给助手。假设您有 render_author 助手，接受 article 对象作为参数，以显示关于其作者的详细信息。您可以使用 this 关键字，如下所示：
<h1>{{excerpt article.title characters=50}}</h1>
{{#with article}}
{{render_author this}}
{{/with}}
<article>{{article.body}}</article>
this 将被解析为 article。
访问数组中的项目
一些帮助中心属性包含对象数组。例如，attachments 属性包含一系列附件。
要访问数组中的项目，需要遍历数组中的每一项。each 助手正是这样。例如：
<h1>{{excerpt article.title characters=50}}</h1>
{{#with article.author}}
...
{{/with}}
<article>{{article.body}}</article>
{{#each attachments}}
<a href="{{url}}" target="_blank">{{name}}</a>
<span>({{size}})</span>
{{/each}}
上面的代码段列出了所有的附件。每个列表项目都显示每个附件的特定数据，例如 url、name 和 size。
例如 with，each 会更改其代码块中的背景信息。这意味着如果您要访问外部上下文，可以使用 ../ 符号。
您可能希望在数组为空时呈现消息。您可以使用 if 代码块轻松达到此目的，如下所示：
...
{{#if attachments}}
{{#each attachments}}
<a href="{{url}}" target="_blank">{{name}}</a>
<span>({{size}})</span>
{{/each}}
{{else}}
Sorry, no attachments available!
{{/if}}
这很好用，但您也可以使用 else 代码块以提高代码的可读性：
...
{{#each attachments}}
<a href="{{url}}" target="_blank">{{name}}</a>
<span>({{size}})</span>
{{else}}
Sorry, no attachments available!
{{/each}}
长度
每个数组都有一个隐式 length 属性，给出数组中元素的数量。例如，如果您想显示附件数量，请使用 length 属性如下：
...
There are {{attachments.length}}.
{{#each attachments}}
<a href="{{url}}" target="_blank">{{name}}</a>
<span>({{size}})</span>
{{/each}}子表达式
子表达式允许您在单个表达式中调用多个助手，并将内部助手调用的结果作为参数传递给外部助手。子表达式由括号定界。
以下示例显示了表达式中的子表达式：
{{search placeholder=(dc "search_text")}}
子表达式可以嵌套：
{{search placeholder=(excerpt (dc "search_text"))}}
子表达式可在条件助手中使用：
{{#if (compare collection.length "==" 0)}}
<div>Empty collection.</div>
{{else}}
<div>Your collection has {{collection.length}} items</div>
{{/if}}
子表达式可在数组迭代器助手中使用：
{{#each (slice (filter user.badges on="category_slug" equals="achievements")
0 4)}}
<section>
<h3>{{name}}</h3>
<div>{{description}}</div>
</section>
{{/each}}
0 条评论