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

新人

「Thymeleafで変数定義ってどうやるんですか？Javaの変数と違うんですか？」

先輩

「Thymeleaf変数はHTMLテンプレート内専用の一時変数で、@Controllerから渡すモデルとは別扱いだよ。表示や計算用の補助として柔軟に使えるんだ。」

新人

「具体的な書き方や使い方を例で見せてくれますか？」

先輩

「もちろん。GradleとPleiadesでの基本構成前提で、th:with を中心に丁寧に解説するよ！」

1. Thymeleafの変数の基本とは？

ThymeleafはSpring Frameworkで人気のあるサーバーサイドのテンプレートエンジンです。HTMLファイルにth:with属性を使って変数を定義すれば、ページ描画中だけに使える一時的なテンプレート変数を保持でき、表示内容や計算結果を簡単に扱えます。

たとえば、画面内で挨拶文や合計値を表示したいとき、@Controllerから渡すモデル変数に加えて、一時変数で補助計算を行えます。これにより、HTMLがすっきりし、モデル側の処理もシンプルに保てます。

初心者にとって理解しやすいのは、Thymeleaf変数はテンプレートごとに限定され、Javaの変数とはスコープが異なるという点です。テンプレート内で完結するため、コードの可読性と保守性も向上します。

2. 変数の定義方法（th:withを中心に具体例を示しながら解説）

変数を定義するには、th:with属性をHTML要素に追加します。複数の変数をカンマで区切って定義でき、文字列や数値の計算も可能です。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
  <meta charset="UTF-8">
  <title>変数定義の基本</title>
</head>
<body th:with="greeting='こんにちは', count=3">
  <p th:text="${greeting}">デフォルト挨拶</p>
  <p th:text="'現在のカウント：' + ${count}">カウント情報</p>
</body>
</html>

この例では、th:with="greeting='こんにちは', count=3"としてgreetingとcountを定義し、それぞれ

要素でth:textを使って値を表示しています。${}で変数を参照できる点が特徴です。

次は、@Controllerから渡されたモデル変数と組み合わせた例です。以下はController側のコードになります。


package com.example.demo;

import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;

@Controller
public class SampleController {
  @GetMapping("/welcome")
  public String welcome(Model model) {
    model.addAttribute("name", "花子");
    return "welcome";
  }
}

この@Controllerではnameというモデル変数を渡しています。次に、テンプレートでth:withと組み合わせます。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head><meta charset="UTF-8"><title>ようこそ画面</title></head>
<body th:with="greeting='ようこそ', fullName=${name} + ' さん'">
  <h1 th:text="${greeting} + '、' + ${fullName}">ようこそ、 花子 さん</h1>
</body>
</html>

この例では、モデル変数nameをfullNameとして加工し、テンプレート内で使っています。これにより、テンプレートでの文字列結合や挨拶文生成がきれいに記述できます。

Gradle環境とPleiades設定済みの前提であれば、上記のように@PostMappingを使わず@Controllerを使った基本構成で簡単にテンプレート変数が使えます。

3. 変数のスコープと有効範囲の理解

Thymeleafのth:withで定義した変数は、その要素と子要素の範囲だけで有効です。スコープを意識することが、意図したデータを正しく表示するコツです。


<ul th:with="parentMsg='親メッセージ'">
  <li th:each="item : ${items}"
      th:with="childMsg='項目: ' + ${item}">
    <p th:text="${parentMsg}">親メッセージ</p>
    <p th:text="${childMsg}">項目: 値</p>
  </li>
</ul>
<p th:text="${parentMsg}">ここでも親メッセージ</p>

この例では

要素の中ではchildMsgが使えますが、外では使えません。逆にparentMsgは

さらに、th:blockを使うことで変数のスコープを論理ブロックの中に閉じることができます。これにより、複雑なHTML構造でも変数がぶつからないように整理できます。


<th:block th:with="tempVal=${someValue}">
  <p th:text="${tempVal}">一時値</p>
</th:block>
<!-- tempVal はここではアクセス不可 -->

4. よくある間違い例と正しい書き方

初心者の方がよく間違える例をいくつか紹介し、正しい書き方とともに解説します。

変数名の重複による予期せぬ上書き


<body th:with="msg='最初のメッセージ'">
  <div th:with="msg='上書きされたメッセージ'">
    <p th:text="${msg}">上書きされたメッセージ</p>
  </div>
  <p th:text="${msg}">最初のメッセージ</p>
</body>

同じ名前の変数を別スコープで定義すると上書きされます。変数名は意味が通じるように注意して使い分けましょう。

モデル変数とテンプレート変数の衝突


<body th:with="name='テンプレート内名前'">
  <p th:text="${name}">テンプレート内名前</p>
</body>

このようにすると、@Controllerから渡されたnameが無視されてしまいます。モデル変数とテンプレート変数は名前を揃えないことが重要です。

th:with の構文エラー


<body th:with="greeting='こんにちは' count=3"> <!-- カンマ忘れ -->
  <p th:text="${greeting}">こんにちは</p>
  <p th:text="${count}">3</p>
</body>

正しくは「greeting='こんにちは', count=3」とカンマで区切ります。構文ミスを防ぐためには、ひとつずつ丁寧に定義することが大切です。

スペースやクオートの不一致


<body th:with="message=こんにちは"> <!-- クオート不足 -->
  <p th:text="${message}">こんにちは</p>
</body>

文字列は必ずシングルクオートで囲みましょう。正しくはth:with="message='こんにちは'"です。

5. まとめとしての振り返りとポイント

ここまで紹介したThymeleafの変数定義方法は、初心者でも分かりやすく実践できる基本機能です。th:withによって一時変数を定義し、表示用や計算用に活用することで、HTMLテンプレートが整理しやすくなります。

重要なポイントは以下の通りです：

テンプレート変数は一時的でスコープが短い：定義された要素とその子要素内だけで有効です。
変数名の重複を避ける：モデル変数とテンプレート変数で同じ名前を使うと上書きされてしまうため、分かりやすい名前にしましょう。
構文に注意：複数定義時はカンマで区切り、文字列はシングルクオートで囲む必要があります。
スコープ制御の工夫：th:blockを使って変数の有効範囲を明示的に分けると、テンプレートが読みやすくなります。

これらの基本ルールを守れば、Gradle＋Pleiades環境で@Controllerと連携したThymeleafテンプレートが、安定して使いやすくなります。

6. 初心者向けによくある質問と回答

Q. テンプレート変数はJavaの変数とどう違いますか？

A. Javaの変数はメソッドやクラス単位で使われますが、Thymeleafの変数はHTMLテンプレート内だけで役割を持つ一時変数です。

Q. モデル変数と同じ名前にしてしまったときどうなる？

A. テンプレート変数が優先され、モデル変数が隠れてしまうため、名前の衝突を避けることが大切です。

Q. th:with内でカンマを入れ忘れるとどうなる？

A. タイプミスによる構文エラーが発生し、テンプレートのレンダリングに失敗します。記述後は画面表示確認を忘れずに。

Q. 一時変数として演算も可能ですか？

A. はい、th:with="total=${price} * ${quantity}" のように、四則演算や文字列結合も使えます。

7. 学習を深めるためのおすすめ情報

以下の資料やサンプルを活用すると、Thymeleaf変数の理解がさらに深まります：

公式Thymeleafリファレンス：th:withや式言語、スコープの詳細な説明あり。
Spring公式ガイド：@Controllerとの連携方法や、Gradleプロジェクト設定の手順が丁寧に解説されています。
GitHubのサンプルプロジェクト：Pleiades＋Gradle＋Thymeleaf環境が整ったサンプルで、自分の環境に取り込んで動作確認が可能です。
所感のある実践的Tip記事：例えば「文字列結合テンプレート」や「演算結果をHTMLに表示する小技」など、便利な使い方をまとめた記事が参考になります。

まずは一番簡単な画面でth:withを使って変数定義と表示を試し、その後演算やスコープ制御にチャレンジしてみましょう。段階的に経験を積むことで、Thymeleafテンプレートの書き方が自然に身につきます。