Thymeleafのth:includeの使い方を完全ガイド！初心者でもわかるテンプレートの再利用
生徒
「Thymeleafでテンプレートを再利用する方法ってありますか？」
先生
「Thymeleafにはth:includeという便利な機能があります。これを使うと、別のHTMLファイルを簡単に読み込んで再利用できるんです。」
生徒
「それって、具体的にはどういう風に使うんですか？」
先生
「それじゃあ、th:includeの基本的な使い方を詳しく見ていきましょう！」
1. th:includeとは？
Thymeleafのth:includeは、複数のページで共通して使われるパーツを外部ファイルとして管理し、必要な場所へ読み込むための属性です。例えば、ヘッダー・フッター・サイドバーなど、どのページにも存在する共通レイアウトを別ファイルに分割しておくことで、同じHTMLを繰り返し書く必要がなくなり、修正・更新作業が大幅に効率化されます。
特に「ページデザインを後から変更したい」「一部分だけ更新したい」といった場面で効果を発揮します。共通要素を1箇所にまとめておくことで、全ページに一括反映でき、保守性・再利用性が高いテンプレート設計が可能になります。
以下は、初心者向けに非常にシンプルな例です。ヘッダー部分をheader.htmlとして切り出し、main.html側で読み込んで表示します。
<!-- main.html -->
<div th:include="fragments/header :: headerFragment"></div>
<p>ここがメインページの本文になります。</p>
<!-- fragments/header.html -->
<div th:fragment="headerFragment">
<header>
<h2 id="mokuji_2">サイト共通ヘッダー</h2><!-- ここに画像を追加 ★NoImageはあとで書き換え★ -->
<div class="position-relative text-center image-overlay mb-3">
<img src="/img/view/java-exception-introduce-02.jpg?1" class="img-fluid" alt="サイト共通ヘッダー" onerror="this.onerror=null; this.src='/img/view/java-exception-introduce.jpg';">
<div class="overlay"></div>
<div class="position-absolute top-50 start-50 translate-middle text-white fw-bold img-overlay-text2">サイト共通ヘッダー</div>
</div>
<p>どのページにも表示される部分です。</p>
</header>
</div>
このように、ヘッダーを別ファイルに分けてth:includeで読み込むだけで、ページ間で同じ内容を再利用できるようになります。後からメニューを追加したりデザインを変えたい場合でも、header.htmlを更新するだけで全ページが自動で更新されるため、開発や運用が格段に楽になります。
2. th:includeの基本的な使い方
まずは、th:includeを使って、HTMLテンプレートを読み込む基本的な方法を紹介します。以下の例では、header.htmlというファイルをメインのテンプレートに読み込んでいます。
<!-- main.html -->
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
<title>Thymeleafのth:include例</title>
</head>
<body>
<!-- ヘッダーを読み込む -->
<div th:include="fragments/header :: headerFragment"></div>
<h1>メインコンテンツ</h1>
<!-- フッターを読み込む -->
<div th:include="fragments/footer :: footerFragment"></div>
</body>
</html>
<!-- fragments/header.html -->
<div th:fragment="headerFragment">
<header>
<h2>サイトのヘッダー</h2>
<nav>
<ul>
<li><a href="/">ホーム</a></li>
<li><a href="/about">会社概要</a></li>
<li><a href="/contact">お問い合わせ</a></li>
</ul>
</nav>
</header>
</div>
<!-- fragments/footer.html -->
<div th:fragment="footerFragment">
<footer>
<p>© 2024 My Website</p>
</footer>
</div>
上記のようにth:includeを使うことで、ヘッダーやフッターを簡単に読み込むことができます。
3. th:includeとth:replaceの違い
th:includeとth:replaceは似たような機能を持っていますが、動作に違いがあります。
- th:include: 読み込んだテンプレートの内容を、その要素の中に挿入します。
- th:replace: 読み込んだテンプレート全体で元の要素を置き換えます。
例えば、th:includeを使うと、<div>要素の中にコンテンツが追加されますが、th:replaceでは<div>要素自体が置き換えられます。シチュエーションに応じて使い分けましょう。
4. パラメータを渡す方法
th:includeでは、パラメータを渡して動的にコンテンツを変更することもできます。例えば、以下のように動的なデータを渡して、再利用性の高いテンプレートを作成できます。
<!-- main.html -->
<div th:include="fragments/message :: messageFragment (msg='こんにちは！')"></div>
<!-- fragments/message.html -->
<div th:fragment="messageFragment (msg)">
<p>メッセージ: [[${msg}]]</p>
</div>
この場合、メインのHTMLに「メッセージ: こんにちは！」と表示されます。
5. th:includeを使うときの注意点
th:includeを使う際には、以下の点に注意しましょう。
- ファイルパスが間違っていると、テンプレートが正しく読み込まれません。
classpath:からのパス指定を確認しましょう。 - 読み込むテンプレートファイルは必ずUTF-8で保存してください。
これらのポイントを押さえることで、エラーを未然に防ぎ、スムーズな開発が可能です。
6. th:includeを使ったレイアウト設計のベストプラクティス
th:includeを活用することで、ヘッダーやフッターだけでなく、サイドバー、パンくずリスト、共通ボタンなど、UIコンポーネントを細かく分割し、再利用可能なテンプレートとして管理できます。特に大規模なWebアプリケーションでは、複数の画面で共通するパーツをテンプレート化することで、保守性や拡張性が向上します。
ベストプラクティスとして、共通パーツを「fragments」ディレクトリにまとめ、役割ごとにファイルを分割すると管理しやすくなります。また、変更を行う際はテンプレートを一箇所修正するだけで全ページに反映されるため、デザイン変更や仕様変更にも強い構造となります。
7. th:includeと条件分岐を組み合わせて使う方法
th:includeは、条件分岐と組み合わせることで動的に読み込むテンプレートを切り替えることができます。例えば、ログインユーザーと未ログインユーザーで異なるヘッナ゙ーを表示したり、ページの種類に応じて別々のレイアウトを適用することができます。
条件分岐には、Thymeleafのth:ifやth:switchを使用します。これにより、HTML全体を変更せずに柔軟なUI表示が可能になります。特に会員制サイトやダッシュボード画面では、ユーザーの権限に応じて動的に表示内容を変える場合に非常に有効です。
8. th:includeが機能しないときに確認すべきポイント
th:includeが期待通り動作しない場合、主に以下の点を確認する必要があります。まず、テンプレートファイルのパスが適切に設定されているか確認しましょう。Thymeleafでは、resources/templates配下からのパス指定が基本となります。また、th:fragmentの名前が一致していないと正しく読み込まれません。
さらに、Thymeleafのテンプレートエンジンが有効になっているか、HTMLファイルが正しいエンコーディング（UTF-8）で保存されているかも重要です。特に日本語を使用する場合、文字コードの不一致が原因で表示されないケースがあります。
これらのポイントを確認することで、エラーの原因を特定しやすくなり、スムーズにテンプレートを再利用できるようになります。
まとめ
ここまで、Thymeleafのth:includeについて、基本的な使い方からパラメータの渡し方、th:replaceとの違い、さらには注意点まで詳しく解説してきました。th:includeを活用することで、HTMLテンプレートの再利用性を高め、メンテナンス性を大幅に向上させることができます。特に、大規模なWebアプリケーションでは、共通パーツ（ヘッダーやフッターなど）を個別に管理することで、修正や更新が非常に効率的になります。
例えば、数十ページにわたるWebサイトであっても、ヘッダー部分を1つのheader.htmlに集約し、それをth:includeで読み込むことで、すべてのページのヘッダーを一括で更新できます。これにより、手作業での修正ミスが減り、開発効率も向上します。また、テンプレートエンジンとしてのThymeleafの強力な点は、HTMLファイルがそのままブラウザで表示できるため、デザイナーとエンジニアのコラボレーションが円滑に進む点です。
一方で、th:includeを使う際の注意点も忘れずに。特にファイルパスの指定ミスや、パラメータの渡し方に気をつける必要があります。正しく設定すれば、動的なデータを柔軟にテンプレートに反映させることができ、非常に便利です。今後、より複雑な動的Webアプリケーションを開発する際にも、今回学んだ知識が役立つでしょう。
<!-- main.html -->
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
<title>復習: th:includeの再利用</title>
</head>
<body>
<div th:include="fragments/header :: headerFragment"></div>
<h1>再利用の重要性を理解しよう！</h1>
<div th:include="fragments/message :: messageFragment (msg='再利用されたメッセージです')"></div>
<div th:include="fragments/footer :: footerFragment"></div>
</body>
</html>
<!-- fragments/message.html -->
<div th:fragment="messageFragment (msg)">
<p>メッセージ: [[${msg}]]</p>
</div>
このようにth:includeを使えば、HTMLコンポーネントを効率的に再利用できます。もしサイト全体の一貫性を保ちたい場合、th:includeは非常に役立つツールとなるでしょう。是非、様々なプロジェクトで活用してみてください。
生徒
「今日のまとめを聞いて、th:includeがすごく便利なものだとわかりました！」
先生
「そうですね。特に大規模なプロジェクトでは、テンプレートの再利用は作業効率を上げるために重要です。時間の節約にもなりますからね。」
生徒
「あと、th:replaceとの違いも覚えておくと役に立ちそうです！」
先生
「その通りです。状況に応じてth:includeとth:replaceを使い分けることで、さらに柔軟なテンプレート設計ができますよ。」
生徒
「これから自分のプロジェクトでも活用してみます！たくさんのページを持つサイトでも管理が楽になりそうです。」
先生
「ぜひ挑戦してみてください。もしわからないことがあれば、いつでも質問してくださいね。」
この記事を読んだ人からの質問
プログラミング初心者からのよくある疑問／質問を解決します
th:includeとは何ですか？どんな場面で使いますか？
th:includeは、ThymeleafでHTMLテンプレートを再利用するための属性です。ヘッダーやフッターなど、複数ページで共通する部分を効率的に管理する際に使います。
th:includeを使うメリットは何ですか？
HTMLコードの重複を減らし、メンテナンス性が向上します。一箇所修正するだけで、全ページに変更を反映できるため、効率的な開発が可能です。
th:includeとth:replaceの違いは何ですか？
th:includeは、読み込んだテンプレートの内容を現在の要素内に挿入します。一方、th:replaceは現在の要素をテンプレートの内容で置き換えます。
th:includeを使う際に注意する点は何ですか？
テンプレートのファイルパスを正しく指定すること、UTF-8形式で保存することが重要です。パスが間違っているとテンプレートが正しく読み込まれません。
th:includeでパラメータを渡す方法を教えてください。
th:includeでは、(paramName='value')の形式でパラメータを渡すことができます。テンプレート側では、th:fragmentに(paramName)を指定してパラメータを受け取ります。
ヘッダーやフッターを再利用するにはどうすれば良いですか？
ヘッダーやフッターを個別のHTMLファイルとして作成し、th:includeを使って必要なページで読み込むことで再利用が可能です。
大規模なWebアプリケーションでth:includeをどのように活用できますか？
th:includeを使うことで、共通部分（例: ナビゲーションバー、フッター）を個別に管理し、効率的にサイト全体の一貫性を保つことができます。
th:includeを使うことでメンテナンス性はどう向上しますか？
共通部分を1箇所にまとめて管理できるため、変更が必要な場合はその部分だけ修正すれば全ページに反映されます。これにより、更新作業の手間が大幅に減ります。
th:includeを使った実践的な例を教えてください。
ログインフォームや商品カードをフラグメント化し、必要なページでth:includeを使って呼び出すことで、効率的に再利用できます。
th:includeを使う際のベストプラクティスは何ですか？
テンプレートを適切なディレクトリ構造に配置し、わかりやすい名前をつけることが重要です。また、ファイルパスの指定を正確に行い、パラメータを活用して柔軟な再利用を実現しましょう。
職業訓練講師が直伝！Thymeleaf実践。Spring Bootと連携する「保守性・UX最大化」の画面構築術。
累計120万PV超の技術メディア運営チームが贈る、商用開発基準の特別カリキュラム
職業訓練講師が直伝！Thymeleaf実践。Spring Bootと連携する「保守性・UX最大化」の画面構築術。
Spring Boot標準のテンプレートエンジンとして、Java開発の現場で不可欠なThymeleaf。本講座では、HTMLの構造を維持する「ナチュラルテンプレート」の利点を活かし、Controllerとのセキュアなデータ連携や、コンポーネント化による圧倒的な保守性を60分で濃縮習得します。
60分集中ワークショップ内容
【つくるもの】
Spring Boot 3.xと連動した「実務型ダッシュボード画面」を構築。フォームバリデーション連携、フラグメント（共通部品）化、ユーティリティオブジェクトによる高度なフォーマット処理など、現場で即戦力として評価される実装コードを組み上げます。
【開発環境】
Spring Boot 3.x / DevTools環境を使用。「LiveReload」による高速開発セットアップや、Thymeleaf特有のデバッグ技法など、実務10年PLが実践する「開発ストレスをゼロにする」プロの知恵を伝授します。
この60分で得られる3つの革新スキル
classの動的切り替えやリンク生成（@{}）を自在に操り、ロジックとデザインを美しく分離します。
th:replace / th:insert を駆使し、修正に強いスケーラブルなUIコンポーネント設計を学びます。
ログインユーザーの権限に応じたボタンや項目の制御など、実務で必須のセキュリティ連携を習得します。
※本講座は、Spring Bootの基本を知り、さらに「表現力豊かな商用UI」を作りたい方向けの「フルスタックUI実装講座」です。フロントとバックを繋ぐ橋渡し役として、市場価値を高めたい方を職業訓練講師が全力でバックアップします。
20名規模のプロジェクトリーダー（PL）が、トラブルを防ぐ実装ノウハウを直接伝授します。
