/
expressions.html
252 lines (238 loc) · 23.9 KB
/
expressions.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
<!DOCTYPE html>
<html lang="en">
<head>
<title>Handlebars 中文网：轻逻辑语义化的模板引擎</title>
<meta charset="UTF-8">
<link href="static/stylesheets/application.css" media="all" rel="stylesheet" type="text/css"/>
<link href="static/stylesheets/sunburst.css" media="all" rel="stylesheet" type="text/css"/>
<link href="static/stylesheets/site.css" media="all" rel="stylesheet" type="text/css"/>
<link href="static/images/favicon.png" rel="shortcut icon" type="image/png" />
</head>
<body>
<div id="body">
<div id="header">
<a href="index.html">
<img alt="Handlebars 中文网：轻逻辑语义化的模板引擎" src="static/images/handlebars_logo.png"/>
</a>
</div>
<div id="contents">
<a href="http://www.devswag.com/collections/handlebars" id="callout">
<img alt="Buy Handlebars swag on DevSwag!" src="static/images/handlebars-devswag.png"/>
</a>
<div id="intro">
表达式是 Handlebars 模板的基本组成单位，单独使用 <code>{{mustache}}</code>，pass them to a Handlebars helper, or use them as values in hash arguments.
</div>
<h2>基本用法</h2>
<!-- Start .contents-->
<dic class="contents">
<div class="bullet">
<p>最简单的表达式是通过 <code>{{</code> 和 <code>}}</code> 包裹数据属性名</p>
<pre><code class="lang-html"><span class="xml"><span class="hljs-tag"><<span class="hljs-title">h1</span>></span></span><span class="hljs-expression">{{<span class="hljs-variable">title</span>}}</span><span class="xml"><span class="hljs-tag"></<span class="hljs-title">h1</span>></span></span>
</code></pre>
<p><code>{{title}}</code>会查找当前上下文 <a href="#" target="_blank">（上下文？）</a> 中的 <code>title</code> 属性。 Block helpers 会改变当前上下文，但他不会改变表达式的语法。</p>
<p>Actually, it means "look for a helper named title, then do the above", but we'll get to that soon enough.</p>
</div>
<div class="bullet">
<p>你还可以使用 <code>.</code> 查找属性的子元素</p>
<pre><code class="lang-html"><span class="xml"><span class="hljs-tag"><<span class="hljs-title">h1</span>></span></span><span class="hljs-expression">{{<span class="hljs-variable">article.title</span>}}</span><span class="xml"><span class="hljs-tag"></<span class="hljs-title">h1</span>></span></span>
</code></pre>
<p>这个示例的意思是：寻找当前上下文中的 <code>article</code> 属性，然后查找 <code>article</code> 属性的 <code>title</code> 属性。找到后输出 <code>title</code></p>
<p>handlebars也支持已经弃用的 <code>/</code> 分隔符，上面的表达式也可以写成：</p>
<pre><code class="lang-html"><span class="xml"><span class="hljs-tag"><<span class="hljs-title">h1</span>></span></span><span class="hljs-expression">{{<span class="hljs-variable">article</span><span class="hljs-end-block">/title</span>}}</span><span class="xml"><span class="hljs-tag"></<span class="hljs-title">h1</span>></span></span>
</code></pre>
</div>
<div class="bullet">
<p>标识符可以是除了以下字符以外的任何 unicode 字符:</p>
<p>空白 <code>!</code> <code>"</code> <code>#</code> <code>%</code> <code>&</code> <code>'</code> <code>(</code> <code>)</code> <code>*</code> <code>+</code> <code>,</code> <code>.</code> <code>/</code> <code>;</code> <code><</code> <code>=</code> <code>></code> <code>@</code> <code>[</code> <code>\</code> <code>]</code> <code>^</code> <code>{</code> <code>|</code> <code>}</code> <code>~</code> <code>`</code></p>
</div>
<div class="bullet"
<p><a name="property-not-a-valid-identifier.html" target="_blank"></a></p>
<p>如果你的标识符是特殊字符，可以使用 <code>[</code> 和 <code>]</code> 包裹标识符：</p>
<pre><code class="lang-html"><span class="xml"></span><span class="hljs-expression">{{<span class="hljs-begin-block">#<span class="hljs-keyword">each</span> articles.</span>[10]<span class="hljs-variable">.</span>[<span class="hljs-begin-block">#comments</span>]}}</span><span class="xml">
<span class="hljs-tag"><<span class="hljs-title">h1</span>></span></span><span class="hljs-expression">{{<span class="hljs-variable">subject</span>}}</span><span class="xml"><span class="hljs-tag"></<span class="hljs-title">h1</span>></span>
<span class="hljs-tag"><<span class="hljs-title">div</span>></span>
</span><span class="hljs-expression">{{<span class="hljs-variable">body</span>}}</span><span class="xml">
<span class="hljs-tag"></<span class="hljs-title">div</span>></span>
</span><span class="hljs-expression">{{<span class="hljs-end-block">/<span class="hljs-keyword">each</span></span>}}</span><span class="xml"></span>
</code></pre>
<p>模板中的 <code>articles.[10].[#comments]</code> 相当于 JavaScript 中的 <code>object.articles[10]["#comments"]</code>。<a href="demo/property-not-a-valid-identifier.html" target="_blank">示例</a></p>
<div class="translator">
<code>articles</code> 也可以是对象，如果是对象则访问 <code>articles</code> 的 <code>10</code> 属性。
</div>
<p>You may not include a closing <code>]</code> in a path-literal, but all other characters are fair game.</p>
</div>
<div class="bullet">
<p><a name="HTML-escapes.html" target="_blank"></a></p>
<p>Handlebars 会转义HTML，你可以使用 <code>{{{</code> 避免转义</p>
<pre><code><span class="hljs-collection">{<span class="hljs-collection">{<span class="hljs-collection">{foo}</span>}</span>}</span>
</code></pre><p><a href="demo/HTML-escapes.html" target="_blank">示例</a></p>
<div class="translator">
转义HTML 指的是:
<pre>
& 会被转换为 &amp;
< ~ &lt;
> ~ &gt;
" ~ &quot;
' ~ &#x27;
` ~ &#x60;
</pre>
</div>
</div>
<!-- End .contents-->
<h2>Helpers</h2>
<!-- Start .contents-->
<dic class="contents">
<div class="bullet"
<p>Helper 语法是简单的标识符后面紧跟着一个或多个参数（用空格分隔），每个参数都是 Handlebars 表达式。</p>
<pre><code><span class="hljs-collection">{<span class="hljs-collection">{<span class="hljs-collection">{link story}</span>}</span>}</span>
</code></pre><p>如上示例，<code>link</code> 是 helper 的名称，<code>story</code> 是 helper 的参数。Handlebars evaluates parameters in exactly the same way described above in "Basic Usage".</p>
<p><a name="SafeString-escapeExpression" target="_blank"></a></p>
<pre><code><span class="hljs-type">Handlebars</span>.registerHelper(<span class="hljs-symbol">'lin</span>k', function(<span class="hljs-class"><span class="hljs-keyword">object</span>) {</span>
<span class="hljs-keyword">var</span> url = <span class="hljs-type">Handlebars</span>.escapeExpression(<span class="hljs-class"><span class="hljs-keyword">object</span>.<span class="hljs-title">url</span>),
</span> text = <span class="hljs-type">Handlebars</span>.escapeExpression(<span class="hljs-class"><span class="hljs-keyword">object</span>.<span class="hljs-title">text</span>);</span>
<span class="hljs-keyword">return</span> <span class="hljs-keyword">new</span> <span class="hljs-type">Handlebars</span>.<span class="hljs-type">SafeString</span>(
<span class="hljs-string">"<a href='"</span> + url + <span class="hljs-string">"'>"</span> + text + <span class="hljs-string">"</a>"</span>
);
});
</code></pre><p>当一个 helper 返回 HTML 字符串 时。你应该使用 <code>SafeString</code> 来避免转义，确保输出的是可渲染的HTML。<br>当使用 <code>SafeString</code> 时，应主动使用 <code>escapeExpression</code> 方法将不安全的数据过滤。</p>
<div class="translator">
确保输出<code><a></code> 而不是 <code>&lt;a&gt;</code>，<br>并过滤 <code><span onclick="javascript:alert(1);">点击我</span></code> 这这危险数据。<br>若不明白请看 <a href="demo/SafeString-escapeExpression.html" target="_blank">示例</a>
</div>
</div>
<div class="bullet"
<p><a name="expressions-1.html" target="_blank"></a></p>
<p>你也可以向 helper 传入字符串、数字或布尔值</p>
<pre><code><span class="hljs-collection">{<span class="hljs-collection">{<span class="hljs-collection">{link <span class="hljs-string">"See more..."</span> story.url}</span>}</span>}</span>
</code></pre><p>在这种情况下，把手将通过链接帮手两个参数：字符串“查看更多......”而在当前的背景下评估story.url的结果。</p>
<p>此时，Handlebars 会将字符串参数 <code>"See more..."</code> 和当前上下文的 <code>story.url</code> 传递给 helper link。</p>
<pre><code>Handlebars.registerHelper(<span class="hljs-string">'link'</span>, function(<span class="hljs-built_in">text</span>, url) {
url = Handlebars.escapeExpression(url);
<span class="hljs-built_in">text</span> = Handlebars.escapeExpression(<span class="hljs-built_in">text</span>);
<span class="hljs-keyword">return</span> <span class="hljs-keyword">new</span> Handlebars.SafeString(
<span class="hljs-string">"<a href='"</span> + url + <span class="hljs-string">"'>"</span> + <span class="hljs-built_in">text</span> + <span class="hljs-string">"</a>"</span>
);
});
</code></pre><p><a href="demo/expressions-1.html" target="_blank">示例</a></p>
<p><a name="expressions-2.html" target="_blank"></a></p>
<p>你还可以使用 <code>story.text</code> 来渲染动态文本</p>
<pre><code><span class="xml"></span><span class="hljs-expression">{{{<span class="hljs-variable">link</span> <span class="hljs-variable">story.text</span> <span class="hljs-variable">story.url</span>}}</span><span class="xml">}</span>
</code></pre><p><a href="demo/expressions-2.html" target="_blank">示例</a></p>
</div>
<div class="bullet"
<p><a name="demo/expressions-3.html" target="_blank"></a></p>
<p>Handlebars helpers 支持传入任意顺序的 key-value （在本文档中被称为 hash arguments）：</p>
<pre><code><span class="xml"></span><span class="hljs-expression">{{{<span class="hljs-variable">link</span> <span class="hljs-string">"See more..."</span> <span class="hljs-variable">href</span>=<span class="hljs-variable">story.url</span> <span class="hljs-variable">class</span>=<span class="hljs-string">"story"</span>}}</span><span class="xml">}</span>
</code></pre><div class="translator">
此处 hash arguments 是 <code>href=story.url class="story"</code>。
<ul>
<li><code>href</code>是 key <code>story.url</code> 是 value</li>
<li><code>class</code>是 key <code>"story"</code> 是 value</li>
</ul>
</div>
<p>hash arguments 必须是简单的标识符，value 必须是表达式。value 的值可以是标识符、路径和字符串。</p>
<pre><code>Handlebars.registerHelper(<span class="hljs-string">'link'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">(text, options)</span> </span>{
<span class="hljs-keyword">var</span> attrs = [];
<span class="hljs-keyword">for</span> (<span class="hljs-keyword">var</span> prop <span class="hljs-keyword">in</span> options.hash) {
attrs.push(
Handlebars.escapeExpression(prop) + <span class="hljs-string">'="'</span>
+ Handlebars.escapeExpression(options.hash[prop]) + <span class="hljs-string">'"'</span>);
}
<span class="hljs-keyword">return</span> <span class="hljs-keyword">new</span> Handlebars.SafeString(
<span class="hljs-string">"<a "</span> + attrs.join(<span class="hljs-string">" "</span>) + <span class="hljs-string">">"</span> + Handlebars.escapeExpression(text) + <span class="hljs-string">"</a>"</span>
);
});
</code></pre><div class="translator">
<p>最终渲染结果：</p>
<pre><code><span class="hljs-tag"><<span class="hljs-title">a</span> <span class="hljs-attribute">class</span>=<span class="hljs-value">"story"</span> <span class="hljs-attribute">href</span>=<span class="hljs-value">"http://http://handlebars-cn.onface.live/"</span>></span>See more...<span class="hljs-tag"></<span class="hljs-title">a</span>></span>
</code></pre></div>
<p>上例中的 <code>options.hash</code> 可访问 hash arguments 。<a href="demo/expressions-3.html" target="_blank">示例</a></p>
</div>
<div class="bullet"
<p>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.</p>
<p><a href="block_helpers.html" class="more-info" target="_blank">了解更多：块 helpers</a></p>
</div>
<!-- End .contents-->
<p><a name="expressions-subexpressions.html" target="_blank"></a></p>
<h2>子表达式</h2>
<!-- Start .contents-->
<dic class="contents">
<div class="bullet">
<p>Handlebars 支持子表达式, 子表达式的结果可作为父表达式的参数，字表达式使用括号分割 <code>(</code>。</p>
<pre><code><span class="xml"></span><span class="hljs-expression">{{<span class="hljs-variable">outer-helper</span> (<span class="hljs-variable">inner-helper</span> '<span class="hljs-variable">abc</span>') '<span class="hljs-variable">def</span>'}}</span><span class="xml"></span>
</code></pre><p>在这个示例中，<code>'abc'</code> 作为 <code>inner-helper</code> 的参数被调用，而 <code>inner-helper</code> 的返回值作为 <code>outer-helper</code> 的第一个参数被调用（<code>'def'</code> 作为第二个参数被调用）。</p>
<p><a href="demo/expressions-subexpressions.html" target="_blank">示例</a></p>
</div>
<!-- End .contents-->
<p><a name="expressions-whitespaccontrol-1.html" target="_blank"></a></p>
<h2>控制空格</h2>
<!-- Start .contents-->
<dic class="contents">
<div class="bullet">
<p>模板空白可由任何 mustache 语法括号中任意一侧添加 <code>~</code> 字符以删除。When applied all whitespace on that side will be removed up to the first handlebars expression or non-whitespace character on that side.</p>
<pre><code class="lang-html"><span class="xml"></span><span class="hljs-expression">{{<span class="hljs-begin-block">#<span class="hljs-keyword">each</span> nav </span>~}}</span><span class="xml">
<span class="hljs-tag"><<span class="hljs-title">a</span> <span class="hljs-attribute">href</span>=<span class="hljs-value">"</span></span></span><span class="hljs-expression">{{<span class="hljs-variable">url</span>}}</span><span class="xml"><span class="hljs-tag"><span class="hljs-value">"</span>></span>
</span><span class="hljs-expression">{{~<span class="hljs-begin-block">#<span class="hljs-keyword">if</span> test</span>}}</span><span class="xml">
</span><span class="hljs-expression">{{~<span class="hljs-variable">title</span>}}</span><span class="xml">
</span><span class="hljs-expression">{{~<span class="hljs-variable"><span class="hljs-keyword">else</span></span>~}}</span><span class="xml">
Empty
</span><span class="hljs-expression">{{~<span class="hljs-end-block">/<span class="hljs-keyword">if</span></span>~}}</span><span class="xml">
<span class="hljs-tag"></<span class="hljs-title">a</span>></span>
</span><span class="hljs-expression">{{~<span class="hljs-end-block">/<span class="hljs-keyword">each</span></span>}}</span><span class="xml"></span>
</code></pre>
<p>数据为：</p>
<pre><code class="lang-js">{
"<span class="hljs-attribute">nav</span>": <span class="hljs-value">[
{"<span class="hljs-attribute">url</span>": <span class="hljs-value"><span class="hljs-string">"foo"</span></span>, "<span class="hljs-attribute">test</span>": <span class="hljs-value"><span class="hljs-literal">true</span></span>, "<span class="hljs-attribute">title</span>": <span class="hljs-value"><span class="hljs-string">"bar"</span></span>},
{"<span class="hljs-attribute">url</span>": <span class="hljs-value"><span class="hljs-string">"bar"</span></span>}
]
</span>}
</code></pre>
<p>最终会输出无换行和空格的内容</p>
<pre><code class="lang-html"><span class="hljs-tag"><<span class="hljs-title">a</span> <span class="hljs-attribute">href</span>=<span class="hljs-value">"foo"</span>></span>bar<span class="hljs-tag"></<span class="hljs-title">a</span>></span><span class="hljs-tag"><<span class="hljs-title">a</span> <span class="hljs-attribute">href</span>=<span class="hljs-value">"bar"</span>></span>Empty<span class="hljs-tag"></<span class="hljs-title">a</span>></span>
</code></pre>
<p><a href="demo/expressions-whitespaccontrol-1.html" target="_blank">示例</a></p>
<p><a name="expressions-whitespaccontrol-2.html" target="_blank"></a></p>
<p>This expands the default behavior of stripping lines that are "standalone" helpers (only a block helper, comment, or partial and whitespace).</p>
<pre><code class="lang-html"><span class="xml"></span><span class="hljs-expression">{{<span class="hljs-begin-block">#<span class="hljs-keyword">each</span> nav</span>}}</span><span class="xml">
<span class="hljs-tag"><<span class="hljs-title">a</span> <span class="hljs-attribute">href</span>=<span class="hljs-value">"</span></span></span><span class="hljs-expression">{{<span class="hljs-variable">url</span>}}</span><span class="xml"><span class="hljs-tag"><span class="hljs-value">"</span>></span>
</span><span class="hljs-expression">{{<span class="hljs-begin-block">#<span class="hljs-keyword">if</span> test</span>}}</span><span class="xml">
</span><span class="hljs-expression">{{<span class="hljs-variable">title</span>}}</span><span class="xml">
</span><span class="hljs-expression">{{<span class="hljs-variable"><span class="hljs-keyword">else</span></span>}}</span><span class="xml">
Empty
</span><span class="hljs-expression">{{<span class="hljs-end-block">/<span class="hljs-keyword">if</span></span>}}</span><span class="xml">
<span class="hljs-tag"></<span class="hljs-title">a</span>></span>
</span><span class="hljs-expression">{{~<span class="hljs-end-block">/<span class="hljs-keyword">each</span></span>}}</span><span class="xml"></span>
</code></pre>
<p>渲染结果：</p>
<pre><code class="lang-html"><span class="hljs-tag"><<span class="hljs-title">a</span> <span class="hljs-attribute">href</span>=<span class="hljs-value">"foo"</span>></span>
bar
<span class="hljs-tag"></<span class="hljs-title">a</span>></span>
<span class="hljs-tag"><<span class="hljs-title">a</span> <span class="hljs-attribute">href</span>=<span class="hljs-value">"bar"</span>></span>
Empty
<span class="hljs-tag"></<span class="hljs-title">a</span>></span>
</code></pre>
<p><a href="demo/expressions-whitespaccontrol-2.html" target="_blank">示例</a></p>
</div>
<!-- End .contents-->
<h2>Id Tracking</h2>
<!-- Start .contents-->
<dic class="contents">
<div class="bullet">
<p>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 <code>trackIds</code> compiler flag.</p>
<pre><code><span class="xml"></span><span class="hljs-expression">{{<span class="hljs-variable">foo</span> <span class="hljs-variable">bar.baz</span>}}</span><span class="xml"></span>
</code></pre><p>would call the helper <code>foo</code> with the value of <code>bar.baz</code> but also will include the literal string <code>"bar.baz"</code> in the <code>ids</code> field on the <code>options</code> argument.</p>
<p>This can be used for future lookup of parameters should it be necessary, but does add additional overhead.</p>
<p>When this mode is enabled, all builtin helpers will generate a <code><a href="reference.html#data-contextPath" target="_blank">@contextPath</a></code> 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.</p>
</div>
<!-- End .contents-->
<a class="issue-tracker" href="https://github.com/onface/handlebars-cn/issues">
发现翻译错误？告诉我们。
</a>
</div>
</div>
<div id="credits"></div>
<a href="http://github.com/onface/handlebars-cn/" id="github">
<img alt="Fork me on GitHub" src="static/images/forkme_right_darkblue_121621.png" />
</a>
</body>
</html>