-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathpgui_misc_charset.html
132 lines (106 loc) · 13.4 KB
/
pgui_misc_charset.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
<!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/pgui_misc_charset.html">
<link rel="canoical" href="http://freemarker.org/docs/pgui_misc_charset.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="pgui.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="pgui_misc.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="pgui_misc_charset.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="pgui_misc_var.html"><span>Previous</span></a><a class="paging-arrow next" href="pgui_misc_multithreading.html"><span>Next</span></a></div><div class="title-wrapper">
<h1 class="content-header header-section1" id="pgui_misc_charset" 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_45" data-menu-target="autoid_45">输入的字符集</a></li><li><a class="page-menu-link" href="#autoid_46" data-menu-target="autoid_46">输出的字符集</a></li></ul> </div><p>像其它大多数的Java应用程序一样，FreeMarker使用 "<a href="gloss.html#gloss.unicode">UNICODE</a> 文本"(UTF-16)来工作。
不过，也有必须处理 <a href="gloss.html#gloss.charset">字符集</a> 的情况，
因为它不得不和外界交换数据，这就会使用到很多字符集。</p>
<h2 class="content-header header-section2" id="autoid_45">输入的字符集</h2>
<p>当 FreeMarker 要加载模板文件(或没有解析的文本文件)时，
那就必须要知道文件使用的字符集，因为文件的存储是原生的字节序列。
可以使用 <code class="inline-code">encoding</code> <a href="pgui_config_settings.html">配置</a> 来确定字符集。
这个配置项只在 FreeMarker 使用 <code class="inline-code">Configuration</code>
对象的 <code class="inline-code">getTemplate</code>
方法加载模板(解析过的或没有解析过的)时起作用。请注意 <a href="ref_directive_include.html#ref.directive.include"><code>include</code> 指令 </a>
在内部也使用了这个方法，所以 <code class="inline-code">encoding</code>
的值对一个已经加载的模板，而且如果这个模板包含 <code class="inline-code">include</code>
指令的调用来说很重要。</p>
<p><code class="inline-code">encoding</code> 配置的getter和setter方法在第一个(配置)层面很特殊。
getter方法猜想返回值是基于 <code class="inline-code">Locale</code>(本地化，译者注)传递的参数；
它在地图区域编码表(称为编码地图)中查询编码，如果没有找到该区域，就返回默认编码。
可以使用配置对象的 <code class="inline-code">setEncoding(Locale locale, String encoding)</code>
方法来填充编码表；编码表初始化时是空的。默认的初始编码是系统属性
<code class="inline-code">file.encoding</code> 的值，但是可以通过
<code class="inline-code">setDefaultEncoding</code> 方法来设置一个不同的默认值，而不是依赖它。
对于新项目来说，默认的编码设置就是 <code class="inline-code">utf-8</code>。</p>
<p>也可以在模板层或运行环境层(当指定编码值作为 <code class="inline-code">getTemplate</code>
方法的参数时，应该在模板层覆盖 <code class="inline-code">encoding</code> 设置)直接给定值来覆盖
<code class="inline-code">encoding</code> 的设置。如果不覆盖它，那么 <code class="inline-code">locale</code>
设置的有效值将会是 <code class="inline-code">configuration.getEncoding(Locale)</code> 方法的返回值。</p>
<p>而且，代替这种基于字符集猜测的机制，也可以在模板文件中使用
<a href="ref_directive_ftl.html#ref.directive.ftl"><a href="ref_directive_ftl.html#ref.directive.ftl"><code>ftl</code></a>
指令</a>, 比如 <code class="inline-code"><#ftl
encoding="utf-8"></code> 来指定特定的字符集。</p>
<p>请注意，模板使用的字符集和模板生成的输出内容的字符集是独立的
(除非包含 FreeMarker 的软件故意将设置输出内容的字符集和模板字符集设置成相同的)。</p>
<h2 class="content-header header-section2" id="autoid_46">输出的字符集</h2>
<div class="callout note">
<strong class="callout-label">Note:</strong>
<p><code class="inline-code">output_encoding</code> 设置/参数和 <a href="ref_builtins_string.html#ref_builtin_url">内建函数<code>url</code></a>
从FreeMarker 2.3.1版本开始才可以使用，而在2.3以前的版本中是不存在的。</p>
</div>
<p>原则上，FreeMarker 不处理输出内容的字符集问题，
因为 FreeMarker 将输出内容都写入了 <code class="inline-code">java.io.Writer</code>
对象中。而 <code class="inline-code">Writer</code>
对象是由封装了 FreeMarker(比如Web应用框架) 的软件生成的，
那么输出内容的字符集就是由封装软件来控制的。而FreeMarker有一个称为
<code class="inline-code">output_encoding</code>(开始于 FreeMarker 2.3.1 版本之后)的设置。
封装软件应该使用这个设置(<code class="inline-code">Writer</code>对象使用的字符集)
来通知 FreeMarker 在输出中(否则 FreeMarker 不能找到它)使用哪种字符集。
有一些新的特性，如<a href="ref_builtins_string.html#ref_builtin_url">内建函数<code>url</code></a>，<a href="ref_specvar.html">特殊变量<code>output_encoding</code></a>
也利用这个信息。因此，如果封装软件没有设置字符集这个信息，
那么 FreeMarker 需要知道输出字符集的特性就不能被利用了。</p>
<p>如果你使用 FreeMarker 来编写软件，
你也许想知道在输出内容中到底选择了哪种字符集。
当然这取决于运行 FreeMarker 输出内容的计算机本身，
但是如果用户对这个问题可以变通，
那么通用的实践是使用模板文件的字符集作为输出的字符集，或者使用UTF-8。
通常使用UTF-8是最佳的实践，因为任意的文本可能来自数据模型，
那就可能包含不能被模板字符集所编码的字符。</p>
<p>如果使用了
<code class="inline-code">Template.createProcessingEnvironment(<em class="code-color">...</em>)</code>
和 <code class="inline-code">Environment.process(<em class="code-color">...</em>)</code> 方法来代替
<code class="inline-code">Template.process(<em class="code-color">...</em>)</code> 方法，
FreeMarker 的设置可以对任意独立执行的模板进行。
因此，你可以对每个独立执行的模板设置 <code class="inline-code">output_encoding</code> 信息：</p>
<div class="code-wrapper"><pre class="code-block code-unspecified">Writer w = new OutputStreamWriter(out, outputCharset);
Environment env = template.createProcessingEnvironment(dataModel, w);
env.setOutputEncoding(outputCharset);
env.process();</pre></div>
<div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="pgui_misc_var.html"><span>Previous</span></a><a class="paging-arrow next" href="pgui_misc_multithreading.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>