024_输入输出字符集

1. 像其它大多数的Java应用程序一样, FreeMarker使用"UNICODE文本"(UTF-16)来工作。不过, 也有必须处理字符集的情况, 因为它不得不和外界交换数据, 这就会使用到很多字符集。

2. 输入的字符集

2.1. 当FreeMarker要加载模板文件(或没有解析的文本文件)时, 那就必须要知道文件使用的字符集。可以使用encoding配置来确定字符集。这个配置项只在FreeMarker使用Configuration对象的getTemplate方法加载模板(解析过的或没有解析过的)时起作用。请注意include指令在内部也使用了这个方法。

2.2. encoding配置的getter和setter方法在第一个(配置)层面很特殊。getter方法猜想返回值是基于Locale(本地化)传递的参数; 它在地图区域编码表(称为编码地图)中查询编码, 如果没有找到该区域, 就返回默认编码。可以使用配置对象的setEncoding(Locale locale, String encoding)方法来填充编码表; 编码表初始化时是空的。默认的初始编码是系统属性file.encoding的值, 但是可以通过setDefaultEncoding方法来设置一个不同的默认值, 而不是依赖它。对于新项目来说, 默认的编码设置就是utf-8。

2.3. 也可以在运行环境层直接给定值来覆盖encoding的设置。

2.4. 也可以在模板文件中使用ftl指令, 比如: <#ftl encoding="utf-8">来指定特定的字符集。

2.5. 请注意, 模板使用的字符集和模板生成的输出内容的字符集是独立的。

3. 输出的字符集

3.1. 原则上, FreeMarker不处理输出内容的字符集问题, 因为FreeMarker将输出内容都写入了java.io.Writer对象中。而Writer对象是由封装了FreeMarker(比如Web应用框架)的软件生成的, 那么输出内容的字符集就是由封装软件来控制的。

3.2. 而FreeMarker有一个称为output_encoding的设置。封装软件应该使用这个设置(Writer对象使用的字符集)来通知FreeMarker在输出中(否则FreeMarker不能找到它)使用哪种字符集。

3.3. 有一些新的特性, 如内建函数url, 特殊变量output_encoding也利用这个信息。因此, 如果封装软件没有设置字符集这个信息, 那么FreeMarker需要知道输出字符集的特性就不能被利用了。

3.4. 如果你使用FreeMarker来编写软件, 你也许想知道在输出内容中到底选择了哪种字符集。当然这取决于运行FreeMarker输出内容的计算机本身, 但是如果用户对这个问题可以变通, 那么通用的实践是使用模板文件的字符集作为输出的字符集, 或者使用UTF-8。通常使用UTF-8是最佳的实践。