Thymeleaf 変数式の書き方を完全ガイド！初心者でもわかる式展開の基本

Thymeleaf 変数式の書き方！式展開の基本

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

新人

「先輩、Thymeleafの変数式ってどんな仕組みなんですか？」

先輩

「Thymeleafでは、HTMLテンプレート内で変数を展開する仕組みがあって、それを式展開と呼びます。式展開を使うことで、HTMLに値を埋め込めるんだ。」

新人

「なるほど！式展開ってどんな書き方をするんですか？」

先輩

「それじゃあ、Thymeleafの式展開の基本を一緒に見ていこう！」

1. Thymeleafの式展開とは？

Thymeleafの式展開とは、HTMLファイルに記述した変数をサーバー側で動的に値に置き換えて表示する仕組みです。たとえば、Javaの@Controllerクラスで設定したモデルの値を、HTMLに表示させるときに使います。

Thymeleafでは、式展開に${...}の書き方を使います。これを「変数式」とも呼びます。例えば、Javaの変数messageの値をHTMLに表示したい場合、次のように記述します。


<p th:text="${message}">ここにメッセージが入ります</p>

このように、th:text属性の中に${...}で変数を書いておくと、コントローラで渡した値がHTMLの表示に反映されます。とてもシンプルで直感的な書き方です。

開発環境はPleiadesをインストールして、Gradleでプロジェクトを作成することを前提にしています。プロジェクトの作成時にSpring Webの依存関係を追加すれば、Thymeleafも使えるようになります。

2. 式展開の基本的な書き方

ここでは、Thymeleafの式展開の基本的な書き方を、実際のコード例を交えながら解説します。まずは、Javaの@Controllerクラスを作成します。


package com.example.thymeleafdemo.controller;

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

@Controller
public class MessageController {

    @GetMapping(&quot;/showMessage&quot;)
    public String showMessage(Model model) {
        String message = &quot;こんにちは、Thymeleaf！&quot;;
        model.addAttribute(&quot;message&quot;, message);
        return &quot;message&quot;;
    }
}

このMessageControllerクラスでは、showMessageメソッドでModelにmessageという名前で文字列を登録しています。このmessageをHTMLに表示するために、Thymeleafの式展開を使います。

次に、HTMLファイルの中身を見ていきましょう。Pleiadesで作成したsrc/main/resources/templatesフォルダに、message.htmlを作成します。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>Thymeleaf 式展開の基本</title>
</head>
<body>
    <h1>Thymeleaf 変数式の例</h1>
    <p th:text="${message}">ここにメッセージが入ります</p>
</body>
</html>

このように、th:text属性を使って${message}と書くことで、Modelに渡したmessageの値が表示されます。PleiadesのGradleプロジェクトでアプリケーションを実行すると、ブラウザで/showMessageにアクセスしたときに、「こんにちは、Thymeleaf！」と表示されます。

式展開の書き方のポイントは、必ず${...}の中に変数名を書くことです。th:text属性は、HTMLの要素の中身を書き換える働きを持っています。これによって、サーバー側の値を動的にHTMLに反映できます。

さらに、Thymeleafでは他にもいろいろな属性を式展開に使えます。例えば、リンク先を動的に書き換えるth:hrefや、フォームの値を設定するth:valueなどです。これらも基本的な書き方は同じで、${...}の中に変数名を入れます。

Thymeleafの式展開は、初心者でもすぐに使える便利な仕組みです。まずはth:textをしっかりマスターして、次にth:hrefやth:valueなど、ほかの属性でも試してみてください。

Thymeleafの式展開を覚えておくと、Spring Bootアプリケーションの画面作成がとてもスムーズになります。ぜひ、Pleiadesの開発環境で実際に試してみて、HTMLの動的な仕組みを体験してみましょう！

3. 式展開で使える演算や条件分岐の基本

Thymeleafの式展開では、${...}の中で簡単な演算や条件分岐が使えます。これにより、画面表示を柔軟に制御できるようになります。ここでは初心者向けに、演算と条件分岐の使い方を具体的に見ていきましょう。

3‑1. 算術演算

加算や減算、乗算、除算などの基本演算が式展開にも対応しています。たとえば、モデルで数値を渡して、画面上で演算結果を表示できます。


@GetMapping("/calc")
public String calc(Model model) {
    int a = 5;
    int b = 3;
    model.addAttribute("a", a);
    model.addAttribute("b", b);
    return "calc";
}


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head><meta charset="UTF-8"><title>演算例</title></head>
<body>
  <h1>算術演算の例</h1>
  <p th:text="${a} + ${b} = ${a + b}"></p>
  <p th:text="${a} × ${b} = ${a * b}"></p>
  <p th:text="${a} / ${b} = ${a / b}"></p>
</body>
</html>

実行結果は「5 + 3 = 8」「5 × 3 = 15」「5 / 3 = 1」になります。整数の除算では小数点以下が切り捨てられる点に注意しましょう。

3‑2. 条件分岐（三項演算子）

式展開ではJavaの三項演算子が使えます。条件によって表示を切り替えたい場面で便利です。


@GetMapping("/status")
public String status(Model model) {
    boolean loggedIn = true;
    model.addAttribute("loggedIn", loggedIn);
    return "status";
}


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head><meta charset="UTF-8"><title>条件分岐例</title></head>
<body>
  <h1>条件分岐の例</h1>
  <p th:text="${loggedIn} ? 'ログイン中です' : 'ログインしていません'"></p>
</body>
</html>

このように、? : を使えば、ログイン状態によって文言を切り替えられます。分かりやすく条件分岐を画面に反映できます。

4. ループ内での式展開（具体的な例を交えて解説）

Thymeleafでは、リストの要素を繰り返し表示するループ処理にも式展開が使えます。th:eachを使って、JavaのListに入れたデータをHTML上でループして表示しましょう。

4‑1. コントローラでリストを用意する


@GetMapping("/items")
public String items(Model model) {
    List<String> items = Arrays.asList("リンゴ", "バナナ", "オレンジ");
    model.addAttribute("items", items);
    return "items";
}

ここでは果物の名前を入れたシンプルなリストをモデルに渡しています。

4‑2. HTMLテンプレートでループ処理


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head><meta charset="UTF-8"><title>ループ処理の例</title></head>
<body>
  <h1>果物リスト</h1>
  <ul>
    <li th:each="item, iterStat : ${items}"
        th:text="${iterStat.index + 1} + '. ' + ${item}"></li>
  </ul>
</body>
</html>

th:eachは「アイテム」と「ループ状態」を受け取るように書きます。ここではインデックス番号も同時に表示しています。

4‑3. 条件付きループ表示

ループ内でも条件分岐を組み合わせられます。例えばリストの中身が空の場合にメッセージを出す例です。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head><meta charset="UTF-8"><title>条件付きループ</title></head>
<body>
  <h1>果物リスト（条件付き）</h1>
  <ul th:if="${items.size()} > 0">
    <li th:each="item : ${items}" th:text="${item}"></li>
  </ul>
  <p th:unless="${items.size()} > 0">リストにアイテムがありません</p>
</body>
</html>

ここではth:ifとth:unlessを使って、リストが空かどうかを判定して表示内容を切り替えています。これにより、空の場合のユーザー体験も考慮できます。

4‑4. オブジェクトのリスト表示

同様にJavaオブジェクトのリストにも対応できます。例えばFruitクラスを使って、複数の項目を表示します。


public class Fruit {
    private String name;
    private int price;
    // コンストラクタとゲッター省略
}

@GetMapping("/fruitList")
public String fruitList(Model model) {
    List<Fruit> list = Arrays.asList(
        new Fruit("リンゴ", 150),
        new Fruit("バナナ", 120),
        new Fruit("オレンジ", 180)
    );
    model.addAttribute("fruitList", list);
    return "fruitList";
}


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head><meta charset="UTF-8"><title>オブジェクトリスト</title></head>
<body>
  <h1>果物と価格一覧</h1>
  <table>
    <tr><th>名前</th><th>価格</th></tr>
    <tr th:each="f : ${fruitList}">
      <td th:text="${f.name}"></td>
      <td th:text="${f.price} + '円'"></td>
    </tr>
  </table>
</body>
</html>

このように、オブジェクトのプロパティに対しても${...}でアクセスできます。テーブル形式で表示することで見やすくなります。

これまでで、Thymeleafの式展開による演算、条件分岐、ループ処理について基礎を学びました。ここまでの内容を使えば、動的なリスト表示や条件付き表示など、さまざまな画面処理がPleiades＋Gradle＋@Controllerの環境で実装できます。次のステップでは、さらにフォームやリンクの連携にも挑戦してみましょう！

5. よくある質問とその答え

Q1. 式展開した変数が表示されないときは？

ModelにaddAttributeしているのに表示されない場合、Pleiadesでテンプレートの名前やフォルダ構成を確認しましょう。src/main/resources/templatesに置かれているか、拡張子が.htmlになっているかチェックしてください。@Controllerの戻り値とファイル名が一致しないとThymeleafが読み込めません。

Q2. nullや未定義の変数に安全に対応する方法は？

変数がnullになる可能性があるなら、${var ?: 'デフォルト値'}のように三項演算子を使うと安全です。たとえば、messageがnullなら「利用できません」と表示するようにできます。


<p th:text="${message} ?: '利用できません'"></p>

Q3. 数値をフォーマットしたいときは？

Thymeleafでは標準で式展開にパイプ（|）を使ったフォーマットや、#numbers.formatInteger()などユーティリティが使えます。たとえば桁区切りを追加する方法は次の通りです。


<p th:text="${#numbers.formatInteger(price, ���,)} + '円'"></p>

Q4. 式展開とJavaScriptの連携はどうする？

式展開でJavaScriptの変数に値を埋め込むときは、まずHTML要素に値を埋めてからJSで参照します。直接JS内に${...}を書いても動く場合がありますが、安全性を考えると属性で埋めてから取得する方法がよく使われます。


<div id="data" th:data-value="${someValue}"></div>
<script>
  const value = document.getElementById('data').getAttribute('data-value');
</script>

Q5. ロケール別の日付フォーマットは？

CSVや国別に日付書式を変える場合は、#dates.format()}ユーティリティを使えます。java.util.DateやLocalDateを指定してフォーマット文字列を渡してください。


<p th:text="${#dates.format(today, 'yyyy年MM月dd日')}"></p>

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

Thymeleafの理解をさらに深めるために、以下のリソースがおすすめです。Pleiades＋Gradle＋@Controllerの環境で実践すると学びが定着します。

公式チュートリアルとドキュメント

Thymeleaf公式サイトでは式展開やユーティリティの詳しいドキュメントがあります。特に「Expression Syntax」や「#numbers/#datesユーティリティ」などを読むと式展開の理解が深まります。

Spring Boot公式リファレンス

Spring公式ドキュメントのテンプレート部分にはThymeleafとの連携方法が詳しく載っています。@ControllerでModelに値を渡す流れや、Gradle設定例など初心者にもわかりやすい構成です。

サンプルプロジェクトを触ってみる

GithubにはThymeleafを使ったサンプルアプリが多数公開されています。Pleiadesでチェックアウトして、実際に動かしてみると理解が進みます。課題として、フォーム入力やリンク処理など応用使いの練習にもなります。

オンライン動画や書籍も活用しよう

YouTubeやUdemyで初心者向けThymeleaf動画も多く公開されています。映像でテンプレートの動きを見ると、理解が早くなります。書籍なら「Spring入門」系の書籍がThymeleafの章をまんべんなく網羅しています。

これでThymeleafの式展開に関する記事は完了です。初心者でもPleiades＋Gradle＋@Controllerで動的な画面を作れるようになることを目指して書きました。ご自身のプロジェクトでもまずはth:textやth:eachなどの基本から使ってみてください！