SpringのThymeleafでエラー表示する方法！フォームバインドとバリデーションを丁寧に解説

画面へのエラー表示：Thymeleaf の th:field とエラー強調表現

先生と生徒の会話形式で理解しよう

生徒

「Springのバリデーションで入力エラーが出たとき、画面にどうやって表示すればいいんですか？」

先生

「それにはThymeleafのth:fieldやth:errorsを使いますよ。エラーの強調もBootstrapと組み合わせれば簡単です。」

生徒

「じゃあ、エラーが出た項目だけ赤くして、メッセージも出せるってことですか？」

先生

「その通りです。基本から順番に見ていきましょう！」

1. Springのフォームバインドとバリデーションの基本

Spring MVCでは、HTMLフォームからの入力値をJavaのオブジェクトにバインドできます。そして、JSR-303のバリデーションを組み合わせることで、入力チェックも自動で行えます。

まずはフォームクラスにバリデーションアノテーションを追加しましょう。


public class UserForm {

    @NotBlank(message = "ユーザー名を入力してください")
    private String username;

    @Email(message = "メールアドレスの形式が正しくありません")
    private String email;

    // getter / setter
}

このようにすることで、入力が空だったり形式が間違っていた場合に、エラーが発生します。

2. コントローラーでエラー処理を受け取る

コントローラーでは、@ValidatedとBindingResultを使って、バリデーション結果を受け取ります。


@PostMapping("/register")
public String register(@ModelAttribute("form") @Validated UserForm form, BindingResult result) {
    if (result.hasErrors()) {
        return "form";
    }
    return "success";
}

エラーがある場合は再度フォーム画面に戻し、エラーメッセージを表示します。

3. Thymeleafでのエラー表示：th:fieldとth:errors

Thymeleafでは、Springのフォームオブジェクトと連携して、フィールドごとのエラー表示が可能です。フォーム入力欄にはth:fieldを使います。


<form th:action="@{/register}" th:object="${form}" method="post">
    <div class="mb-3">
        <label for="username" class="form-label">ユーザー名</label>
        <input type="text" th:field="*{username}" class="form-control" />
        <div th:if="${#fields.hasErrors('username')}" th:errors="*{username}" class="text-danger"></div>
    </div>

    <div class="mb-3">
        <label for="email" class="form-label">メールアドレス</label>
        <input type="email" th:field="*{email}" class="form-control" />
        <div th:if="${#fields.hasErrors('email')}" th:errors="*{email}" class="text-danger"></div>
    </div>

    <button type="submit" class="btn btn-primary">登録</button>
</form>

th:fieldは、Springのバインド情報に従ってnameやid属性も自動設定してくれる便利な属性です。

4. エラーのある入力欄を強調表示する

エラーがある項目を視覚的にわかりやすくするためには、Bootstrapのis-invalidクラスを使います。


<input type="text" 
       th:field="*{username}" 
       th:classappend="${#fields.hasErrors('username')} ? ' is-invalid'" 
       class="form-control" />

th:classappendを使えば、条件に応じてクラスを追加できるため、エラーがあるときだけis-invalidが付与されます。

5. `th:errors`でメッセージを表示する方法

5. th:errorsでメッセージを表示する方法

th:errorsは、フィールドごとに発生したエラーメッセージを表示するための属性です。1つのフィールドに複数の制約をつけている場合でも、自動ですべて表示されます。


<div th:errors="*{email}" class="text-danger"></div>

この要素は、エラーがあるときだけ表示され、なければ出力されません。条件分岐を書かなくても済むので便利です。

6. 全体のエラー表示：フォームレベルのバリデーション

フォーム全体に関するエラー（例：メールアドレスと確認用アドレスが一致しないなど）を表示したい場合は、globalErrorを使います。


<div th:if="${#fields.hasGlobalErrors()}" class="alert alert-danger">
    <ul>
        <li th:each="err : ${#fields.globalErrors()}" th:text="${err}"></li>
    </ul>
</div>

このようにすることで、入力フィールドに紐づかないエラーもユーザーに伝えることができます。