Thymeleaf（タイムリーフ）の使い方入門！初心者でもわかるth:textの基礎
生徒
「Thymeleafで表示するテキストをコントロールする方法はありますか？」
先生
「Thymeleafではth:textという属性を使うことで、簡単に動的なテキスト表示を実現できますよ。」
生徒
「具体的にはどのように使えばいいのでしょうか？」
先生
「では、基本的な使い方から詳しく解説していきますね！」
1. th:textとは？
th:textは、Thymeleafで最も基本となる機能のひとつで、HTMLタグの中に「サーバーから受け取った値」を表示するための属性です。
例えば、<span>や<div>に設定することで、画面に出したい文字を動的に差し替えることができます。
もし値が設定されていない場合でも、HTML側に書いたデフォルト文字がそのまま表示されるので安心です。
プログラミング未経験でも、HTMLに少し書き足すだけで使えるのが大きな魅力です。 「コントローラーで用意したテキストを画面に出す」という、一番よく使うパターンを 初心者向けの簡単な例で確認してみましょう。
<p>メッセージ：<span th:text="${message}">ここが置き換わります</span></p>
上記では、messageという変数の中身がタグに入ります。
例えば「こんにちは！」という文字が渡されていれば、画面には「メッセージ：こんにちは！」と表示されます。
静的なHTMLではできない「動的なデータ表示」が、たった1行でできるのがth:textです。
Webアプリでは、ユーザー名、エラーメッセージ、商品名など、
状況によって変化するテキストを扱う機会が多くあります。
そうした「毎回違う内容」を安全に表示できる仕組みが、Thymeleafのth:textだと覚えておくと理解しやすいでしょう。
2. 基本的なth:textの使い方
th:textを使って、HTMLの要素にテキストを挿入する方法について見ていきましょう。ここでは、th:textの基本的な構文と使い方を学んでいきます。
例えば、コントローラーから「message」という変数が渡されたときに、それを表示させるHTMLコードは以下のようになります。
<span th:text="${message}">デフォルトテキスト</span>
ここでのth:text="${message}"は、コントローラーから渡された「message」というデータを<span>タグの中に挿入することを意味します。
この記述をすることで、デフォルトテキストはmessageの内容に置き換わり、ブラウザに表示されるようになります。
3. th:textの変数設定とエスケープ処理
Thymeleafのth:textは、Javaオブジェクトや変数の値をHTMLに表示する際、自動的にエスケープ処理を行ってくれます。つまり、<や>といったHTMLの特殊文字があった場合、それをHTMLエンティティに変換して表示します。
例えば、Java側で以下のようなメッセージが設定されているとします。
model.addAttribute("message", "Welcome to <strong>Thymeleaf</strong>!");
このmessageをth:textで表示すると、HTMLエスケープが効いて<strong>タグがそのまま文字列として表示されます。
<span th:text="${message}">デフォルトメッセージ</span>
この結果、次のように画面に出力されます。
Welcome to <strong>Thymeleaf</strong>!
4. th:utextでエスケープを無効にする方法
HTMLエスケープを無効にしたい場合、th:textの代わりにth:utextを使います。th:utextを用いると、HTMLエスケープが無効になり、タグもそのまま適用されます。
先ほどの例でth:utextを使用した場合のコードは次のようになります。
<span th:utext="${message}">デフォルトメッセージ</span>
この場合、表示結果は次のように「Thymeleaf」という文字が太字で表示されます。
Welcome to <strong>Thymeleaf</strong>!
このように、HTMLタグをそのまま反映させたい場合にth:utextを使うと便利です。ただし、ユーザーが入力したデータに対してth:utextを使うと、XSS（クロスサイトスクリプティング）のリスクがあるため注意が必要です。
5. th:textで式を使って計算結果を表示する
th:textでは、式を使って計算結果を直接表示することも可能です。例えば、${5 + 3}のように記述すれば、計算された結果が表示されます。
次の例では、itemsのリストのサイズを表示します。
<p th:text="${items.size()}">アイテムの数</p>
上記のコードは、リストの要素数を表示します。これにより、動的なリストの情報をページに直接表示できます。
6. th:textでの条件分岐表示
Thymeleafのth:textと条件分岐を組み合わせて、特定の条件に応じたテキストを表示することも可能です。
例えば、ログインしているかどうかで表示内容を変える場合、次のようにします。
<p th:text="${isLoggedIn ? 'ようこそ、ユーザーさん！' : 'ゲストさん、ログインしてください'}"></p>
このコードでは、isLoggedInがtrueなら「ようこそ、ユーザーさん！」、falseなら「ゲストさん、ログインしてください」が表示されます。
7. コントローラーからModelに値を渡す基本（@Controllerとth:textの連携）
Thymeleafで動的テキストを表示するには、まずコントローラーからModelに値を詰めてテンプレートへ渡します。ここで渡した値をth:textで参照すれば、ページ内のテキストを安全に置き換えられます。
@Controller
public class HelloController {
@GetMapping("/hello")
public String hello(Model model) {
model.addAttribute("name", "山田");
model.addAttribute("count", 3);
model.addAttribute("now", java.time.LocalDateTime.now());
model.addAttribute("total", java.math.BigDecimal.valueOf(12345.6));
return "hello"; // hello.html をレンダリング
}
}
テンプレート側では、次のようにth:textでModelの値を参照します。
<p>ユーザー名：<span th:text="${name}">ゲスト</span></p>
<p>メッセージ数：<span th:text="${count}">0</span></p>
8. メッセージプロパティとth:textでの国際化（i18n）の基本
固定文言はテンプレートに直書きせず、メッセージプロパティ（例：messages.properties）へ切り出すと、言語ごとの切り替えが容易になります。th:textは#{...}構文でメッセージを参照できます。
# src/main/resources/messages.properties
greeting.user=こんにちは、{0}さん
items.count=アイテム数: {0}
total.amount=合計金額: {0}
テンプレートでは次のように記述します。プレースホルダー{0}へModelの値を渡せます。
<p th:text="#{greeting.user(${name})}">こんにちは、ユーザーさん</p>
<p th:text="#{items.count(${count})}">アイテム数: 0</p>
言語ごとにmessages_ja.propertiesやmessages_en.propertiesを用意すれば、ロケールに応じて自動で適切な文言が表示されます。
9. 文字列の連結・数値／日付フォーマットをth:textで扱う
Thymeleafは文字列の連結やフォーマット用ユーティリティを備えており、th:textだけで見やすい表示を実現できます。
- 文字列連結（リテラル置換）：
|...|で文字列を囲み、${...}を差し込みます。 - 数値フォーマット：
#numbersで整数／通貨などの整形が可能です。 - 日付時刻フォーマット：
#temporalsでjava.timeの値を整形できます。
<p th:text="|ようこそ、${name}さん！|">ようこそ、ゲストさん！</p>
<!-- 整数の見やすい表示（3桁区切りなどロケールに準拠） -->
<p th:text="|未読メッセージ: ${#numbers.formatInteger(count)}件|">未読メッセージ: 0件</p>
<!-- 通貨表示（ロケールの通貨書式に準拠） -->
<p th:text="|合計金額: ${#numbers.formatCurrency(total)}|">合計金額: ￥0</p>
<!-- 日付時刻の整形（java.time.LocalDateTime を想定） -->
<p th:text="${#temporals.format(now, 'yyyy/MM/dd HH:mm')}">2025/01/01 00:00</p>
テキスト生成をすべてテンプレート側で行うのではなく、必要に応じてサービス層で値を整えてからModelへ詰めると、ビューの責務が明確になり保守性が高まります。
まとめ
本記事では、Thymeleafの基本的な使い方から応用的な活用法まで、「th:text」を中心に学びました。Thymeleafは、HTMLとJavaコードのデータバインディングを簡単に行えるテンプレートエンジンであり、Spring Bootと併用することで、動的なWebページの構築が容易になります。特に、th:textを使って、コントローラーから渡されたデータを動的に表示する方法や、エスケープ処理、エスケープ無効化、式による計算や条件分岐による柔軟な表示制御が行えることを確認しました。これらのテクニックを駆使することで、ユーザーに応じたカスタマイズ表示や、柔軟な画面レイアウトが可能になります。
th:textの基本的な使い方として、HTMLの要素にテキストを動的に表示する手順を押さえ、エスケープ処理やth:utextの活用により、タグの扱いやセキュリティについて理解を深めました。また、式を用いた計算やリストの動的表示、条件分岐による出し分けなど、Thymeleafの表現力豊かな機能を活用することがWeb開発において重要であるとわかりました。
以下は、今回学んだ内容の総括的なサンプルコードです。これまで紹介した構文を複合的に活用し、実際のページ構成に適用する例を確認しましょう。
<section>
<h2 th:text="${title}">デフォルトタイトル</h2>
<p th:utext="${introMessage}">デフォルトメッセージ</p>
<div>
<span th:text="${userName != null ? 'ようこそ、' + userName + 'さん！' : 'ゲストさん、ログインしてください'}"></span>
<ul>
<li th:each="item : ${items}" th:text="${item}">サンプルアイテム</li>
</ul>
</div>
<p>計算結果: <span th:text="${10 + 20}">30</span></p>
</section>
上記コードでは、th:textを活用してページ全体のテキストを動的に更新しつつ、条件分岐でログイン状態の異なるユーザー向けのメッセージ表示を行っています。また、アイテムのリスト表示と計算式も取り入れ、複数の機能を組み合わせたサンプルとなっています。
生徒
「先生、Thymeleafのth:textでいろんなことができるんですね！」
先生
「その通りです！特にSpring BootのWebアプリでは、th:textは動的なデータ表示に欠かせません。」
生徒
「エスケープ処理や計算、条件分岐もできるとは思いませんでした。特にth:utextを使うとHTMLもそのまま表示されるんですね。」
先生
「そうです。ただし、ユーザーが入力したデータを表示する際は、XSS攻撃対策としてth:utextの使用には慎重になる必要があります。」
生徒
「わかりました！今後の開発で活用できそうです。しっかり復習して自分のものにしたいと思います！」
先生
「その意気です。Thymeleafの基本をマスターして、Webアプリの見栄えや使い勝手をさらに良くしていきましょう。」
この記事を読んだ人からの質問
