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

新人

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

先輩

「Thymeleafの変数はHTMLテンプレート内でデータを一時保存して使う仕組みだよ。@Controllerから渡されたデータや、演算結果を扱えるんだ。」

新人

「具体的にはどんなふうに定義して使えばいいんでしょう？」

先輩

「それじゃあ基本の定義方法から、実例を交えて説明していくよ！」

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

ThymeleafはHTMLテンプレートエンジンで、HTML内に変数を定義してデータを保持できます。これは@Controllerから渡されるモデル変数とは別に、テンプレート内だけで使える一時的な変数です。

初心者がまず覚えておきたいのは、th:with属性で変数を定義し、th:textなどで使える点です。ループの中や条件分岐の中でも別名で再定義ができて便利です。

環境はPleiades＋Gradle＋@Controllerで@ Spring設定済みなので、モデルと組み合わせて安心して使えます。

2. 変数を定義する方法と使い方（基本的な使い方を具体例で紹介）

以下のHTMLでは、th:withで変数を定義し、その後に出力しています。まずは基本の書き方を確認しましょう。


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

この例では、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 DemoController {
  @GetMapping("/hello")
  public String hello(Model model) {
    model.addAttribute("name", " 太郎");
    return "hello";
  }
}

このコントローラでは、nameというモデル変数を渡しています。

続いて、hello.htmlで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} + ' さん'">
  <p th:text="${greeting} + '、' + ${fullName}">ようこそ、名前 さん</p>
</body>
</html>

ここでは、モデル変数nameをfullNameという変数に加工しています。このようにして、テンプレート内で柔軟に文字列編集が可能です。

3. 変数のスコープと使用できる箇所

Thymeleafの変数には、有効な範囲（スコープ）があります。th:withで定義した変数は、その要素と子要素の中だけで使えます。ループや条件分岐の中でも新しく上書きできます。

たとえば、以下のHTMLでは親要素で定義した変数を

の中で再定義し、それぞれに応じて異なる値を使っています。


<ul th:with="parentMsg='全体メッセージ'">
  <li th:each="item : ${items}"
      th:with="subMsg='項目: ' + ${item}">
    <p th:text="${parentMsg}">全体メッセージ</p>
    <p th:text="${subMsg}">項目: 値</p>
  </li>
</ul>

このように変数のスコープを意識することで、テンプレート内で安全にデータを扱えます。また、th:blockでもスコープを使って値をまとめられます。

4. よくある間違いとその解決方法

初心者がつまずきやすい問題として、次のような間違いがあります。

変数名の重複による上書き

同じ名前で複数回定義すると、後から定義した値で上書きされ、意図した表示がされないことがあります。


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

上記のように、スコープを理解しておけば安全です。

モデル変数とローカル変数の区別が曖昧

Controllerから渡されたnameと、th:with="name=...“ で同じ名前を使うと混乱するので注意が必要です。


<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」のようにカンマを入れましょう。

5. 初心者が知っておくべきポイント

Thymeleafで変数を使うとき、まず覚えておきたいのは「テンプレート内だけで使える一時変数が定義できる」という点です。th:withを使えば、表示用のデータを加工したり、一時的な計算結果を保持して使うのに便利です。

変数の有効範囲（スコープ）は、その要素と子要素の中に限られます。ループや条件分岐で再定義できるため、使い分けを意識することで安全にテンプレートを構成できます。

また、モデル変数とテンプレート変数を同じ名前にすると表⽰が思わぬ⽅向に変わります。初心者のうちは名前の重複を避けて、意図した変数を明確にしておきましょう。

構文エラーを避けるためには、th:with内のカンマやクオートを正しく書くことも重要です。正しく書けば、変数定義がシンプルで可読性の高いテンプレートになります。

最終的には、th:withで一時変数を定義し、th:textなどで表示し、th:eachやth:blockで必要に応じて再定義しながら、安全かつ柔軟な表示処理を実現するという流れが基本になります。

6. よくある質問と回答

Q. テンプレート内変数はController側のモデル変数と違うの？

A. はい、テンプレート内で定義する変数は一時的なもので、th:withを使ってHTML出力中にだけ使います。一方、モデル変数はControllerから渡されて全体で使える変数です。

Q. 変数のスコープがわからずに上書きしてしまった

A. 親要素で定義して、子要素で再定義するのが原因です。必要ならth:blockでまとめて意図を明示し、スコープを意識して書きましょう。

Q. th:withで複数定義するとき、カンマを入れ忘れることがある

A. カンマを忘れると構文エラーになります。必ず「var1='値', var2=式」のようにカンマで仕切るように注意してください。

Q. モデル変数nameとテンプレート変数nameが両方ある場合は？

A. テンプレート内のth:withが優先されるため、モデル変数は隠されてしまいます。意図しない代入を避けるため、名前は別々にしましょう。

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

Pleiades環境にGradleと@Controllerを使ったSpring設定が済んでいる前提で、以下の情報が学習に役立ちます。

公式Thymeleafリファレンス：th:withやスコープ、式演算の基本が丁寧に解説されています。
Spring公式ドキュメント：@Controllerからモデルへデータを渡す流れや、ビルド設定がステップごとに紹介されています。
サンプルプロジェクト：GitHubで公開されているPleiades＋Gradle設定済みのテンプレート例を参考にすると、実際の動きを試しながら理解が深まります。
テンプレート内での演算と表示の実例：文字列の結合や条件演算などを実際に書いてみることで、th:withの実用性がわかりやすくなります。

まずは簡単なテンプレートを作って、th:withで変数を定義し、表示までの流れを体験してみましょう。そのあとにループ制御やスコープ再定義を試すことで、自然にテンプレートの構造を理解できます。

初心者の方は、小さな機能から試すことが上達への近道です。基本と構文を抑えながら、一歩ずつ学習を進めていきましょう！

まとめ

Thymeleafの変数の考え方を全体で振り返る

この記事では、Thymeleafにおける変数の基本的な定義方法から使い方、スコープの考え方、さらに初心者がつまずきやすい注意点までを順を追って解説してきました。 Thymeleafの変数は、Javaのローカル変数とは異なり、HTMLテンプレート内で表示処理を補助するための一時的な変数として使われるのが大きな特徴です。 th:withを使うことで、@Controllerから渡されたモデル変数を加工したり、表示用に分かりやすい形へ変換したりできるため、画面側のロジックをすっきり整理できます。

特にSpring MVCとThymeleafを組み合わせた開発では、Controllerで取得した値をそのまま表示するのではなく、テンプレート内で文字列を結合したり、表示用の名称を組み立てたりする場面が頻繁にあります。そのような場合に th:with を活用すると、「表示に必要な処理はテンプレート側で完結させる」という分担がしやすくなり、 Java側のコードを必要以上に複雑にせずに済みます。

スコープを理解することが安全なテンプレート作成の鍵

Thymeleafの変数を扱ううえで最も重要なポイントの一つが、変数のスコープです。 th:withで定義した変数は、その属性が書かれている要素と、その子要素の中でのみ有効になります。この仕組みを理解していないと、「思った場所で値が使えない」「いつの間にか上書きされている」といった混乱が起きやすくなります。

記事内で紹介したように、親要素で定義した変数と、子要素で再定義した変数は別物として扱われます。これはループ処理や条件分岐を行う際に非常に便利な仕組みで、各要素ごとに表示内容を切り替えたい場合にも安全に使えます。逆に、モデル変数と同じ名前をテンプレート変数に使ってしまうと、本来使いたかった値が隠れてしまうため、変数名の付け方には十分注意が必要です。

まとめとしてのシンプルな変数定義サンプル


<body th:with="title='商品一覧', total=${items.size()}">
    <h1 th:text="${title}">タイトル</h1>
    <p th:text="'件数：' + ${total}">件数</p>
</body>

この例のように、th:withを使えばモデル変数をもとにした計算結果や表示専用の値をテンプレート内で簡単に定義できます。表示ロジックをテンプレート側にまとめることで、HTMLの構造が分かりやすくなり、後から見直したときにも意図を理解しやすくなります。初心者の方は、まずこのような小さな例から練習していくのがおすすめです。

先生と生徒の振り返り会話

生徒：「Thymeleafの変数って、最初はJavaの変数と同じ感覚で考えてしまって混乱していました。」

先生：「それはよくあることだね。Thymeleafの変数は表示を助けるための一時的な存在だと考えると分かりやすいよ。」

生徒：「th:withを使うと、Controllerの値を加工してそのまま表示できるのが便利だと感じました。」

先生：「そうだね。表示専用の処理をテンプレート側で完結させるのは、実務でもよく使う考え方だよ。」

生徒：「スコープを意識しないと、変数が上書きされる理由が分からなくなるのも納得できました。」

先生：「変数名とスコープを意識できるようになると、テンプレートが一気に読みやすくなるはずだ。」

生徒：「まずはth:withとth:textをしっかり練習して、ループや条件分岐でも使ってみます。」

先生：「それが一番いい進め方だね。基礎が固まれば、Thymeleaf全体の理解も自然と深まるよ。」