Thymeleaf th:checkedで条件によってチェックを設定する例

新人と先輩の会話形式で理解しよう

新人

「先輩、Thymeleafでチェックボックスに条件を付けてチェックを入れる方法ってありますか？」

先輩

「良い質問だね。Thymeleafでは、th:checkedという属性を使って、特定の条件が真（true）のときだけチェックを入れることができるんだ。」

新人

「なるほど。じゃあ、Springのコントローラとどう連携させるんですか？」

先輩

「それは後で具体的に見ていこう。まずは、Thymeleafとは何かから確認していこう。」

1. Thymeleafとは？

Thymeleaf（タイムリーフ）は、Spring Frameworkでよく使われるテンプレートエンジンの一つです。テンプレートエンジンとは、サーバー側のデータをHTMLテンプレートに埋め込んで、動的にWebページを生成する仕組みのことを指します。Thymeleafを使うと、HTML内で変数を展開したり、条件分岐や繰り返し処理を記述することができます。

例えば、次のようにth:textを使うと、サーバー側で用意した文字列をHTMLに表示することができます。


<p th:text="${message}"></p>

このようにThymeleafでは、通常のHTML構文を保ちながら、Springのデータを動的に表示できるのが特徴です。ブラウザで開いても崩れない「ナチュラルテンプレート」として動作するのも魅力です。

今回の記事では、特にチェックボックスを動的に制御する方法に焦点を当てて解説していきます。

2. th:checked属性とは？

th:checked属性は、ThymeleafでチェックボックスのON/OFFを条件によって制御したいときに使用します。通常のHTMLでは次のように記述します。


<input type="checkbox" checked>

この場合は常にチェックが入った状態で表示されますが、Thymeleafを使えば、サーバー側の値によって動的にチェックを切り替えることができます。例えば、次のような記述です。


<input type="checkbox" th:checked="${user.active}">

このコードでは、user.activeがtrueのときにチェックが入り、falseのときはチェックが外れた状態で表示されます。つまり、Springのモデル属性の値に応じてチェックの状態が自動的に反映される仕組みです。

このth:checked属性を使うことで、条件分岐をHTML内に直接書かなくても済むため、可読性の高いテンプレートを保つことができます。

開発環境の前提

今回の記事のサンプルは、次のような前提条件で作成しています。

開発環境：pleiades を使用
ビルドツール：Gradle を使用（Mavenは使用しない）
プロジェクト作成：pleiadesの「新規Springプロジェクト」から作成し、依存関係もチェックボックスで追加
コントローラ：@Controllerを使用（@RestControllerは使用しない）
不要な外部ライブラリ（Bootstrapなど）は使用しない純粋なSpring構成

Spring Bootを使う場合でも同様の構成で動作しますが、ここではGradleを用いた標準的なSpring MVCプロジェクトを前提とします。

チェックボックスの基本構造

Thymeleafでチェックボックスを動的に制御する場合、コントローラ側のJavaコードで値を設定し、それをHTMLテンプレートに反映させます。以下は簡単なコントローラの例です。


@Controller
public class SampleController {

    @GetMapping("/checkbox")
    public String showCheckbox(Model model) {
        User user = new User();
        user.setActive(true);
        model.addAttribute("user", user);
        return "checkbox";
    }
}

この例では、Userクラスのactiveフィールドをtrueに設定しています。その結果、HTML側のth:checkedで参照されたとき、自動的にチェックボックスにチェックが入った状態になります。

HTML側のコードは次のようになります。


<form action="#" method="post">
    <input type="checkbox" th:checked="${user.active}">
    <label>有効ユーザー</label>
</form>

このように、コントローラとThymeleafテンプレートを組み合わせることで、動的にチェック状態を制御することが可能になります。条件によってON/OFFを切り替えたい場合は、boolean型やフラグ変数を使って判定を行います。

3. コントローラ側での値設定方法（Modelへのデータ渡し）

ここからは、ThymeleafとSpringを組み合わせて実際にチェックボックスを動かす方法を見ていきます。まず理解しておきたいのは、チェックボックスのON/OFFを決める「値」がどこから来るかということです。Thymeleafのth:checkedは、Springのコントローラから渡されるModelオブジェクトの中身をもとにして判断します。

たとえば、あるユーザーが「有効」かどうかを表すactiveというフィールドを持つクラスがあるとします。その値をSpringコントローラでセットしておけば、テンプレート側のth:checkedがそれを参照して動的にチェックを反映してくれます。


@Controller
public class UserController {

    @GetMapping("/user/form")
    public String showForm(Model model) {
        User user = new User();
        user.setActive(false); // 初期状態ではチェックを外す
        model.addAttribute("user", user);
        return "user_form";
    }

    @PostMapping("/user/form")
    public String handleSubmit(@ModelAttribute User user) {
        System.out.println("ユーザーの有効状態: " + user.isActive());
        return "result";
    }
}

この例では、@Controllerを使ってコントローラを定義し、Modelを介してUserオブジェクトをビューへ渡しています。Thymeleafのth:checkedは、このuser.activeを参照して動作するため、trueならチェックが入り、falseなら外れる仕組みです。

このように、コントローラのModelを介して値を渡すことで、テンプレートとサーバーサイドの状態を一致させることができます。これはSpring MVCの大きな特徴の一つであり、Thymeleafとの相性が非常に良いポイントでもあります。

4. テンプレート側でのth:checkedの条件指定方法

次に、Thymeleafのテンプレート側での設定方法を詳しく見ていきましょう。th:checkedは、trueやfalseの値をもとにして自動的にチェックの状態を切り替えます。つまり、th:checked="${user.active}"という書き方をすれば、コントローラで設定した値がそのまま反映されます。

条件をさらに細かく制御したい場合は、条件式を使って設定することもできます。たとえば次のような書き方です。


<input type="checkbox" th:checked="${user.role == 'ADMIN'}">

この例では、user.roleがADMINという値を持つときだけチェックがONになります。つまり、Thymeleafではth:checkedに「式」を書くことで、柔軟な条件分岐が可能になります。

また、boolean以外の値でも、比較演算子を使って条件を表現できるため、チェックボックスの制御をデータの内容に応じて細かく行えるのが魅力です。

実際のテンプレートでの例を見てみましょう。


<form action="#" method="post" th:object="${user}">
    <label>
        <input type="checkbox" th:field="*{active}" th:checked="${user.active}">
        有効にする
    </label>
    <button type="submit">送信</button>
</form>

このコードでは、th:fieldを使ってフォーム要素とオブジェクトのフィールドをバインドしつつ、th:checkedで初期状態のON/OFFを制御しています。チェックが入っている状態で送信すると、trueがサーバーに送られます。

このように、ThymeleafではHTMLとSpringのModelを密接に連携させることで、シンプルかつ直感的に条件付きのフォームを構築できるのです。

5. 実際のHTMLフォームとチェックボックスの連携例

最後に、実際にThymeleafのテンプレートとSpringのコントローラを組み合わせた動作例を見てみましょう。pleiades＋Gradleの環境であれば、次のようなコードをそのまま実行して動作を確認できます。


@Controller
public class CheckboxExampleController {

    @GetMapping("/settings")
    public String showSettings(Model model) {
        Setting setting = new Setting();
        setting.setNotificationEnabled(true);
        model.addAttribute("setting", setting);
        return "settings";
    }

    @PostMapping("/settings")
    public String saveSettings(@ModelAttribute Setting setting, Model model) {
        model.addAttribute("result", setting.isNotificationEnabled());
        return "result";
    }
}


<form action="#" method="post" th:object="${setting}">
    <div>
        <input type="checkbox" th:field="*{notificationEnabled}" th:checked="${setting.notificationEnabled}">
        <label>通知を有効にする</label>
    </div>
    <button type="submit">保存</button>
</form>

上記のように、Thymeleafでチェックボックスを扱うときは、th:fieldとth:checkedを組み合わせるのが基本です。これにより、チェックの状態が自動的にSpringのオブジェクトにマッピングされ、送信時には値がtrueまたはfalseとして受け取られます。

また、チェック状態を初期表示で切り替えたい場合は、コントローラ側でtrueかfalseをセットしておけばOKです。条件付きでチェックを入れる場合も、th:checkedを使えば柔軟に対応できます。

例えば、ユーザーが設定画面を開いたときに「通知を有効にする」チェックボックスがオンになっているかどうかを、ユーザー情報の内容に応じて制御できます。これは管理画面や設定ページなど、さまざまなWebアプリでよく使われるパターンです。

このように、Thymeleafのth:checked属性を使うことで、条件によるチェックボックス制御を簡単に実現でき、Spring MVCとの相性も抜群です。pleiades＋Gradleの環境で手軽に動作を確認できるため、テンプレートエンジンの学習にも最適です。

6. th:checkedの注意点（boolean型やnull値を扱う際のポイント）

ここでは、Thymeleaf チェックボックス条件設定を行う際に気をつけたい注意点について詳しく解説します。特に初心者がつまずきやすいのが、boolean型やnull値を扱うときの挙動です。Springのモデルで値がnullの場合、Thymeleafのth:checkedは「false」として解釈されます。そのため、意図しない未チェック状態になることがあります。

例えば、チェックボックスを初期状態でオンにしたいのに、オブジェクト生成時にbooleanが初期化されずnullのままだと、表示時にはチェックが外れた状態になります。これを防ぐには、コントローラ側で明示的に初期値を設定しておくことが重要です。


@Controller
public class CheckedInitController {

    @GetMapping("/init")
    public String showForm(Model model) {
        Setting setting = new Setting();
        // boolean値を必ず初期化
        setting.setNotificationEnabled(false);
        model.addAttribute("setting", setting);
        return "init_form";
    }
}

このように、初期化を怠らないことがポイントです。もしもboolean型をラッパークラスのBooleanとして扱う場合は、nullチェックを明示的に行うことをおすすめします。テンプレート側で条件式を使えば安全に制御できます。


<input type="checkbox" th:checked="${setting.notificationEnabled != null and setting.notificationEnabled}">

この条件式は、「nullでなく、かつtrueのときだけチェックを入れる」という意味になります。こうしておくことで、null値が渡ってもエラーにはならず、安全に動作します。特に実際のアプリケーションでは、フォームバインド時に想定外の値が渡ることもあるため、このような記述でエラーを防ぐことが重要です。

また、フォームの送信後に再表示する際、値が反映されない場合は、コントローラで@ModelAttributeのオブジェクトをそのままテンプレートに返すことを忘れないようにしましょう。これが抜けていると、th:checkedの状態が初期化されてしまうことがあります。

7. 実際のアプリ画面での挙動説明（チェックのON/OFFがどう反映されるか）

では次に、Thymeleaf チェックボックス条件設定が実際の画面でどのように動作するのかを見ていきましょう。pleiades＋Gradle環境でプロジェクトを実行すると、フォームを開いた瞬間にチェックボックスの状態がModelの値によって自動的に決まります。ユーザーがチェックを入れたり外したりして送信すると、その状態がSpringコントローラ側のオブジェクトに反映されます。

たとえば、次のような動作をイメージしてください。最初にtrueをセットしておけば、ページを開いた時点でチェックがONの状態です。そしてユーザーがチェックを外して送信すると、サーバー側ではfalseとして受け取れます。


@PostMapping("/init")
public String handleForm(@ModelAttribute Setting setting, Model model) {
    boolean state = setting.isNotificationEnabled();
    model.addAttribute("currentState", state);
    return "init_result";
}

上記のコードで、stateがtrueなら「チェックON」、falseなら「チェックOFF」として画面に反映できます。Thymeleafではこの値を簡単に再表示できます。


<p th:text="'現在の設定：' + (${currentState} ? 'チェックON' : 'チェックOFF')"></p>

このようにテンプレート内で条件式を記述することで、チェックボックスの状態をそのまま画面に表示できます。実際のアプリでは「設定を保存しました」「チェックを外しました」などのメッセージを表示すると、ユーザーに分かりやすくなります。

ここで注意したいのは、Thymeleafのフォーム送信時にチェックを外すと、そのフィールドが送信データから欠落することです。つまり、未チェックの場合は値そのものがサーバーに渡らないため、予期せぬ挙動を防ぐにはhiddenフィールドを併用する方法があります。


<input type="hidden" name="_notificationEnabled" value="off">
<input type="checkbox" th:field="*{notificationEnabled}">

このように記述しておくと、チェックが外れたときも「off」という値が送られるため、コントローラ側で正しくfalseとして認識されます。これもth:checkedを使うときのよくある落とし穴の一つです。

実際にpleiadesでプロジェクトを実行して確認すると、チェックを外して保存したあと再読み込みした際に、反映された状態が正しく保持されていることがわかるでしょう。初心者の方は、まずこの「状態の往復」が正しく動くことを確認してみてください。

8. よくあるエラーと解決方法（チェックされない・常にONになる場合など）

最後に、th:checked エラー対処としてよくあるトラブルとその解決方法を紹介します。Thymeleafでチェックボックスを扱うとき、思ったように動かないケースがいくつかあります。

まず最も多いのが「チェックが反映されない」というケースです。これは、テンプレート側のバインド指定が間違っていることが多く、th:fieldとth:checkedを両方指定せずに片方だけ記述していると発生します。正しい構成では次のように記述します。


<input type="checkbox" th:field="*{active}" th:checked="${user.active}">

次に多いのが「常にチェックがONになる」パターンです。この場合、boolean値の初期化が正しく行われていないか、条件式の書き方に問題がある可能性があります。特にth:checked="${user.active = true}"のように代入演算子を使ってしまうと、常にtrueが設定されてしまうため、注意が必要です。正しくは比較演算子==を使います。

また、フォーム送信後にチェック状態がリセットされる場合は、コントローラで再度Modelに値を設定し直すことを忘れていないか確認してください。Spring MVCでは、リダイレクト後にModelの情報が消えるため、再表示用の値を再セットする必要があります。

さらに、テンプレート内で条件式をネストしすぎると、式の評価が意図しない結果になることがあります。可能な限りシンプルな式で状態を表現するのがThymeleafのベストプラクティスです。

もし「th:checkedが効かない」場合は、テンプレートがキャッシュされている可能性もあります。開発環境ではspring.thymeleaf.cache=falseを設定しておくと、テンプレート更新が即時反映されてトラブルを防げます。


spring.thymeleaf.cache=false

この設定はapplication.propertiesに記述します。pleiadesのGradleプロジェクトであれば、src/main/resources配下にファイルを作成して設定可能です。これでテンプレート変更のたびに再起動しなくても反映されるようになります。

以上のように、th:checkedを使う際にはbooleanの初期値・Modelの再設定・キャッシュ設定など、いくつかのポイントを押さえておく必要があります。慣れてくると、これらの注意点は自然に理解できるようになりますが、最初は「なぜ動かないのか」を一つずつ確認する姿勢が大切です。

特に、Thymeleaf チェックボックス条件設定は一見シンプルですが、実際の開発では小さな見落としが大きな不具合につながることもあります。今回紹介したエラー対処法を覚えておけば、フォーム入力の信頼性を高め、安定したWebアプリケーションを構築できるでしょう。