Thymeleafのth:hrefの使い方を全解説。初心者でも完璧に理解できるガイド
生徒
「ThymeleafでURLを設定するにはどうすればいいですか？」
先生
「Thymeleafではth:href属性を使うことで、HTMLのタグに実行URLを設定できますよ。」
生徒
「実際に使うとどうなるのか教えてください！」
先生
「じゃあ、実際のコードを見ていきましょう。」
1. th:hrefとは？
Thymeleafのth:hrefは、HTMLのタグに設定するhref属性を
サーバー側の値で安全に置き換えるための属性です。テンプレート上では
<a th:href="...">と書き、画面に表示される直前（サーバーでのレンダリング時）に
実際のURLへと変換されます。これにより、アプリのコンテキストパス（アプリ配下のベースURL）を自動で考慮しつつ、
手動の文字連結ミスやパス違いを防げます。
<!-- まずは一番やさしい例：トップページに戻るリンク -->
<a th:href="@{/}">トップへ戻る</a>
上の例では、@{/}が「アプリのルート（トップ）」を指します。
本番環境や開発環境でURLの前に付くパスが違っても、th:hrefなら自動で合わせてくれるため、
初心者でも同じテンプレートをそのまま使い回せます。まずは「固定の場所へ戻るリンク」を
th:hrefで置き換えるところから始めると理解しやすいでしょう。
2. th:hrefの基本な使い方
まずは「固定の場所へリンクする」一番シンプルなパターンから始めます。
th:hrefの中で@{...}という書き方（URL式）を使うと、
テンプレートを表示する直前にタグのhrefへ安全に差し込まれます。
基本は「アプリ内のパスをそのまま書く」だけです。
<!-- トップ/ホームなど、固定ページへのリンク -->
<a th:href="@{/home}">ホームに戻る</a>
<!-- ルート（トップ）へ戻る -->
<a th:href="@{/}">トップへ</a>
<!-- 階層があるページへ移動 -->
<a th:href="@{/products/list}">商品一覧へ</a>
<!-- ボタン風のリンク（Bootstrap を利用） -->
<a class="btn btn-primary" th:href="@{/contact}" role="button">お問い合わせ</a>
ポイントは次の2つです。①@{...}の中には「アプリ内のパス」をそのまま書く。
②hrefとth:hrefを同時に書かない（th:hrefが最終的な値を決めるため、基本はth:hrefだけにする）。
これだけで、開発環境と本番環境でパスが違っても自動で整えてくれるので、初心者でも迷いにくくなります。
まずはこの形で、固定ページへのリンクをth:hrefに置き換えてみましょう。
3. 変数やパラメータの流入方法
th:hrefでは、パラメータや変数をURLに流入することもできます。
以下のコードを使って見てみましょう。
<a th:href="@{/user/{id}(id=${user.id})}">ユーザページ</a>
このコードでは、{id}に${user.id}が流入されます。これにより効果的にユーザページのURLを生成できます。
4. th:hrefの実行結果
実際に使用した場合の実行結果を以下に表示します。
<a href="/user/123">ユーザページ</a>
これにより、指定したidに対応したURLが生成されます。
5. クエリパラメータ付きURLの生成（検索・一覧で必須のパターン）
初心者がつまずきやすいのが、クエリパラメータの付け方です。th:hrefは
@{...}の中でキーと値を指定するだけで、URLエンコードも含めて安全に生成してくれます。
「Thymeleaf」「th:href」「URLパラメータ」「Spring MVC」のキーワードを押さえて、SEOに強い内部リンクを正しく作りましょう。
<a th:href="@{/search(q=${keyword}, page=${page}, sort=${sort})}">検索結果へ</a>
生成例：/search?q=スマホ&page=2&sort=price のように、URLエンコード済みで出力されます。
なお、@{...}はアプリのコンテキストパスも自動で考慮するため、本番と開発でパスが違っても安全です。
6. @を使わずに文字連結で動的リンクを作る（相対/絶対パスのコツ）
学習のために、@を使わず文字連結でリンクを作る方法も理解しておきましょう。
文字列補間（|...|）や+演算子でパスやパラメータを連結できます。
ただしURLエンコードやコンテキストパス付与は自動ではありません。運用では@{...}が推奨です。
<!-- 文字列補間（読みやすくて便利） -->
<a th:href="|/user/${user.id}|">ユーザ詳細へ</a>
<!-- 文字列連結（+ 演算子） -->
<a th:href="${'/user/' + user.id}">ユーザ詳細へ</a>
<!-- クエリ文字列の連結（& は & にする） -->
<a th:href="|/search?q=${keyword}&page=${page}|">検索へ</a>
<!-- 絶対URLを直書きする例（外部サイトへ） -->
<a th:href="${'https://example.com/user/' + user.id}" target="_blank" rel="noopener">外部詳細へ</a>
/app の場合、文字連結では
|/app/user/${user.id}| のように自分で付与する必要があります。
また、パラメータのエンコードも自前対応が必要です。確実さが必要なら @{...} を使いましょう。
7. 条件付きリンクとアクセシビリティ（内部リンク最適化のベストプラクティス）
SEOでは内部リンクの品質が重要です。th:ifやth:unlessを使えば、
データが未設定のときに「クリックできないダミーリンク」を避けられます。ユーザ体験（UX）やアクセシビリティの観点でも有効です。
<!-- user が存在する時だけ実リンク、なければテキスト -->
<a th:if="${user != null}" th:href="@{/user/{id}(id=${user.id})}">ユーザ詳細へ</a>
<span th:unless="${user != null}" aria-disabled="true" class="text-muted">ユーザ詳細へ（未選択）</span>
<!-- 在庫なしならボタン風リンクを無効化（視覚的＋意味的配慮） -->
<a th:href="@{/cart/add(id=${item.id})}"
th:attrappend="aria-disabled=${!item.inStock}"
th:classappend="${!item.inStock} ? ' disabled' : ''"
role="button">カートに入れる</a>
クリック不可状態を明示し、誤クリックや離脱を防止することで、サイト回遊性やコンバージョンの改善にもつながります。
まとめ
この記事では、Thymeleafにおけるth:hrefの基本的な使い方から応用的な設定まで解説しました。th:hrefを使うことで、サーバーサイドのデータやパラメータをリンクに組み込むことができ、効率的に動的なURLを生成できます。
初心者でも理解しやすいように、サンプルコードとその実行結果を見ながら説明しました。
具体的には、次のポイントを理解していただけたと思います：
th:href属性を使うことで、HTMLタグにサーバーサイドのURLやデータを指定できる。- 変数やパラメータを組み込むことで、動的なURLの生成が可能。
- Thymeleafではコンテキストパスを
@{}を使って指定することが推奨されている。
以下に簡単なサンプルコードで復習してみましょう。
<a th:href="@{/product/{id}(id=${product.id})}">商品ページへ</a>
上記のコードでは、動的に商品IDをth:hrefに渡し、URLを生成しています。Thymeleafを活用することで、テンプレートエンジンをより柔軟に使うことが可能です。
生徒
「th:hrefを使うと、動的にURLを設定できるんですね！」
先生
「その通りです。パラメータや変数も渡せるので、複数のユーザーページや商品ページを簡単に生成できます。」
生徒
「それなら、毎回手動でURLを書かなくても済みますね！」
先生
「そうですね。Thymeleafは効率的にテンプレートを作成できるので、ぜひ使いこなしてください。」
この記事を読んだ人からの質問
