-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathdgui_template_valueinsertion.html
300 lines (212 loc) · 21.1 KB
/
dgui_template_valueinsertion.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
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
<!doctype html>
<html lang="en" class="page-type-section">
<head prefix="og: http://ogp.me/ns#">
<meta charset="utf-8">
<title>插值 - FreeMarker 手册</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="format-detection" content="telephone=no">
<meta property="og:site_name" content="FreeMarker 手册">
<meta property="og:title" content="插值">
<meta property="og:locale" content="en_US">
<meta property="og:url" content="http://freemarker.org/docs/dgui_template_valueinsertion.html">
<link rel="canoical" href="http://freemarker.org/docs/dgui_template_valueinsertion.html">
<link rel="icon" href="favicon.png" type="image/png">
<link rel="stylesheet" type="text/css" href="docgen-resources/docgen.min.css">
</head>
<body itemscope itemtype="https://schema.org/Code">
<meta itemprop="url" content="http://freemarker.org/docs/">
<meta itemprop="name" content="FreeMarker 手册">
<!--[if lte IE 9]>
<div style="background-color: #C00; color: #fff; padding: 12px 24px;">Please use a modern browser to view this website.</div>
<![endif]--><div class="header-top-bg"><div class="site-width header-top"><a class="logo" href="http://freemarker.org" role="banner"> <img itemprop="image" src="logo.png" alt="FreeMarker">
</a><ul class="tabs"><li><a href="http://freemarker.org/">Home</a></li><li class="current"><a href="index.html">Manual</a></li><li><a class="external" href="http://freemarker.org/docs/api/index.html">Java API</a></li></ul><ul class="secondary-tabs"><li><a class="tab icon-heart" href="http://freemarker.org/contribute.html" title="Contribute"><span>Contribute</span></a></li><li><a class="tab icon-bug" href="https://sourceforge.net/p/freemarker/bugs/new/" title="Report a Bug"><span>Report a Bug</span></a></li><li><a class="tab icon-download" href="http://freemarker.org/freemarkerdownload.html" title="Download"><span>Download</span></a></li></ul></div></div><div class="header-bottom-bg"><div class="site-width search-row"><a href="toc.html" class="navigation-header">Manual</a><div class="navigation-header"></div></div><div class="site-width breadcrumb-row"><ul class="breadcrumb" itemscope itemtype="http://schema.org/BreadcrumbList"><li class="step-0" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="toc.html"><span itemprop="name">FreeMarker 手册</span></a></li><li class="step-1" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="dgui.html"><span itemprop="name">模板开发指南</span></a></li><li class="step-2" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="dgui_template.html"><span itemprop="name">模板</span></a></li><li class="step-3" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="dgui_template_valueinsertion.html"><span itemprop="name">插值</span></a></li></ul><div class="bookmarks" title="Bookmarks"><span class="sr-only">Bookmarks:</span><ul class="bookmark-list"><li><a href="alphaidx.html">Alpha. index</a></li><li><a href="gloss.html">Glossary</a></li><li><a href="dgui_template_exp.html#exp_cheatsheet">Expressions</a></li><li><a href="ref_builtins_alphaidx.html">?builtins</a></li><li><a href="ref_directive_alphaidx.html">#directives</a></li><li><a href="ref_specvar.html">.spec_vars</a></li><li><a href="app_faq.html">FAQ</a></li></ul></div></div></div> <div class="main-content site-width">
<div class="content-wrapper">
<div id="table-of-contents-wrapper" class="col-left">
<script>var breadcrumb = ["FreeMarker 手册","模板开发指南","模板","插值"];</script>
<script src="toc.js"></script>
<script src="docgen-resources/main.min.js"></script>
</div>
<div class="col-right"><div class="page-content"><div class="page-title"><div class="pagers top"><a class="paging-arrow previous" href="dgui_template_exp.html"><span>Previous</span></a><a class="paging-arrow next" href="dgui_misc.html"><span>Next</span></a></div><div class="title-wrapper">
<h1 class="content-header header-section1" id="dgui_template_valueinsertion" itemprop="headline">插值</h1>
</div></div><div class="page-menu">
<div class="page-menu-title">Page Contents</div>
<ul><li><a class="page-menu-link" href="#autoid_14" data-menu-target="autoid_14">概览</a></li><li><a class="page-menu-link" href="#autoid_15" data-menu-target="autoid_15">字符串插入指南：不要忘了转义！</a></li><li><a class="page-menu-link" href="#autoid_16" data-menu-target="autoid_16">数字插入指南</a></li><li><a class="page-menu-link" href="#dgui_template_valueinserion_universal_date" data-menu-target="dgui_template_valueinserion_universal_date">日期/时间插入指南</a></li><li><a class="page-menu-link" href="#autoid_17" data-menu-target="autoid_17">布尔值插入指南</a></li><li><a class="page-menu-link" href="#autoid_18" data-menu-target="autoid_18">精确的转换规则</a></li></ul> </div>
<h2 class="content-header header-section2" id="autoid_14">概览</h2>
<p>插值的使用格式是：
<code class="inline-code">${<em class="code-color">expression</em>}</code>，这里的
<code class="inline-code"><em class="code-color">expression</em></code>
可以是所有种类的表达式(比如 <code class="inline-code">${100 + x}</code>)。</p>
<p>插值是用来给 <code class="inline-code"><em class="code-color">表达式</em></code>
插入具体值然后转换为文本(字符串)。插值仅仅可以在两种位置使用：在 <a href="dgui_template_overallstructure.html"><span class="marked-text">文本</span> 区</a> (比如
<code class="inline-code"><h1>Hello ${name}!</h1></code>) 和 <a href="dgui_template_exp.html#dgui_template_exp_stringop_interpolation">字符串表达式</a>
(比如 <code class="inline-code"><#include "/footer/${company}.html"></code>)中。</p>
<p>表达式的结果必须是字符串，数字或者日期/时间/日期-时间值，
因为(默认是这样)仅仅这些值可以被插值自动转换为字符串。其它类型的值
(比如布尔值，序列)必须 "手动地" 转换成字符串(后续会有一些建议)，
否则就会发生错误，中止模板执行。</p>
<div class="callout warning">
<strong class="callout-label">Warning!</strong>
<p>一个常犯的错误是在不能使用插值的地方使用了它。
插值 <em>仅仅</em> 在 <a href="dgui_template_overallstructure.html"><span class="marked-text">文本</span> 区</a> (比如
<code class="inline-code"><h1>Hello ${name}!</h1></code>) 和 <a href="dgui_template_exp.html#dgui_template_exp_direct_string">字符串</a>
(比如 <code class="inline-code"><#include "/footer/${company}.html"></code>)中起作用。
典型的 <em>错误</em> 使用是 <code class="inline-code"><#if
${big}>...</#if></code>，这是语法上的错误。
只要简单写为 <code class="inline-code"><#if big>...</#if></code>即可。
而且 <code class="inline-code"><#if "${big}">...</#if></code> 也是
<em>错误</em>的，因为这样参数就是字符串类型了，
但是 <code class="inline-code">if</code> 指令的参数要求是布尔值，所以就会发生运行时错误。</p>
</div>
<h2 class="content-header header-section2" id="autoid_15">字符串插入指南：不要忘了转义！</h2>
<p>如果插值在 <a href="dgui_template_overallstructure.html"><span class="marked-text">文本</span> 区</a> (也就是说，不在 <a href="dgui_template_exp.html#dgui_template_exp_stringop_interpolation">字符串表达式</a> 中)，如果 <a href="ref_directive_escape.html#ref.directive.escape"><code>escape</code>
指令</a> 起作用了，那么将被插入的字符串会被自动转义。如果要生成HTML，
那么强烈建议你利用它来阻止跨站脚本攻击和非格式良好的HTML页面。这里有一个示例：</p>
<div class="code-wrapper"><pre class="code-block code-template"><strong><#escape x as x?html></strong>
...
<p>Title: <strong>${</strong>book.title<strong>}</strong></p>
<p>Description: <strong><#noescape>${</strong>book.description<strong>}</#noescape></strong></p>
<h2>Comments:</h2>
<#list comments as comment>
<div class="comment">
<strong>${</strong>comment<strong>}</strong>
</div>
</#list>
...
<strong></#escape></strong></pre></div>
<p>这个示例展示了当生成HTML时，最好将完整的模板放入到
<code class="inline-code">escape</code> 指令中。那么，如果
<code class="inline-code">book.title</code> 包含 <code class="inline-code">&</code>，
在输出中它就会被替换成 <code class="inline-code">&amp;</code>，
而页面还会保持为格式良好的HTML。如果用户注释包含如
<code class="inline-code"><iframe></code>(或其它元素)的标记，那么就会被转义成
<code class="inline-code">&lt;iframe&gt;</code> 的样子，使他们没有任何有害点。
但有时在数据模型中真的需要HTML，我们假设上面的
<code class="inline-code">book.description</code> 在数据库中的存储是HTML格式的，
那么此时不得不使用 <code class="inline-code">noescape</code> 来抵消
<code class="inline-code">escape</code> 的转义，不包含 <code class="inline-code">escape</code>，
模板就会像这样了：</p>
<div class="code-wrapper"><pre class="code-block code-template"> ...
<p>Title: ${book.title?html}</p>
<p>Description: ${book.description}</p>
<h2>Comments:</h2>
<#list comments as comment>
<div class="comment">
${comment?html}
</div>
</#list>
...</pre></div>
<p>这和之前示例的效果是一样的， 但是这里可能会忘记
<code class="inline-code">?html</code> 等内建函数，那么这就会有安全上的问题了。
在之前的示例中，你可能忘记 <code class="inline-code">noescape</code> 等内建函数，
也会造成不良的输出，但是起码是没有安全隐患的。</p>
<h2 class="content-header header-section2" id="autoid_16">数字插入指南</h2>
<p>如果表达式是数字类型，那么根据数字的默认格式，
数值将会转换成字符串。这也许会包含最大的小数，
数字分组和相似处理的问题。通常程序员应该设置默认的数字格式；
而模板设计者不需要处理它(但是可以使用 <code class="inline-code">number_format</code>
来设置；详情请参考 <a href="ref_directive_setting.html">
<code>setting</code> 指令部分的文档</a>)。
可以使用<a href="ref_builtins_number.html#ref_builtin_string_for_number">
内建函数 <code>string</code> </a>
为一个插值来重写默认数值格式。</p>
<p>小数的分隔符通常(其他类似的符号也是这样，如分组符号)
是根据所在地的标准(语言，国家)来确定的，这也需要程序员来设置。例如这个模板：</p>
<div class="code-wrapper"><pre class="code-block code-template">${1.5}</pre></div>
<p>如果当前本地化设置为英语时，将会输出：</p>
<div class="code-wrapper"><pre class="code-block code-output">1.5</pre></div>
<p>而当前地区为德国时，将会输出：</p>
<div class="code-wrapper"><pre class="code-block code-output">1,5</pre></div>
<p>这是因为德国人使用逗号作为小数点。</p>
<div class="callout warning">
<strong class="callout-label">Warning!</strong>
<p>可以看出，插值的打印都是给用户看的(至少是这样的)，
而不是给''计算机''的。有时候这样并不好，比如要打印数据库记录的主键，
用来作为URL中的一部分或HTML表单的隐藏域来作为提交内容，
或者要打印CSS/JavaScript中的数字，因为这些值都是给计算机程序去识别的而不是给用户看的。
很多程序对数字格式的要求非常严格，它们只能理解一部分简单的美式数字格式。那样的话，
可以使用内建函数<a href="ref_builtins_number.html#ref_builtin_c"><code>c</code></a>
（代表''计算机''）来解决这个问题，比如：</p>
<div class="code-wrapper"><pre class="code-block code-template"><a href="/shop/productdetails?id=${product.id?c}">Details...</a></pre></div>
</div>
<h2 class="content-header header-section2" id="dgui_template_valueinserion_universal_date">日期/时间插入指南</h2>
<p>如果表达式的值是时间日期类型，那么日期中的数字将会按照默认格式来转换成文本。
通常程序员应该设置默认格式，而页面设计者无需处理这一点。(如果需要的话，
<a href="ref_directive_setting.html#topic.dateTimeFormatSettings">可以参考
<code>date_format</code>， <code>time_format</code> 和
<code>datetime_format</code> 的 </a>
<a href="ref_directive_setting.html#ref.directive.setting"><code>setting</code>
指令</a>设置)。当然，也可以使用
<a href="ref_builtins_date.html#ref_builtin_string_for_date">内建函数<code>string</code></a>
来覆盖单独插值的默认格式。</p>
<div class="callout warning">
<strong class="callout-label">Warning!</strong>
<p>为了将日期显示成文本，FreeMarker 必须知道日期中的哪一部分在使用，也就是说，
如果仅仅日期部分(年，月，日)使用或仅仅时间部分(时，分，秒，毫秒)使用或两部分都用。
不幸的是，由于Java平台技术的限制，自动探测一些变量是不现实的。
这时可以找程序员对数据模型中可能出问题的变量进行处理。
如果找出时间日期变量的哪部分在使用是不太可能的话，就必须帮助 FreeMarker 使用内建函数
<a href="ref_builtins_date.html#ref_builtin_date_datetype"><code>date</code>，
<code>time</code> 和 <code>datetime</code></a> 来识别
(比如 <code class="inline-code">${lastUpdated?datetime}</code> )，否则就会出现错误停止执行。</p>
</div>
<h2 class="content-header header-section2" id="autoid_17">布尔值插入指南</h2>
<p>若要使用插值方式来打印布尔值会引起错误，中止模板的执行。
例如： <code class="inline-code">${a == 2}</code> 就会引起错误，
它不会打印''true''或其他内容。这是因为没有全局来表示布尔值的好方法
(有时想输出yes/no，但有时是想要enabled/disabled,on/off等等)。</p>
<p>我们可以使用内建函数 <a href="ref_builtins_boolean.html#ref_builtin_string_for_boolean"><code>?string</code></a>
来将布尔值转换为字符串形式。比如输出变量"married"的值(假设它是一个布尔值)，
那么可以这么来写: <code class="inline-code">${married?string("yes", "no")}</code>。</p>
<p>可以使用设置参数 <code class="inline-code">boolean_format</code>
来为 FreeMarker 配置默认的布尔值格式。那么，直接编写
<code class="inline-code">${married}</code> 这样的代码就不会有问题了。但在很多应用程序中，
这样的做法是不推荐使用的，因为布尔值在不同的地方就应该呈现出不同的格式，
同时将格式留作默认值也可以认为是疏忽，因为这可能导致错误产生。</p>
<p>当想生成JavaScript或其它计算机语言代码部分时，那么可以考虑使用
<code class="inline-code">${someBoolean?c}</code>("c" 代表计算机)来输出布尔值true/false。
(请记住 <code class="inline-code">?c</code> 也可以用来输出给计算机看的数字。)</p>
<h2 class="content-header header-section2" id="autoid_18">精确的转换规则</h2>
<p>对于有兴趣研究的人，表达式的值转换为字符串(仍受限于转义)
精确的规则就是下面这些，以这个顺序进行：</p>
<div class="orderedlist"><ol type="1">
<li>
<p>如果这个值是数字，那么它会按照指定的 <code class="inline-code">number_format</code>
设置规则来转换为字符串。所以这些转换通常是对用户进行的，而不是对计算机。</p>
</li>
<li>
<p>如果这个值是日期，时间或时间日期类型的一种，那么它们会按照指定的
<code class="inline-code">date_format</code>， <code class="inline-code">time_format</code>
或者 <code class="inline-code">datetime_format</code> 设置规则来转换为字符串。
如果它不能被探测出来是哪种日期类型(日期或时间或日期时间)时，就会发生错误了。</p>
</li>
<li>
<p>如果值本来就是字符串类型的，不需要转换。</p>
</li>
<li>
<p>如果 FreeMarker 引擎在传统兼容模式下：</p>
<div class="orderedlist"><ol type="1">
<li>
<p>如果值是布尔类型，true值就转换成"true"，false值将会转换为空字符串。</p>
</li>
<li>
<p>如果表达式未被定义(<code class="inline-code">null</code> 或者变量未定义)，
那么就转换为空字符串。</p>
</li>
<li>
<p>否则就会发生错误中止模板执行。</p>
</li>
</ol></div>
</li>
<li>
<p>否则就会发生错误中止模板执行。</p>
</li>
</ol></div>
<div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="dgui_template_exp.html"><span>Previous</span></a><a class="paging-arrow next" href="dgui_misc.html"><span>Next</span></a></div></div></div></div> </div>
</div>
<div class="site-footer"><div class="site-width"><div class="footer-top"><div class="col-left sitemap"><div class="column"><h3 class="column-header">Overview</h3><ul><li><a href="http://freemarker.org/index.html">What is FreeMarker?</a></li><li><a href="http://freemarker.org/freemarkerdownload.html">Download</a></li><li><a href="app_versions.html">Version history</a></li><li><a href="http://freemarker.org/history.html">About us</a></li><li><a itemprop="license" href="app_license.html">License</a></li></ul></div><div class="column"><h3 class="column-header">Handy stuff</h3><ul><li><a href="http://freemarker-online.kenshoo.com/">Try template online</a></li><li><a href="dgui_template_exp.html#exp_cheatsheet">Expressions cheatsheet</a></li><li><a href="ref_directive_alphaidx.html">#directives</a></li><li><a href="ref_builtins_alphaidx.html">?built_ins</a></li><li><a href="ref_specvar.html">.special_vars</a></li></ul></div><div class="column"><h3 class="column-header">Community</h3><ul><li><a href="https://github.com/nanlei/freemarker/tree/manual-zh-2.3-gae/src/manual">Chinese Manual on Github</a></li><li><a href="https://github.com/freemarker/freemarker">FreeMarker on Github</a></li><li><a href="https://twitter.com/freemarker">Follow us on Twitter</a></li><li><a href="https://sourceforge.net/p/freemarker/bugs/new/">Report a bug</a></li><li><a href="http://stackoverflow.com/questions/ask?tags=freemarker">Ask a question</a></li><li><a href="http://freemarker.org/mailing-lists.html">Mailing lists</a></li></ul></div></div><div class="col-right"><ul class="social-icons"><li><a class="github" href="https://github.com/freemarker/freemarker">Github</a></li><li><a class="twitter" href="https://twitter.com/freemarker">Twitter</a></li><li><a class="stack-overflow" href="http://stackoverflow.com/questions/ask?tags=freemarker">Stack Overflow</a></li></ul><a class="xxe" href="http://www.xmlmind.com/xmleditor/" rel="nofollow" title="Edited with XMLMind XML Editor"><span>Edited with XMLMind XML Editor</span></a></div></div><div class="footer-bottom"><p><span class="generated-for-product">Generated for: Freemarker 2.3.23</span><span class="last-updated"> Last generated:
<time itemprop="dateModified" datetime="2015-09-18T14:38:51Z" title="Friday, September 18, 2015 2:38:51 PM GMT">2015-09-18 14:38:51 GMT</time></span></p> <p class="copyright">
© <span itemprop="copyrightYear">1999</span>–2015
<a itemtype="http://schema.org/Organization" itemprop="copyrightHolder" href="http://freemarker.org">The FreeMarker Project</a>. All rights reserved. </p>
</div></div></div></body>
</html>