Thymeleafのfragmentとは？基本の使い方をやさしく解説【初心者向け完全ガイド】
新人
「最近Thymeleafを使っていて、fragmentっていうのを見かけたんですけど、何のことですか？」
先輩
「fragmentはThymeleafで使えるテンプレートの一部を切り出して再利用できる機能なんだ。共通のヘッダーやフッターを分けて使いたいときに便利だよ。」
新人
「共通のパーツって、毎回コピーして書いてたんですけど、それを避けられるってことですか？」
先輩
「その通り。fragmentを使えば、繰り返し使うHTML部分を一箇所にまとめて、必要なところから読み込むだけで済むんだ。実際の使い方を見ながら詳しく説明していこう！」
1. Thymeleafのfragmentとは何か
Thymeleafのfragmentとは、HTMLの一部分を部品のように切り出して、他のテンプレートファイルから再利用できる仕組みです。たとえば、Webページのヘッダーやフッター、共通のメニューなど、複数の画面で使う要素を一つのテンプレートにまとめて管理できます。
通常のHTMLでは、ページごとに同じコードをコピー＆ペーストすることが多く、修正が発生したときに全ページを編集しなければならないという手間が生まれます。Thymeleafのfragmentを使えば、共通部分を一箇所に集約しておけるので、修正も一度で済み、保守性が高まります。
また、fragmentはSpring Frameworkとの連携にも強く、@Controllerで渡したデータと組み合わせて柔軟な画面表示が可能です。PleiadesでGradle構成のSpringプロジェクトを作成すれば、依存関係の追加もチェックボックスで簡単に行えます。
2. fragmentを使うメリット
Thymeleafでfragmentを使う最大のメリットは、HTMLテンプレートの共通化と再利用性の向上にあります。具体的には次のような利点があります。
① 共通パーツの一元管理
たとえば、Webサイトのすべてのページで共通のナビゲーションメニューを使う場合、fragmentを使えばそのメニューを別ファイルに切り出して再利用できます。こうすることで、修正があった際に1つのファイルを変更するだけで全ページに反映されます。
② コードの重複を防げる
HTMLをコピー＆ペーストで管理していると、ほんの少しの変更でも複数のファイルに手を加える必要が出てきます。fragmentを使えば同じ内容を何度も書かなくてよくなるため、開発効率がアップします。
③ 見通しのよいテンプレート構成
テンプレートを機能ごとに分割できるため、1つのHTMLファイルが長くなりすぎることを防げます。これは初心者にとってもコードの構造が理解しやすくなるという大きなメリットです。
④ 保守性と拡張性の向上
将来的にデザインを変更する場合でも、fragmentで共通化された部分を修正するだけで複数の画面に反映されるため、メンテナンスのコストを大幅に削減できます。また、新しいページを作る際にも、既存のfragmentを使えば構築が早くなります。
⑤ Springとの親和性が高い
Spring MVCとThymeleafは非常に相性がよく、@Controllerで返したテンプレート内でfragmentを自然に呼び出せます。開発環境としては、Pleiades＋Gradle構成のプロジェクトを作成し、テンプレートファイルをsrc/main/resources/templatesに配置すれば簡単に利用できます。
このように、Thymeleafのfragment機能は、初心者が効率的にテンプレート開発を進めるうえで非常に役立つツールです。特に複数ページを持つアプリケーションでは、その効果を強く実感できるでしょう。
3. fragmentの作り方（HTMLファイルでの定義方法）
それでは、Thymeleafにおけるfragmentの定義方法について詳しく見ていきましょう。fragmentを作るには、テンプレートファイル内にth:fragmentという属性を使って、再利用可能なHTMLパーツをマークアップします。
たとえば、共通のヘッダー部分をheader.htmlというファイルに定義する場合、以下のように記述します。
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<body>
<div th:fragment="siteHeader">
<header>
<h1>サンプルサイト</h1>
<nav>
<a href="/">ホーム</a> |
<a href="/about">このサイトについて</a>
</nav>
</header>
</div>
</body>
</html>
th:fragment="siteHeader"と書くことで、「siteHeader」という名前のfragmentとして定義できます。この部分は他のテンプレートから呼び出すことができるようになります。
ポイントは、fragmentを記述するHTMLは通常のテンプレートファイルと同じように扱えるという点です。ファイル名や配置場所は特に制限がありませんが、慣例としてはfragmentsフォルダをtemplates配下に作成し、その中に配置すると管理しやすくなります。
4. fragmentの読み込み方法（layout:fragmentやth:replaceなどの使い方）
定義したfragmentを他のテンプレートから読み込むには、th:insertやth:replace、th:includeなどの属性を使います。ここではよく使われるth:replaceを使った方法を紹介します。
たとえば、main.htmlというファイルの中で、先ほど作成したsiteHeaderを読み込む場合、以下のように書きます。
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<body>
<div th:replace="fragments/header :: siteHeader"></div>
<main>
<p>これはメインコンテンツの領域です。</p>
</main>
</body>
</html>
th:replace="fragments/header :: siteHeader"は、「templates/fragments/header.html」ファイル内にあるth:fragment="siteHeader"の内容をここに差し込むという意味です。::で区切って、ファイル名とfragment名を指定するのが基本形になります。
th:replace と th:insert の違い
- th:replace：呼び出し元の要素ごと置き換える
- th:insert：呼び出し元の要素の中にfragmentの内容を挿入する
ほとんどの場合、th:replaceを使うとHTMLがすっきりしやすくおすすめです。divやsectionなどで囲んで使う際も柔軟に対応できます。
レイアウト用の共通テンプレートと組み合わせる
実際の開発では、共通レイアウトファイルを作り、その中にヘッダーやフッターのfragmentを定義して、それをすべての画面で呼び出すという使い方が一般的です。
たとえば、共通レイアウトに以下のような記述をすることができます。
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
<title>共通レイアウトの例</title>
</head>
<body>
<div th:replace="fragments/header :: siteHeader"></div>
<div th:replace="${content}"></div>
<div th:replace="fragments/footer :: siteFooter"></div>
</body>
</html>
このように構成しておくことで、各ページごとに個別のコンテンツだけを用意し、レイアウト部分は共通のテンプレートを使いまわすことができます。これはアプリケーションのスケーラビリティを高めるうえでも非常に有効なアプローチです。
このように、fragmentを定義して読み込む方法を理解することで、Thymeleafを使ったWebアプリケーション開発がより効率的になります。特にPleiadesとGradle構成で開発する場合、テンプレートの構造を明確にし、コードの見通しをよくするためにfragmentの活用は欠かせない手法となります。
5. fragmentを使った画面構成の具体例（共通ヘッダー・フッター）
Thymeleafのfragmentを使うと、画面全体の構成を効率的に管理できます。特に共通ヘッダーやフッターのように、すべてのページで同じ内容を表示したい部分に活用するのが一般的です。
ここでは、共通レイアウトを構成する具体例として、header.htmlとfooter.htmlのfragmentを作成し、それをmain.htmlに読み込んで画面を構成する方法を紹介します。
ヘッダーのfragment（header.html）
<div th:fragment="siteHeader">
<header>
<h1>サンプルアプリケーション</h1>
<nav>
<a href="/">ホーム</a> |
<a href="/profile">プロフィール</a>
</nav>
</header>
</div>
フッターのfragment（footer.html）
<div th:fragment="siteFooter">
<footer>
<p>© 2025 Sample Inc.</p>
</footer>
</div>
メインテンプレート（main.html）
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
<meta charset="UTF-8">
<title>メインページ</title>
</head>
<body>
<div th:replace="fragments/header :: siteHeader"></div>
<main>
<h2>メインコンテンツ</h2>
<p>これはメインエリアのコンテンツです。</p>
</main>
<div th:replace="fragments/footer :: siteFooter"></div>
</body>
</html>
このように、共通化されたヘッダーとフッターをfragmentとして定義し、画面ごとに再利用することで、全体のHTML構造がスッキリと整理され、保守性も大きく向上します。
6. fragmentの応用テクニック（動的パラメータの渡し方、th:fragmentの使い分け）
ここからは、Thymeleafのfragment機能をさらに活用するための応用テクニックを紹介します。特に動的な値をfragmentに渡す方法や、th:fragmentの記述パターンについて解説します。
動的パラメータをfragmentに渡す
たとえば、ボタンやタイトルなどを動的に変えたいとき、fragment側で変数を受け取って処理することができます。以下に例を示します。
ボタンのfragment（button.html）
<div th:fragment="button(label)">
<button type="button">[[${label}]]</button>
</div>
呼び出し側のテンプレート
<div th:replace="fragments/button :: button('登録する')"></div>
このように、buttonというfragmentに対して'登録する'という引数を渡すことで、ボタンのラベルが動的に変化します。
この仕組みを利用すれば、複数の画面で異なる文言を持つ同一デザインの部品を再利用できます。
複数の要素をまとめて渡す（複数引数）
<div th:fragment="card(title, message)">
<div class="card">
<h3>[[${title}]]</h3>
<p>[[${message}]]</p>
</div>
</div>
<div th:replace="fragments/card :: card('お知らせ', 'メンテナンスは明日10時です。')"></div>
引数はカンマ区切りで複数渡すことができるので、自由度の高い再利用が可能になります。
th:fragmentの使い分け
一つのファイル内に複数のfragmentを定義することも可能です。例えば、common.htmlというファイルにヘッダーとフッター両方を記述することができます。
<div th:fragment="siteHeader">
<header>共通ヘッダー</header>
</div>
<div th:fragment="siteFooter">
<footer>共通フッター</footer>
</div>
このように記述しておけば、呼び出し側ではcommon :: siteHeaderやcommon :: siteFooterとして個別に使うことができます。ファイル数を必要以上に増やしたくない場合や、関連するfragmentをまとめたい場合に有効です。
応用的な使い方も、PleiadesでのSpringプロジェクト作成時に最初から組み込んでおくと、のちの開発や保守が格段に楽になります。
このように、Thymeleafのfragmentは、基本的なHTMLの共通化だけでなく、パラメータの活用や柔軟な構成によって、テンプレートの表現力を広げる強力な仕組みです。初心者のうちからこの機能をしっかり理解して使えるようになれば、アプリケーション開発のスピードと品質は大きく向上するでしょう。
この記事を読んだ人からの質問
