表达式是 Handlebars 模板的基本组成单位,单独使用 `{{mustache}}`,pass them to a Handlebars helper, or use them as values in hash arguments.
基本用法
-------
最简单的表达式是通过 `{{` 和 `}}` 包裹数据属性名
```html
{{title}}
```
``{{title}}``会查找当前上下文 [(上下文?)](#) 中的 `title` 属性。 Block helpers 会改变当前上下文,但他不会改变表达式的语法。
Actually, it means "look for a helper named title, then do the above", but we'll get to that soon enough.
你还可以使用 `.` 查找属性的子元素
```html
{{article.title}}
```
这个示例的意思是:寻找当前上下文中的 `article` 属性,然后查找 `article` 属性的 `title` 属性。找到后输出 `title`
handlebars也支持已经弃用的 `/` 分隔符,上面的表达式也可以写成:
```html
{{article/title}}
```
标识符可以是除了以下字符以外的任何 unicode 字符:
空白 `!` `"` `#` `%` `&` `'` `(` `)` `*` `+` `,` `.` `/` `;` `<` `=` `>` `@` `[` `\` `]` `^` `{` `|` `}` `~` `
如果你的标识符是特殊字符,可以使用 `[` 和 `]` 包裹标识符:
```html
{{#each articles.[10].[#comments]}}
{{subject}}
{{body}}
{{/each}}
```
模板中的 `articles.[10].[#comments]` 相当于 JavaScript 中的 `object.articles[10]["#comments"]`。[示例](demo/property-not-a-valid-identifier.html)
`articles` 也可以是对象,如果是对象则访问 `articles` 的 `10` 属性。
You may not include a closing `]` in a path-literal, but all other characters are fair game.
Handlebars 会转义HTML,你可以使用 `{{{` 避免转义
```
{{{foo}}}
```
[示例](demo/HTML-escapes.html)
转义HTML 指的是:
& 会被转换为 &
< ~ <
> ~ >
" ~ "
' ~ '
` ~ `
Helpers
-------
Helper 语法是简单的标识符后面紧跟着一个或多个参数(用空格分隔),每个参数都是 Handlebars 表达式。
```
{{{link story}}}
```
如上示例,`link` 是 helper 的名称,`story` 是 helper 的参数。Handlebars evaluates parameters in exactly the same way described above in "Basic Usage".
```
Handlebars.registerHelper('link', function(object) {
var url = Handlebars.escapeExpression(object.url),
text = Handlebars.escapeExpression(object.text);
return new Handlebars.SafeString(
"" + text + ""
);
});
```
当一个 helper 返回 HTML 字符串 时。你应该使用 `SafeString` 来避免转义,确保输出的是可渲染的HTML。
当使用 `SafeString` 时,应主动使用 `escapeExpression` 方法将不安全的数据过滤。
你也可以向 helper 传入字符串、数字或布尔值
```
{{{link "See more..." story.url}}}
```
在这种情况下,把手将通过链接帮手两个参数:字符串“查看更多......”而在当前的背景下评估story.url的结果。
此时,Handlebars 会将字符串参数 `"See more..."` 和当前上下文的 `story.url` 传递给 helper link。
```
Handlebars.registerHelper('link', function(text, url) {
url = Handlebars.escapeExpression(url);
text = Handlebars.escapeExpression(text);
return new Handlebars.SafeString(
"" + text + ""
);
});
```
[示例](demo/expressions-1.html)
你还可以使用 `story.text` 来渲染动态文本
```
{{{link story.text story.url}}}
```
[示例](demo/expressions-2.html)
Handlebars helpers 支持传入任意顺序的 key-value (在本文档中被称为 hash arguments):
```
{{{link "See more..." href=story.url class="story"}}}
```
此处 hash arguments 是 `href=story.url class="story"`。
- `href`是 key `story.url` 是 value
- `class`是 key `"story"` 是 value
hash arguments 必须是简单的标识符,value 必须是表达式。value 的值可以是标识符、路径和字符串。
```
Handlebars.registerHelper('link', function(text, options) {
var attrs = [];
for (var prop in options.hash) {
attrs.push(
Handlebars.escapeExpression(prop) + '="'
+ Handlebars.escapeExpression(options.hash[prop]) + '"');
}
return new Handlebars.SafeString(
"" + Handlebars.escapeExpression(text) + ""
);
});
```
最终渲染结果:
```
See more...
```
上例中的 `options.hash` 可访问 hash arguments 。[示例](demo/expressions-3.html)
Handlebars also offers a mechanism for invoking a helper with a block of the template. Block helpers can then invoke that block zero or more times with any context it chooses.
了解更多:块 helpers
子表达式
------
Handlebars 支持子表达式, 子表达式的结果可作为父表达式的参数,字表达式使用括号分割 `(`。
```
{{outer-helper (inner-helper 'abc') 'def'}}
```
在这个示例中,`'abc'` 作为 `inner-helper` 的参数被调用,而 `inner-helper` 的返回值作为 `outer-helper` 的第一个参数被调用(`'def'` 作为第二个参数被调用)。
[示例](demo/expressions-subexpressions.html)
控制空格
------
模板空白可由任何 mustache 语法括号中任意一侧添加 `~` 字符以删除。When applied all whitespace on that side will be removed up to the first handlebars expression or non-whitespace character on that side.
```html
{{#each nav ~}}
{{~#if test}}
{{~title}}
{{~else~}}
Empty
{{~/if~}}
{{~/each}}
```
数据为:
```js
{
"nav": [
{"url": "foo", "test": true, "title": "bar"},
{"url": "bar"}
]
}
```
最终会输出无换行和空格的内容
```html
barEmpty
```
[示例](demo/expressions-whitespaccontrol-1.html)
This expands the default behavior of stripping lines that are "standalone" helpers (only a block helper, comment, or partial and whitespace).
```html
{{#each nav}}
{{#if test}}
{{title}}
{{else}}
Empty
{{/if}}
{{~/each}}
```
渲染结果:
```html
bar
Empty
```
[示例](demo/expressions-whitespaccontrol-2.html)
Id Tracking
------
Optionally, helpers can be informed of the paths that were used to lookup an argument for a given value. This mode may be enabled via the `trackIds` compiler flag.
```
{{foo bar.baz}}
```
would call the helper `foo` with the value of `bar.baz` but also will include the literal string `"bar.baz"` in the `ids` field on the `options` argument.
This can be used for future lookup of parameters should it be necessary, but does add additional overhead.
When this mode is enabled, all builtin helpers will generate a [@contextPath](reference.html#data-contextPath)
variable that denotes the lookup path for the current context. It's highly recommended that generic helpers provide such a variable if they modify the context when executing their children.