文档

§为模板引擎添加对自定义格式的支持

内置模板引擎支持常见的模板格式（HTML、XML 等），但如果需要，您可以轻松地添加对您自己的格式的支持。本页总结了支持自定义格式的步骤。

§模板处理过程概述

模板引擎通过追加模板的静态和动态内容部分来构建其结果。例如，考虑以下模板

foo @bar baz

它由两个静态部分（foo  和  baz）和一个动态部分（bar）组成。模板引擎将这些部分连接在一起以构建其结果。实际上，为了防止跨站点脚本攻击，bar 的值可以在连接到结果的其余部分之前进行转义。此转义过程特定于每种格式：例如，在 HTML 的情况下，您希望将“<”转换为“&lt;”。

模板引擎如何知道哪种格式对应于模板文件？它查看其扩展名：例如，如果它以 .scala.html 结尾，它将 HTML 格式与该文件关联。

总之，要支持您自己的模板格式，您需要执行以下步骤

§实现格式

实现play.twirl.api.Format<A>接口，该接口具有方法A raw(String text)和A escape(String text)，它们将分别用于集成静态和动态模板部分。

格式的类型参数A定义了模板渲染的结果类型，例如，对于 HTML 模板，Html。此类型必须是play.twirl.api.Appendable<A>特性的子类型，该特性定义了如何将部分连接在一起。

为了方便起见，Play 提供了一个play.twirl.api.BufferedContent<A>抽象类，该类使用StringBuilder来构建其结果，并实现了play.twirl.api.Appendable<A>，并且实现了play.twirl.api.Content接口，以便 Play 知道如何将其序列化为 HTTP 响应主体。

简而言之，您需要编写两个类：一个定义结果（实现play.twirl.api.Appendable<A>），另一个定义文本集成过程（实现play.twirl.api.Format<A>）。例如，以下是 HTML 格式的定义方式

public class Html extends BufferedContent<Html> {
  public Html(StringBuilder buffer) {
    super(buffer);
  }
  String contentType() {
    return "text/html";
  }
}

public class HtmlFormat implements Format<Html> {
  Html raw(String text: String) { … }
  Html escape(String text) { … }
  public static final HtmlFormat instance = new HtmlFormat(); // The build process needs a static reference to the format (see the next section)
}

§将文件扩展名与格式关联

模板在编译整个应用程序源代码之前，由构建过程编译成.scala文件。TwirlKeys.templateFormats键是类型为Map[String, String]的 sbt 设置，定义了文件扩展名和模板格式之间的映射。例如，如果您希望 Play 使用您自己的 HTML 格式实现，则必须在您的构建文件中编写以下内容，以将.scala.html文件与您的自定义my.HtmlFormat格式关联

TwirlKeys.templateFormats += ("html" -> "my.HtmlFormat.instance")

请注意，箭头右侧包含类型为play.twirl.api.Format<?>的静态值的完全限定名。

下一步： 表单提交和验证

在此文档中发现错误？此页面的源代码可以在 此处找到。在阅读文档指南后，请随时贡献拉取请求。有疑问或建议要分享？转到我们的社区论坛，与社区开始对话。