Thymeleafのfragmentの使い方とメリットを初心者向けに解説！テンプレートの共通化で開発効率アップ

【Thymeleaf】fragmentのメリットと活用例まとめ

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

新人

「先輩、Thymeleafで画面を作っているんですが、同じヘッダーやフッターを毎回コピペするのが面倒で……。」

先輩

「それなら、fragmentを使うと便利だよ。Thymeleafではテンプレートの共通部分を切り出して再利用できる仕組みがあるんだ。」

新人

「fragmentって、具体的にどうやって使うんですか？」

先輩

「じゃあ、まずはThymeleafのfragmentとは何かを説明するね。その後、メリットや使い方も詳しく教えるよ。」

1. Thymeleafのfragmentとは？

Thymeleafのfragmentとは、HTMLテンプレートの中で共通して使いたいパーツ（ヘッダーやフッターなど）を別ファイルに切り出し、他のテンプレートで再利用できる機能です。Spring Bootで画面を作るとき、同じコードを何度も書かずに済むので、保守性や可読性が向上します。

例えば、次のようなheaderを定義するHTMLがあります。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>共通ヘッダー</title>
</head>
<body>
    <div th:fragment="header">
        <h1>社内ポータルサイト</h1>
        <nav>
            <a th:href="@{/home}">ホーム</a> |
            <a th:href="@{/profile}">プロフィール</a>
        </nav>
    </div>
</body>
</html>

このth:fragment="header"で定義した部分を、別のテンプレートから読み込んで使うことができます。

呼び出す側のテンプレートでは以下のように記述します。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>トップページ</title>
</head>
<body>
    <div th:replace="fragments/header :: header"></div>
    <p>ようこそ、社内ポータルへ！</p>
</body>
</html>

これで、header部分はfragments/header.htmlという別ファイルに記述されているものを読み込んで表示することができます。

2. fragmentを使うメリット

Thymeleafのfragmentを使うことで、テンプレートの再利用が可能になります。以下に主なメリットを紹介します。

① コードの共通化で効率アップ

共通部分をfragment化することで、ヘッダー・フッター・メニューなどのコードを一か所にまとめることができ、同じコードを何度も書く必要がなくなります。

② 保守性の向上

デザイン変更などが発生した場合、fragmentの元ファイルを修正すれば、すべての画面に自動で反映されます。数十ページあるWebアプリでも、効率よく変更できます。

③ コードの見通しが良くなる

テンプレートの構成がすっきりして読みやすくなります。個別画面では必要な要素だけに集中でき、共通レイアウト部分は別管理が可能になります。

④ テンプレート構造の分離で責務分割

画面ごとのレイアウトだけに集中できるため、チーム開発でも分担作業がしやすくなります。デザイン担当とロジック担当の役割も明確になります。

⑤ テストやデバッグが簡単になる

共通部分の不具合をfragmentファイル単体で確認できるため、デバッグの際に原因切り分けがスムーズになります。

実際にSpring Bootで開発するときは、以下のように@Controllerを使って画面にデータを渡しながらテンプレートを表示します。


@Controller
public class HomeController {

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

このhome.htmlテンプレートで、先ほどのheaderフラグメントを読み込むことで、簡潔で再利用性の高い画面を作ることができます。

このようにThymeleafのfragmentは、初心者でも取り入れやすく、コードの保守性や拡張性を高める非常に有効な機能です。

3. fragmentの活用例（共通ヘッダー・フッターなど）

それでは、Thymeleafのfragmentを実際にどのように活用するのか、具体的な例を見ていきましょう。初心者の方にもわかりやすいように、画面の上部に表示されるヘッダー、下部に表示されるフッター、それぞれをfragmentとして作成し、画面全体で共通化して使う方法を紹介します。

① 共通ヘッダーの定義

まずは、fragments/header.htmlに共通ヘッダーを定義します。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<body>
    <div th:fragment="header">
        <header>
            <h1>社員情報システム</h1>
            <nav>
                <a th:href="@{/home}">ホーム</a> |
                <a th:href="@{/about}">会社情報</a> |
                <a th:href="@{/contact}">お問い合わせ</a>
            </nav>
            <hr>
        </header>
    </div>
</body>
</html>

② 共通フッターの定義

次に、fragments/footer.htmlとして、ページ下部に配置するフッター部分を用意します。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<body>
    <div th:fragment="footer">
        <footer>
            <hr>
            <p>&copy; 2025 社員情報システム All rights reserved.</p>
        </footer>
    </div>
</body>
</html>

③ 各画面での呼び出し

上記で作成した共通ヘッダー・フッターを、実際の画面テンプレートで読み込んで使います。たとえば、home.htmlでは以下のように記述します。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>ホーム画面</title>
</head>
<body>

    <div th:replace="fragments/header :: header"></div>

    <main>
        <h2>ようこそ</h2>
        <p>社員情報システムへようこそ。</p>
    </main>

    <div th:replace="fragments/footer :: footer"></div>

</body>
</html>

このように、th:replaceでfragmentを呼び出すことで、各画面のテンプレートに共通パーツを簡単に取り込めます。

4. 実際のHTML構成とプロジェクト構造（テンプレートファイルの配置）

初心者の方がつまずきやすいのが、ファイルの配置場所です。PleiadesでGradleプロジェクトを作成した場合、Thymeleafのテンプレートファイルはsrc/main/resources/templates以下に置く必要があります。

以下に、Thymeleafのfragmentを活用するためのプロジェクト構造の例を紹介します。


src/
└── main/
    └── resources/
        └── templates/
            ├── fragments/
            │   ├── header.html
            │   └── footer.html
            ├── home.html
            └── about.html

fragmentsフォルダの中に、共通化したいheader.htmlやfooter.htmlなどのテンプレートをまとめておくと、他のテンプレートから参照しやすくなります。

そして、例えばabout.htmlでも、同じようにth:replaceを使って共通パーツを読み込むことができます。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>会社情報</title>
</head>
<body>

    <div th:replace="fragments/header :: header"></div>

    <main>
        <h2>会社概要</h2>
        <p>私たちは高品質なITサービスを提供しています。</p>
    </main>

    <div th:replace="fragments/footer :: footer"></div>

</body>
</html>

テンプレートファイルの構成をしっかり整理しておくことで、メンテナンス性が大幅に向上し、画面全体の一貫性も保つことができます。

また、@Controllerを用いたコントローラークラスでは、表示する画面の名前を文字列で返すことで、Thymeleafテンプレートを自動的に探して表示してくれます。以下にAboutControllerの例を示します。


@Controller
public class AboutController {

    @GetMapping("/about")
    public String about() {
        return "about";
    }
}

このように、画面の構成とコントローラーの連携を正しく設計することで、初心者でも簡単にThymeleafのfragmentを活用できるようになります。

開発初期から共通化の考え方を取り入れておくことで、プロジェクトが大きくなっても安心して拡張できるのがfragmentの大きな魅力です。Pleiades環境でGradleを使った開発でも、テンプレートの配置と呼び出し方を正しく行えば、問題なく動作させることができます。

特に初心者の方は、th:replaceやth:fragmentの書き方に慣れるまでは、サンプルを参考にしながら実際に手を動かして試してみるのが効果的です。

5. fragmentの応用テクニック（パラメータ渡し・動的読み込みなど）

ここでは、初心者の方にもぜひ知っておいてほしいThymeleafのfragmentの応用的な使い方を紹介します。基本的な使い方をマスターした後は、パラメータ渡しや動的な内容の差し込みといったテクニックを活用することで、さらに柔軟で効率的な画面構成が実現できます。

① fragmentにパラメータを渡す

Thymeleafでは、fragmentに値を渡して表示内容を切り替えることができます。たとえば、ヘッダーにユーザー名などを表示したい場合は、次のように記述します。

fragments/header.html


<div th:fragment="header(userName)">
    <header>
        <h1>ようこそ [[${userName}]] さん</h1>
        <nav>
            <a th:href="@{/home}">ホーム</a> |
            <a th:href="@{/logout}">ログアウト</a>
        </nav>
        <hr>
    </header>
</div>

このfragmentは、呼び出し側でユーザー名を指定して表示できます。

home.html


<div th:replace="fragments/header :: header('田中 太郎')"></div>

これにより、ログインユーザー名などを動的に表示させることが可能になります。テンプレートの再利用性も高まり、共通部分でも柔軟な対応ができます。

② th:include と th:replace の違い

th:includeは、fragment内のdivなどの中身だけを埋め込む方法です。一方でth:replaceは、タグごと丸ごと置き換えます。ケースに応じて使い分けることが大切です。

th:include の例：


<div class="box" th:include="fragments/banner :: bannerText"></div>

th:replace の例：


<div th:replace="fragments/banner :: bannerText"></div>

初心者のうちはth:replaceで統一しておくのがおすすめですが、構造を意識できるようになったら使い分けるとより効率的です。

③ fragmentの中で条件分岐を使う

Thymeleafではth:ifやth:unlessを使って、表示の切り替えもできます。たとえば、ユーザーが管理者かどうかでナビゲーションを出し分けるような処理も可能です。


<nav th:fragment="menu(userRole)">
    <a th:href="@{/home}">ホーム</a>
    <a th:href="@{/profile}">プロフィール</a>
    <a th:href="@{/admin}" th:if="${userRole == 'admin'}">管理者メニュー</a>
</nav>

このように、条件に応じて表示内容を動的に切り替えることで、同じテンプレートでもさまざまな画面構成に対応できます。

6. fragmentを活用した効率的な画面設計のポイント

最後に、Thymeleafのfragmentを活用して効率の良い画面設計を行うためのポイントを初心者向けに解説します。PleiadesでGradle構成のプロジェクトを作るときにも活かせる内容です。

① 設計段階から共通パーツを意識する

プロジェクトを始める段階から、「この部分は複数の画面で共通して使うかもしれない」と考えて、headerやfooter、menuなどの共通要素はfragmentとして分けておきましょう。後から変更が入ったときにも一括で対応できるため、効率よく開発できます。

② fragmentは機能単位で細かく分ける

一つのfragmentにすべての要素を詰め込むと、管理がしづらくなります。できるだけ機能ごとに分けて、小さなパーツ単位で再利用できるようにしましょう。

たとえば以下のように役割ごとに分けて整理すると、テンプレートの構造がわかりやすくなります。


templates/
├── fragments/
│   ├── header.html
│   ├── footer.html
│   ├── menu.html
│   └── banner.html
├── home.html
├── about.html
└── contact.html

③ fragmentを使ってレイアウトを共通化する

Thymeleafでは、画面全体のレイアウトもfragmentで共通化できます。ベースレイアウトを用意し、ページごとに異なるコンテンツを差し込む形にすれば、統一感のあるUIが実現できます。


<!-- fragments/layout.html -->
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title th:text="${pageTitle}">タイトル</title>
</head>
<body>
    <div th:replace="fragments/header :: header"></div>

    <main>
        <div th:fragment="content"></div>
    </main>

    <div th:replace="fragments/footer :: footer"></div>
</body>
</html>

このようなレイアウトをベースにして、実際の画面ではth:replaceを使って個別の内容を差し込むことができます。


<!-- home.html -->
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<body>
    <div th:replace="fragments/layout :: content">
        <h2>トップページ</h2>
        <p>ここがメインコンテンツです。</p>
    </div>
</body>
</html>

このように、共通レイアウト＋個別内容という構成にすることで、変更があった場合にも個別ファイルへの影響を最小限に抑えられます。

④ fragmentの命名ルールを統一する

fragmentを多く作ると、呼び出しミスが起きやすくなります。fragments/header.htmlの中ではheader、menu.htmlならmenuといったように、テンプレート名とfragment名を一致させると、管理がしやすくなります。

⑤ fragmentは見た目よりも構造を重視

初心者のうちはデザインよりコードの構造に注目しましょう。HTMLが整理されていれば、後からデザイン変更があっても簡単に対応できます。まずは「見やすく、再利用しやすい」構成を目指すことが大切です。

以上のように、Thymeleafのfragmentを上手に使えば、初心者でも効率よく保守性の高い画面設計が可能になります。PleiadesとGradleの開発環境でも、テンプレートを整理して活用するだけで、大きなプロジェクトにも対応できるようになります。

まとめ

Thymeleafのfragmentを理解することの重要性

本記事では、Thymeleafのfragment機能について、初心者の方にも理解しやすいように基礎から応用まで順を追って解説してきました。 fragmentとは、画面の中で何度も使われる共通部分を切り出し、別ファイルとして管理しながら再利用できる仕組みです。ヘッダーやフッター、メニューといった共通レイアウトをfragmentとして管理することで、HTMLテンプレート全体の構造が整理され、可読性と保守性が大きく向上します。

特にSpring BootとThymeleafを組み合わせたWebアプリケーション開発では、画面数が増えるほど共通部分の管理が課題になります。 fragmentを使わずにコピーペーストを繰り返してしまうと、修正漏れや不具合の原因になりやすく、開発効率も徐々に低下してしまいます。 fragmentを正しく理解し、設計段階から共通化を意識することで、初心者の方でも安定した画面開発ができるようになります。

fragmentによる開発効率と保守性の向上

fragmentの最大のメリットは、修正箇所を一か所に集約できる点です。例えばヘッダーの文言やナビゲーションを変更したい場合でも、 fragmentファイルを修正するだけで全画面に反映されます。これは個人開発だけでなく、チーム開発においても非常に大きな利点となります。

また、fragmentを活用することで、HTMLテンプレートが「共通部分」と「画面固有部分」に自然と分離されます。その結果、各画面のHTMLは本当に必要な内容だけが記述されるようになり、初心者の方でも画面構造を把握しやすくなります。コードを読む側の負担が減ることで、レビューや引き継ぎもスムーズに進みます。

まとめとしてのサンプル構成例

記事全体を通して紹介してきた内容を踏まえると、 Thymeleafのfragmentは以下のような構成で使うのが現実的です。共通ヘッダーと共通フッターをfragmentとして定義し、各画面ではth:replaceを使って読み込む形が基本になります。


<!-- fragments/header.html -->
<div th:fragment="header">
    <header>
        <h1>業務管理システム</h1>
        <nav>
            <a th:href="@{/home}">ホーム</a>
            <a th:href="@{/about}">概要</a>
        </nav>
    </header>
</div>


<!-- home.html -->
<div th:replace="fragments/header :: header"></div>
<main>
    <p>ここに画面固有の内容を記述します。</p>
</main>

このような形でfragmentを活用することで、HTMLテンプレートの役割が明確になり、初心者でも無理なく設計を理解できるようになります。 fragmentは単なる便利機能ではなく、画面設計そのものを整理するための考え方だと捉えると、より自然に使いこなせるようになります。

初心者が意識したいfragment活用のポイント

初めてfragmentを使う場合は、完璧を目指さず、まずはヘッダーやフッターなど分かりやすい部分から共通化するのがおすすめです。実際に動かしながら「ここは共通にできそうだ」と気づいた部分をfragmentに切り出していくことで、少しずつ理解が深まっていきます。

また、fragment名とファイル名を揃えること、 fragmentsフォルダにまとめて配置することなど、基本的なルールを決めておくと迷いにくくなります。こうした小さな工夫の積み重ねが、後々の開発を楽にしてくれます。

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

生徒

「fragmentを使うことで、同じHTMLを何度も書かなくてよくなる理由がよく分かりました。今までコピーペーストしていたのが、少し怖くなりました。」

先生

「それに気づけたのは大きな成長だね。 fragmentは手を抜くための仕組みではなく、きれいな構造を保つための道具なんだ。」

生徒

「最初は難しそうに見えましたが、ヘッダーやフッターから始めれば初心者でも使えそうだと感じました。」

先生

「その通り。小さな共通化を積み重ねることで、自然と保守性の高い画面設計ができるようになる。 Thymeleafのfragmentは、その第一歩としてとても良い学習テーマだよ。」

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

プログラミング初心者からのよくある疑問／質問を解決します

Thymeleaf（タイムリーフ）のfragment（フラグメント）とは、具体的にどのような機能で、どんなメリットがあるのでしょうか？初心者にも分かりやすく教えてください。

Thymeleafのfragment（フラグメント）は、一言で言うと「Webサイトの共通パーツを使い回すための部品化機能」です。例えば、Webサイトにはどのページにも必ず表示される「ヘッダー（画面上部）」や「フッター（画面下部）」、「サイドメニュー」などがあります。これらをページごとに毎回コピー＆ペーストして記述するのは非常に効率が悪く、修正が必要になった際にすべてのファイルを直さなければなりません。そこで、fragment機能を使って共通部分を別ファイルに切り出しておけば、一つの部品を呼び出すだけで複数の画面に同じ内容を表示できるようになります。メリットとしては、コードの記述量が減って開発効率が劇的にアップすること、修正が一箇所で済むため保守性が向上すること、そしてソースコードが整理されて読みやすくなることなどが挙げられます。Spring Boot（スプリングブート）を活用したWebアプリ開発において、テンプレートの共通化は必須のテクニックです。