Thymeleaf th:textの使い方とポイントを初心者向けに解説！SpringとGradle環境で学ぶ基本

Thymeleaf th:textの使い方とポイント

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

新人

「先輩、Thymeleafってよく聞くんですけど、具体的に何をするものなんですか？」

先輩

「ThymeleafはJavaのテンプレートエンジンで、HTMLに動的な値を埋め込むための仕組みだよ。Spring MVCと一緒に使うことが多いんだ。」

新人

「なるほど！じゃあ、th:textっていうのは何なんですか？」

先輩

「th:textはThymeleafの属性のひとつで、HTMLタグの中に文字列を表示するために使うんだよ。実際にコードを見てみるとわかりやすいよ。」

1. Thymeleafとは？

Thymeleafは、Spring BootやSpring MVCで広く利用されているテンプレートエンジンです。Thymeleafを使うことで、HTMLファイルにJavaのオブジェクトから渡されたデータを直接表示することができます。特にThymeleaf th:textを使うと、文字列を動的にレンダリングして画面に反映できます。

例えば、従来のJSPのように特殊なタグではなく、HTMLに近い構文で実装できるので、初心者でも直感的に学びやすいのが特徴です。

2. th属性の概要と役割

Thymeleafでは、th:textのほかにも、th:ifやth:eachなど多くの属性があります。これらはすべて「th属性」と呼ばれ、HTMLの標準属性を拡張する形で利用されます。

th属性の最大の特徴は、サーバーサイドで処理された値をHTMLに埋め込み、実際のブラウザには加工済みの静的なHTMLとして表示される点です。これにより、JavaコードとHTMLを分離しながら効率よく開発することができます。

特にth:textはもっともよく使われる属性で、文字列をそのまま表示するために使います。例えば、ユーザー名やメッセージなどを安全に画面に表示するのに適しています。

3. th:textの基本的な使い方

それでは、実際にSpring MVCのコントローラから値を渡して、Thymeleaf th:textで表示する例を見てみましょう。開発環境はpleiadesでGradleを使用し、コントローラは@Controllerを使って実装します。


@Controller
public class HelloController {

    @GetMapping("/hello")
    public String hello(Model model) {
        model.addAttribute("message", "こんにちは、Thymeleafの世界！");
        return "hello";
    }
}

上記のコントローラでは、messageという名前で文字列をモデルに追加しています。次に、ThymeleafのHTMLテンプレートでこの値を表示する方法を見てみましょう。


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

この例では、th:text="${message}"と書くことで、コントローラから渡された「こんにちは、Thymeleafの世界！」という文字列がブラウザに表示されます。


こんにちは、Thymeleafの世界！

このように、Thymeleaf th:textを使えば、コントローラから渡されたデータをHTMLに簡単に表示できます。初心者にとってもわかりやすく、安全に値を表示できるのがポイントです。

4. th:textと通常のHTMLとの違い（エスケープ処理の説明）

ここからはThymeleaf th:textの重要なポイントであるエスケープ処理について説明します。通常のHTMLでは、タグの中に直接文字列を書けばそのまま表示されます。しかし、もしユーザーから受け取った値に危険なスクリプトが含まれていた場合、セキュリティ上のリスクとなります。そこでThymeleaf th:textはデフォルトでエスケープ処理を行い、ブラウザで安全に表示できる形に変換します。

例えば、入力値として<script>alert('xss')</script>という文字列が渡された場合、通常のHTMLならそのまま実行されてしまう可能性があります。しかしth:textを使えば、タグとして解釈されずにただの文字列として表示されます。これによりクロスサイトスクリプティング攻撃を防ぐことができます。

一方で、もしHTMLタグをそのまま有効にしたい場合はth:utextを使いますが、初心者のうちはth:textを基本として覚えておくのがおすすめです。安全に画面に表示するための初歩的な仕組みとして理解しておくとよいでしょう。

5. th:textで変数を表示する方法（モデルから受け取る値）

Thymeleaf th:textでは、サーバー側のコントローラから渡されたモデルの値を表示できます。変数は${変数名}というEL式の形式で書き、HTMLの中で参照します。これにより、動的なデータをテンプレートに埋め込むことが可能になります。

例えば、ユーザー名やメールアドレスなどを画面に表示するケースを考えてみましょう。コントローラでmodel.addAttribute("username", "山田太郎");と設定すると、テンプレート側でth:text="${username}"と書くことで表示できます。


@Controller
public class UserController {

    @GetMapping("/user")
    public String user(Model model) {
        model.addAttribute("username", "山田太郎");
        model.addAttribute("email", "taro@example.com");
        return "user";
    }
}


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>ユーザー情報の表示</title>
</head>
<body>
    <p>ユーザー名: <span th:text="${username}"></span></p>
    <p>メールアドレス: <span th:text="${email}"></span></p>
</body>
</html>


ユーザー名: 山田太郎
メールアドレス: taro@example.com

このように、モデルに格納した値をHTML側で呼び出すことで、動的なコンテンツを作成することができます。Thymeleaf th:textは最も基本的で頻繁に使われる書き方なので、しっかり練習して身につけておくとよいでしょう。

6. コントローラ（@Controller）からビューに値を渡して表示する具体例

次に、実際に複数の値をコントローラからビューに渡し、それをテンプレートで表示する一連の流れを見ていきます。開発環境はpleiadesでGradleを使用し、@Controllerを使うのが前提です。ここでは商品情報を表示する簡単なサンプルを取り上げます。


@Controller
public class ProductController {

    @GetMapping("/product")
    public String product(Model model) {
        model.addAttribute("name", "ノートパソコン");
        model.addAttribute("price", 120000);
        model.addAttribute("description", "高性能で初心者にもおすすめの最新モデルです。");
        return "product";
    }
}


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>商品情報の表示</title>
</head>
<body>
    <h3>商品名: <span th:text="${name}"></span></h3>
    <p>価格: <span th:text="${price}"></span> 円</p>
    <p>説明: <span th:text="${description}"></span></p>
</body>
</html>


商品名: ノートパソコン
価格: 120000 円
説明: 高性能で初心者にもおすすめの最新モデルです。

この例では、コントローラで商品名、価格、説明文をモデルに追加し、テンプレートのth:textでそれぞれを表示しています。これにより、データベースや外部サービスから取得した情報を動的に表示することができ、実用的なWebアプリケーション開発に直結します。

さらに、Thymeleaf th:textを使えば、ユーザーが入力した値をそのまま画面に反映したり、フォームの入力確認画面を作成したりすることも可能です。Spring MVCとThymeleafの組み合わせは、学習コストが低いわりに実務でもよく利用されるので、初心者にとって非常に良い練習題材になります。

ここまででth:textの基本的な仕組みやエスケープ処理、変数の表示方法、コントローラとの連携を学ぶことができました。次の記事では、さらに実践的な使い方やエラーの注意点について解説していきます。

7. th:textを使うときのよくある間違い（エスケープの誤解、変数未設定エラーなど）

この章ではThymeleaf th:textを使うときに初心者がつまずきやすい代表的な間違いを整理します。まず多いのがエスケープ処理に関する誤解です。Thymeleaf th:textは危険な文字を自動的にエスケープして無害化してから表示します。したがって、意図せずにタグそのものを表示してしまうのではないかという心配は不要です。一方でタグとして解釈させたいときにth:textを使ってしまうと、期待どおりに装飾が反映されず、ただの文字列が表示されます。これは仕様どおりの動作であり、使い分けの理解が重要になります。

次に多いのが変数未設定のまま画面に出そうとしてしまうパターンです。コントローラでモデルに値を入れ忘れたり、キーの名前が一致していなかったりすると、画面に何も表示されません。エラーとして見えにくいので、テンプレート側で疑似的な初期値を用意しておくのが実務では有効です。具体的にはエルビス演算子を用いる書き方が便利です。なお、演算子の結果は文字列として扱われ、Thymeleaf th:textによって安全に整形されます。

また、名前空間の宣言忘れも頻出です。テンプレートの先頭に名前空間を宣言しないと、属性がただの未知の属性として無視され、データが表示されません。特に複数のテンプレートを新規作成するときは、雛形のヘッダ部分を確実にコピーすることが重要です。さらに、同じタグ内で静的な文字列とThymeleaf th:textを併用してしまうと、最終的にはth:textが静的な内容を置き換えるため、静的な文字列が残らない点にも注意しましょう。必要なら文字列連結をテンプレート式の中で行い、ひとつの出力にまとめるのが安全です。

最後に、型の扱いの誤解にも触れておきます。数値や日付をそのまま出すと、表示形式が想定と異なることがあります。Thymeleaf th:textはあくまで値を文字列化して出力するため、見た目の整形はテンプレート側の式やフォーマッタを使って行います。簡単な場合は文字列連結やフォーマット用のユーティリティを併用し、表示要件を満たすようにしましょう。


<!-- 名前空間の宣言忘れに注意 -->
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head><meta charset="UTF-8"><title>注意点</title></head>
<body>
    <!-- 未設定だと空になる。エルビス演算子で初期値を用意 -->
    <p th:text="${username} ?: '未設定のユーザー'">初期テキストは置き換えられる</p>

    <!-- 静的文字列は置換される。必要なら式内で連結 -->
    <p th:text="'ようこそ、' + (${username} ?: 'ゲスト') + ' さん'">ようこそ</p>

    <!-- タグをそのまま表示したいのにth:textを使ってしまう誤例 -->
    <p th:text="'&lt;strong&gt;太字にしたい&lt;/strong&gt;'">置換対象</p>
</body>
</html>


未設定のユーザー
ようこそ、ゲスト さん
<strong>太字にしたい</strong>

上の例のとおり、Thymeleaf th:textではタグが文字として表示されます。意図的にタグを効かせたい場合は次の章の使い分けを参照してください。また、モデルのキー名が一致しているか、名前空間を正しく宣言しているかを常に点検する習慣を身につけると、表示不具合の大半を未然に防げます。

8. th:textと他のth属性との違いと使い分け

ここではThymeleaf th:textと、挙動がよく比較される属性の役割と使い所をまとめます。まず基本はth:textで、これは常にエスケープして安全な文字列として出力します。次にth:utextは非エスケープ出力であり、タグや装飾を有効化したいときに使います。ただし、信用できない入力に対して不用意に使うと危険なので、信頼済みの定型HTMLや自前でサニタイズした断片に限定するのが推奨です。さらに、属性値を動的に変えたい場合はth:hrefやth:srcなどの属性専用の書き方を使い、テキスト本体ではth:textを選ぶと読みやすいテンプレートになります。

また、テンプレート内で複数の値をまとめて表示したい場合は文字列結合を使い、構造的な繰り返しや条件分岐が必要な場合はth:eachとth:ifを併用します。これらの役割を明確に分けることで、保守性の高いテンプレートを組み立てられます。とくに学習初期は「テキストはth:text、HTMLを効かせたいときだけth:utext」と覚えておくと混乱を避けられます。


@Controller
public class NoticeController {

    @GetMapping("/notice")
    public String notice(Model model) {
        // 管理画面で登録済みの信頼できるHTML断片だと仮定
        String safeHtml = "<strong>重要なお知らせ</strong>：メンテナンスを実施します。";
        model.addAttribute("title", "本日の更新情報");
        model.addAttribute("rawHtml", safeHtml);
        model.addAttribute("link", "/details");
        return "notice";
    }
}


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head><meta charset="UTF-8"><title>使い分け</title></head>
<body>
    <!-- テキストはエスケープして安全に表示 -->
    <h3 th:text="${title}">タイトル</h3>

    <!-- 非エスケープ。信頼済み断片のみに限定 -->
    <p th:utext="${rawHtml}">お知らせ本文</p>

    <!-- 属性は専用のth:hrefで。テキストはth:textで -->
    <a th:href="${link}" th:text="'詳細はこちら'">詳細</a>
</body>
</html>


本日の更新情報
重要なお知らせ：メンテナンスを実施します。
詳細はこちら

このように、Thymeleaf th:textは「安全な既定値」、th:utextは「慎重な例外」という発想で切り分けるのが実務的です。リンク先や画像パスのような属性は専用の属性バインドを使い、本文文字列はth:textで処理するという線引きを守ると、テンプレートの読みやすさと安全性が両立します。

9. 初心者が学ぶときのおすすめの練習方法（小さなアプリを作って試すなど）

学習の効果を高めるには、Thymeleaf th:textの基本と使い分けを短い反復で試すことが大切です。まずは小さなメッセージ表示アプリから始め、固定文字列、モデルからの受け渡し、未設定時の初期値、整形の順に段階を踏んで実装します。開発環境はpleiadesを使い、ビルドはGradle、コントローラは@Controllerで構成します。テンプレートの雛形を常にコピーして名前空間を確実に宣言し、画面に出るまでの最短ルートを毎回なぞることで、手順の抜け漏れを減らせます。

次に、入力フォームから受け取った文字列を確認画面に表示する小さな流れを作ると、実運用に近い感覚を身につけられます。未入力や不正な値が来たときにも画面が崩れないように、エルビス演算子で初期値を出したり、空文字を検知して別の文言を出したりする練習を繰り返してください。さらに、ニュースのお知らせのように装飾を含む文章を扱う場面を想定し、非エスケープ出力と安全性の関係を実験することも有意義です。その際は信頼できる断片かどうかを必ず意識し、th:utextの使用範囲を明確に決めておきましょう。

最後に、一覧画面を用意して複数の項目の表示を繰り返す練習を追加します。繰り返しの中でも本文はThymeleaf th:textで出力し、リンクや画像のパスは属性専用のバインドで処理する方針を徹底します。これにより、テンプレートの役割分担が自然に身につき、保守のしやすい構造を作れるようになります。練習は短い単位で区切り、表示結果を必ず目で確認し、想定と違うときはテンプレート式、モデルのキー、名前空間、コントローラの返却名の四点を順に点検するチェックリストを持つと、原因特定の速度が大きく向上します。


@Controller
public class PracticeController {

    @GetMapping("/confirm")
    public String confirm(@RequestParam(value = "msg", required = false) String msg, Model model) {
        model.addAttribute("msg", msg);
        model.addAttribute("items", java.util.List.of("お知らせA", "お知らせB", "お知らせC"));
        model.addAttribute("detail", "/detail");
        return "confirm";
    }
}


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head><meta charset="UTF-8"><title>練習用テンプレート</title></head>
<body>
    <!-- 未入力時でも崩さない -->
    <p th:text="${msg} ?: 'メッセージは未入力です'">初期値</p>

    <!-- 一覧表示。本文はth:text、リンクはth:href -->
    <ul>
        <li th:each="i : ${items}">
            <a th:href="${detail}" th:text="${i}">項目</a>
        </li>
    </ul>
</body>
</html>


メッセージは未入力です
お知らせA
お知らせB
お知らせC

この練習では、入力が空でも画面が安定して動作し、複数の要素を安全に表示できます。繰り返し処理の中でも本文はThymeleaf th:textを用いるという原則を守ることで、セキュリティと見通しの良さを同時に確保できます。小さな完成体験を積み重ねていけば、実案件で遭遇する表示要件にも落ち着いて対応できるようになります。毎回の学習記録に「どの値をどのキーで渡し、テンプレートでどう参照したか」を残しておくと、後からの復習やトラブルシュートに非常に役立ちます。最終的には、一覧、詳細、確認といった典型的な画面遷移を自力で組み合わせ、Thymeleaf th:textを土台にした安定した表示設計を身につけましょう。

まとめ

この記事で学んできたThymeleaf th:textは、Spring Boot や Spring MVC を使った画面表示の中でも特に利用頻度が高く、テンプレートエンジンを理解するうえで避けて通れない重要な仕組みです。Java のコントローラから渡した値を安全に HTML に埋め込み、ブラウザ側に反映させるという流れは、Web アプリケーション開発の基本ともいえる動作です。th:text は、入力された値をそのまま出力するだけでなく、危険な文字をエスケープして安全に表示するため、初心者でも安心して扱える点が大きな特徴です。

また、th:text は HTML の静的部分とJava側の動的値を自然につなぐ役割を果たすため、複雑な画面生成もしやすくなります。今回の記事では、モデルに格納した値を表示する方法、エスケープ処理の仕組み、変数の未設定時の対処、th:utext との違いなどを丁寧に確認しましたが、実際の画面開発ではこれらの理解が大きく役立ちます。特に th:text を中心として th:if や th:each を組み合わせると、画面に表現できる幅が一気に広がり、商品一覧、お知らせリスト、ユーザー情報の表示などさまざまな応用が可能になります。

さらに、画面側での表示に関するトラブルの多くは、モデルのキー名の不一致や名前空間宣言の抜け、th:text と静的文字が競合してしまうケースに起因するものでした。こうした問題も仕組みを理解していれば落ち着いて対処でき、原因調査の時間も短縮できます。テンプレート構造とコントローラの動きを実際に手を動かしながら学ぶことで、Thymeleaf 全体の見通しが良くなり、Spring MVC を使ったアプリケーション開発に自信がつきます。

■ サンプルコード：まとめとして確認する th:text の基本例

記事内容の総復習として、モデルから値を渡して画面に th:text で表示する最小構成のコードを掲載します。


@Controller
public class SummaryController {

    @GetMapping("/summary")
    public String showSummary(Model model) {
        model.addAttribute("title", "Thymeleafのまとめ表示");
        model.addAttribute("content", "th:textで動的な値を安全に表示できます。");
        model.addAttribute("note", "エスケープ処理が標準で有効です。");
        return "summary";
    }
}


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head><meta charset="UTF-8"><title>まとめ表示</title></head>
<body>
    <h2 th:text="${title}">初期タイトル</h2>
    <p th:text="${content}">初期本文</p>
    <p th:text="${note}">初期ノート</p>
</body>
</html>

このような最小サンプルであっても、コントローラとテンプレートの役割分担、モデルからビューへの受け渡し、そして安全な文字列出力という大切なプロセスがすべて含まれています。ここからさらに条件分岐や繰り返し処理を追加していけば、実務でよく使われる画面構成を実現できるでしょう。

■ th:text を使いこなすための応用例

次のように、複数の値を連結したり、エルビス演算子で未設定時の初期値を設定したりと、表現の幅を広げられます。


<p th:text="'ようこそ、' + (${username} ?: 'ゲスト') + ' さん'">ようこそ</p>
<p th:text="${description} ?: '説明文は登録されていません'">説明文</p>

このような短い工夫が加わるだけで、画面の安定性やユーザビリティが向上し、エラーの起きにくい実用的なテンプレートに仕上がります。特に入力値の確認画面やエラー時のメッセージ表示では、th:text の扱い方が非常に重要になります。

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

生徒：「th:text の使い方を学んでみると、画面表示の仕組みがすごくわかりやすくなりました。モデルの値を画面に出す流れがつながりました！」

先生：「そうだね。Thymeleaf の基本は th:text に集約されているといってもいいくらいだよ。安全に値を表示するためのエスケープ処理もポイントだったね。」

生徒：「エスケープされることを知らずに困ることが多かったのですが、仕組みがわかったので安心して使えそうです。th:utext との違いもハッキリしました。」

先生：「使い分けを理解しておくことは大事だよ。特に初心者のうちは th:text を基本にして、慎重にテンプレートを扱う癖をつけると失敗が少ないんだ。」

生徒：「今後は th:each や th:if と組み合わせて、より動的な画面も作れるように挑戦してみたいです！」

先生：「その意気だね。小さな表示から積み上げていけば、実用的なアプリケーションも必ず作れるようになるよ。」

この記事を読んだ人からの質問