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>

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