文件

§表單範本輔助程式

Play 提供了多個輔助程式，以協助您在 HTML 範本中呈現表單欄位。

§建立 <form> 標籤

第一個輔助函式建立 <form> 標籤。這是一個相當簡單的輔助函式，會自動根據你傳入的反向路由設定 action 和 method 標籤參數

@helper.form(action = routes.Application.submit) {

}

你也可以傳入一組額外的參數，這些參數會加入到產生的 HTML 中

@helper.form(action = routes.Application.submit, Symbol("id") -> "myForm") {

}

§呈現 <input> 元素

views.html.helper 套件中有幾個輸入輔助函式。你可以提供表單欄位給它們，它們會顯示對應的 HTML 表單控制項，包含已填入的值、約束和錯誤

@(myForm: play.data.Form[User])(implicit messages: play.i18n.Messages)

@helper.form(action = routes.Application.submit) {

    @helper.inputText(myForm("email"))

    @helper.inputPassword(myForm("password"))

}

和 form 輔助函式一樣，你可以指定一組額外的參數，這些參數會加入到產生的 HTML 中

@helper.inputText(myForm("email"), Symbol("id") -> "email", Symbol("size") -> 30)

注意：所有額外的參數都會加入到產生的 HTML 中，但名稱以 _ 字元開頭的參數除外。以底線開頭的參數保留給欄位建構函式的參數（我們稍後會看到）。

§自行處理 HTML 輸入建立

還有一個更通用的 input 輔助函式，讓你編寫所需的 HTML 結果

@helper.input(myForm("email")) { (id, name, value, args) =>
    <input type="date" name="@name" id="@id" @toHtmlArgs(args)>
}

§欄位建構函式

已呈現的欄位不只包含一個 <input> 標籤，也可能需要一個 <label> 標籤和一堆其他標籤，讓你的 CSS 架構用來裝飾欄位。

所有輸入輔助函式都採用一個隱含的 FieldConstructor 來處理這部分。預設的建構函式（如果範圍內沒有其他欄位建構函式可用時使用），會產生類似這樣的 HTML

<dl class="error" id="email_field">
    <dt><label for="email">Email:</label></dt>
    <dd><input type="text" name="email" id="email" value=""></dd>
    <dd class="error">This field is required!</dd>
    <dd class="error">Another error</dd>
    <dd class="info">Required</dd>
    <dd class="info">Another constraint</dd>
</dl>

此預設欄位建構函式支援您可以在輸入輔助參數中傳遞的其他選項

'_label -> "Custom label"
'_id -> "idForTheTopDlElement"
'_help -> "Custom help"
'_showConstraints -> false
'_error -> "Force an error"
'_showErrors -> false

§撰寫您自己的欄位建構函式

您通常需要撰寫您自己的欄位建構函式。從撰寫範本開始，如下所示

@(elements: helper.FieldElements)

<div class="@if(elements.hasErrors) {error}">
<label for="@elements.id">@elements.label</label>
<div class="input">
    @elements.input
    <span class="errors">@elements.errors.mkString(", ")</span>
    <span class="help">@elements.infos.mkString(", ")</span>
</div>
</div>

將其儲存在 views/ 中，並將名稱命名為 myFieldConstructorTemplate.scala.html

注意：這只是一個範例。您可以依需要讓它變得更複雜。您也可以使用 @elements.field 存取原始欄位。

現在使用下列方式在某處建立 FieldConstructor

@implicitField: FieldConstructor = @{ FieldConstructor(myFieldConstructorTemplate.f) }

@inputText(myForm("email"))

§處理重複值

最後一個輔助函式讓為重複值產生輸入變得更簡單。假設您有這種類型的表單定義

public class UserForm {

  private String name;
  private List<String> emails;

  public void setName(String name) {
    this.name = name;
  }

  public String getName() {
    return name;
  }

  public void setEmails(List<String> emails) {
    this.emails = emails;
  }

  public List<String> getEmails() {
    return emails;
  }
}

當您使用像這樣的重複資料時，有兩種替代方案可以在 HTTP 要求中傳送表單值。首先，您可以使用空括號對為參數加上字尾，例如「emails[]」。然後，此參數可以用標準方式重複，例如 http://foo.com/request?emails[][email protected]&emails[][email protected]。或者，客戶端可以使用陣列下標明確地將參數命名為唯一名稱，例如 emails[0]、emails[1]、emails[2]，依此類推。此方法也讓您可以維護輸入順序。

現在，您必須為 emails 欄位產生與表單包含的數量一樣多的輸入。只要使用 repeat 輔助函式即可

@helper.inputText(userForm("name"))

@helper.repeat(userForm("emails"), min = 1) { emailField =>

    @helper.inputText(emailField)

}

使用 min 參數顯示最小數量的欄位，即使對應的表單資料為空。

如果您想存取欄位的索引，您可以改用 repeatWithIndex 輔助函式

@helper.repeatWithIndex(userForm("emails"), min = 1) { (emailField, index) =>

    @helper.inputText(emailField, Symbol("_label") -> ("email #" + index))

}

下一步：使用 Json

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