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

新人

「Spring Bootでチェックボックスを使いたいんですが、Thymeleafのth:checkedってどう使うんですか？」

先輩

「th:checkedは、ThymeleafでチェックボックスのON/OFFを動的に制御するための属性なんだ。初心者でもわかるように基本から順に説明していくよ。」

新人

「HTMLのチェックボックスの仕組みもまだ曖昧なので、そこからお願いします！」

先輩

「もちろん！まずはチェックボックスの基本構造から確認しよう。」

1. チェックボックスの基本的なHTML構造と動作

まずはThymeleafを使う前に、チェックボックスの基本的なHTML構造を理解しておきましょう。HTMLでは、<input type="checkbox">を使ってチェックボックスを作成します。


<input type="checkbox" name="agree" value="yes"> 利用規約に同意する

このコードは、「利用規約に同意する」というラベル付きのチェックボックスを表示します。チェックが入っている場合は、サーバーにagree=yesという値が送信されます。

しかし、チェックされていない場合は、その項目はフォーム送信時に送られません。これが初心者がつまずきやすいポイントの一つです。

2. Thymeleafのth:checkedとは？（基本構文と役割）

Thymeleafは、Spring MVCと連携して動的なHTMLテンプレートを生成できるテンプレートエンジンです。チェックボックスの状態をサーバー側の値に応じて制御したい場合、th:checked属性を使います。

たとえば、あるフラグがtrueのときだけチェック状態にしたいときは、以下のように記述します。


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

この例では、user.activeがtrueの場合にチェックがONになり、falseまたはnullの場合にはチェックされません。

実際にSpringの@Controllerと連携させてチェックボックスを制御するには、以下のようなモデル属性が必要です。


@Controller
public class UserController {

    @GetMapping("/form")
    public String showForm(Model model) {
        UserForm form = new UserForm();
        form.setActive(true); // 初期状態でチェックON
        model.addAttribute("user", form);
        return "form";
    }
}

このUserFormクラスは、以下のように定義されていると想定します。


public class UserForm {
    private boolean active;
    public boolean isActive() { return active; }
    public void setActive(boolean active) { this.active = active; }
}

このようにして、Thymeleafのth:checkedを使えば、チェックボックスのON/OFFをJavaの値と連動させて制御できます。

また、チェックボックスの初期状態をオフにしたい場合は、falseをセットするだけで自動的にチェックが外れます。

初心者の方は、th:fieldとの違いに注意しましょう。th:fieldはフォームバインディング全体を扱いますが、th:checkedはチェック状態だけを制御します。

3. 条件によってチェック状態を動的に変える方法

実際の業務では、状況によってチェックボックスの状態を切り替えるケースが多くあります。たとえば、ユーザーの役割に応じてチェック状態を変える、登録済みかどうかで切り替えるなどが挙げられます。

Thymeleafでは、th:checkedに条件式を記述することで、柔軟な制御が可能です。


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

この例では、user.roleが'admin'である場合のみ、チェックボックスがONになります。

複雑な条件式も利用でき、たとえば以下のように複数条件を組み合わせて使うこともできます。


<input type="checkbox" name="subscribed" th:checked="${user != null and user.enabled}">

このようにすることで、userがnullでないかつenabledがtrueのときのみチェックされます。

JavaScriptと連携して動的にチェックを切り替える場合でも、初期状態はth:checkedで制御しておき、動的変更はJSで行います。


<input type="checkbox" id="toggle" th:checked="${user.enabled}">
<button onclick="document.getElementById('toggle').checked = !document.getElementById('toggle').checked;">切り替え</button>

このようにJavaScriptと組み合わせることで、ユーザー操作に応じたインタラクティブなチェックボックス制御が可能となります。

4. モデル属性とth:checkedの連携（@Controllerとの連動）

Thymeleafでth:checkedを活用する際は、@Controllerでモデル属性を適切に設定することが重要です。

以下のように、ユーザー情報をフォームに渡し、その値によってチェック状態を制御します。


@Controller
public class SettingController {

    @GetMapping("/settings")
    public String showSettings(Model model) {
        SettingForm form = new SettingForm();
        form.setNotifyByEmail(true);
        model.addAttribute("settingForm", form);
        return "settings";
    }

    @PostMapping("/settings")
    public String submitSettings(@ModelAttribute SettingForm form, Model model) {
        // 設定を保存する処理
        return "redirect:/settings";
    }
}


public class SettingForm {
    private boolean notifyByEmail;
    public boolean isNotifyByEmail() { return notifyByEmail; }
    public void setNotifyByEmail(boolean notifyByEmail) { this.notifyByEmail = notifyByEmail; }
}

このように、Springの@ControllerでJavaオブジェクトをThymeleafテンプレートに渡し、そのプロパティでth:checkedの状態を制御するのが一般的な実装パターンです。

HTMLテンプレート側では、以下のように記述します。


<form action="#" th:action="@{/settings}" th:object="${settingForm}" method="post">
    <label>
        <input type="checkbox" th:field="*{notifyByEmail}" /> メール通知を受け取る
    </label>
    <button type="submit">保存</button>
</form>

ここではth:fieldを使っていますが、内部的にはth:checkedが自動で適用され、notifyByEmailがtrueならチェック状態になります。

5. よくあるつまずきポイント（nullチェック、boolean型との扱い）

初心者がth:checkedでつまずきやすいポイントとして、「nullとの比較」「boolean型の扱い」「booleanとBooleanの違い」などがあります。

まず、Javaではbooleanはプリミティブ型でnullになりませんが、Booleanはオブジェクト型のためnullになります。テンプレート側でnullをそのまま評価すると、falseとして扱われます。


<input type="checkbox" th:checked="${form.flag}">

このときform.flagがnullだった場合はチェックが外れた状態になりますが、処理によってはNullPointerExceptionになることもあるので、次のように安全に記述するのがおすすめです。


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

これにより、form.flagがnullの場合にはチェックされず、安全に表示できます。

また、booleanを使っていても初期化されていないケースがあると、チェックが外れてしまいます。確実に意図通り動作させるためには、コントローラ側で明示的にtrueまたはfalseを設定するようにしましょう。

さらに、複数のチェックボックスを扱う際に、th:fieldで配列やリストをバインディングする場合も注意が必要です。


<input type="checkbox" th:field="*{options}" value="A" /> 選択肢A
<input type="checkbox" th:field="*{options}" value="B" /> 選択肢B

このようにth:fieldでバインディングすれば、複数の選択肢が配列やリストにマッピングされます。選択済みの値が自動でチェック状態に反映されます。

Thymeleafとth:checkedによるチェックボックス制御は、一見単純に見えますが、フォームと連携する際の型や初期値、null処理などに注意することで、より安全で使いやすい実装が可能になります。

6. 複数チェックボックスの状態を一括で処理する方法

設定画面やアンケート画面など、複数のチェックボックスを扱う場面では、チェック状態を配列やリストとして一括で扱いたいケースがあります。

Thymeleafでは、th:fieldを利用することで、複数のチェックボックスの選択状態をリストにバインディングできます。

たとえば、ユーザーが希望する通知方法を複数選べるようにしたい場合、以下のように記述します。


<form th:action="@{/notify}" th:object="${notifyForm}" method="post">
    <label><input type="checkbox" th:field="*{channels}" value="email" /> メール</label><br>
    <label><input type="checkbox" th:field="*{channels}" value="sms" /> SMS</label><br>
    <label><input type="checkbox" th:field="*{channels}" value="push" /> プッシュ通知</label><br>
    <button type="submit">保存</button>
</form>

このように書くことで、チェックされた値はchannelsリストに格納されます。

Java側では、以下のようにList<String>を用意します。


public class NotifyForm {
    private List<String> channels = new ArrayList<>();
    public List<String> getChannels() { return channels; }
    public void setChannels(List<String> channels) { this.channels = channels; }
}

コントローラでも同様にモデル属性を設定します。


@Controller
public class NotifyController {

    @GetMapping("/notify")
    public String showForm(Model model) {
        NotifyForm form = new NotifyForm();
        form.setChannels(Arrays.asList("email")); // 初期状態でメールを選択
        model.addAttribute("notifyForm", form);
        return "notify";
    }

    @PostMapping("/notify")
    public String save(@ModelAttribute NotifyForm form) {
        // 選択されたチャンネルを処理
        return "redirect:/notify";
    }
}

このようにThymeleafのth:checkedとth:fieldを組み合わせることで、複数のチェックボックスを効率的に制御できます。

7. チェックボックスとフォーム送信の連携（POSTリクエストとの組み合わせ）

チェックボックスの状態をサーバーへ送信して設定を保存するには、POSTリクエストとの連携が重要です。

たとえば、「通知を有効にする」という単一のチェックボックスを設定画面で扱う場合、以下のようなHTMLを記述します。


<form th:action="@{/setting/save}" th:object="${settingForm}" method="post">
    <label>
        <input type="checkbox" th:field="*{enableNotification}" /> 通知を有効にする
    </label>
    <button type="submit">保存</button>
</form>

フォーム送信時、チェックされていればtrueが送信され、外れていればfalseになります。

この動作を受け取るため、Java側では以下のようなクラスを用意します。


public class SettingForm {
    private boolean enableNotification;
    public boolean isEnableNotification() { return enableNotification; }
    public void setEnableNotification(boolean enableNotification) { this.enableNotification = enableNotification; }
}

コントローラでは、POST受信時に@ModelAttributeで値を受け取り、処理を行います。


@Controller
public class SettingController {

    @PostMapping("/setting/save")
    public String saveSettings(@ModelAttribute SettingForm form) {
        // フォームの内容を保存
        boolean isEnabled = form.isEnableNotification();
        // 保存処理など
        return "redirect:/setting/save";
    }
}

このようにThymeleafのth:checkedは、Springのフォーム処理とスムーズに連携可能で、チェック状態をそのままJavaのフィールドに反映できます。

チェックボックスが未チェックの場合はリクエストに値が含まれないため、boolean型を使用しておくことでfalseが自動補完されるという特性も、初心者が理解しておきたいポイントです。

8. 実践例：設定画面でのチェックボックス制御

最後に、よくある実践ケースとして、ユーザーの設定画面で複数のチェックボックスを制御する例を見てみましょう。

以下は、複数の設定項目（メール通知・SMS通知・アカウントの公開設定）をチェックボックスで管理するフォームの例です。


<form th:action="@{/profile/save}" th:object="${profileForm}" method="post">
    <label><input type="checkbox" th:field="*{mailNotification}" /> メール通知を受け取る</label><br>
    <label><input type="checkbox" th:field="*{smsNotification}" /> SMS通知を受け取る</label><br>
    <label><input type="checkbox" th:field="*{publicProfile}" /> プロフィールを公開する</label><br>
    <button type="submit">変更を保存</button>
</form>

このフォームは、各チェック項目の状態をth:checkedによって自動制御します。Javaのフォームクラスは以下のようになります。


public class ProfileForm {
    private boolean mailNotification;
    private boolean smsNotification;
    private boolean publicProfile;

    public boolean isMailNotification() { return mailNotification; }
    public void setMailNotification(boolean mailNotification) { this.mailNotification = mailNotification; }

    public boolean isSmsNotification() { return smsNotification; }
    public void setSmsNotification(boolean smsNotification) { this.smsNotification = smsNotification; }

    public boolean isPublicProfile() { return publicProfile; }
    public void setPublicProfile(boolean publicProfile) { this.publicProfile = publicProfile; }
}

そして、@Controllerでは以下のように設定します。


@Controller
public class ProfileController {

    @GetMapping("/profile")
    public String showForm(Model model) {
        ProfileForm form = new ProfileForm();
        form.setMailNotification(true);
        form.setSmsNotification(false);
        form.setPublicProfile(true);
        model.addAttribute("profileForm", form);
        return "profile";
    }

    @PostMapping("/profile/save")
    public String save(@ModelAttribute ProfileForm form) {
        // 保存処理
        return "redirect:/profile";
    }
}

このように、ThymeleafとSpringの@Controllerを組み合わせることで、チェックボックスによる設定変更を簡単に実現できます。

初心者向けのプロジェクトでは、まずこういった実用的な例から試すことで、Thymeleafのth:checkedやチェックボックス制御の基礎がしっかり身につきます。