文件

§將自訂格式的支援新增至範本引擎

內建範本引擎支援常見的範本格式（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<?> 類型的靜態值的完整限定名稱。

下一步：表單提交和驗證

在此文件檔中發現錯誤？此頁面的原始程式碼可以在 這裡 找到。在閱讀 文件檔指南 後，請隨時提交拉取請求。有問題或建議要分享嗎？請前往 我們的社群論壇，與社群展開對話。