Thymeleafの#calendarsユーティリティとは？初心者向けカレンダー操作ガイド

Thymeleafの#calendarsのユーティリティ

先生と生徒の会話形式で理解しよう

生徒

「Thymeleafでカレンダーの操作を簡単に行う方法はありますか？例えば、曜日や月ごとに処理を分けるようなことがしたいです。」

先生

「はい！Thymeleafには#calendarsという便利なユーティリティが用意されています。これを使うと、カレンダー操作が簡単にできますよ。」

生徒

「具体的にはどんなことができるんですか？」

先生

「それでは、#calendarsの基本的な使い方を詳しく見ていきましょう！」

1. #calendarsユーティリティの基本

Thymeleaf（タイムリーフ）の#calendarsユーティリティは、Web画面上で日付や時刻を自由に操るための「魔法の道具箱」のような機能です。Javaの標準的なカレンダー機能と連携しており、現在の年、月、日、曜日といった情報を、プログラミング初心者の方でも直感的な記述で取得できます。

最大のメリットは、サーバー側で複雑な計算ロジックを書かなくても、HTMLテンプレート（表示画面）側だけで「今日は何年？」「今は何月？」といった動的な情報を埋め込める点にあります。これにより、運用コストの低いメンテナンス性に優れたコードを作成できます。

まずは、最もシンプルに「現在の西暦年」を表示するサンプルを見てみましょう。


<!-- 現在の西暦（4桁）を自動的に出力します -->
<p th:text="${#calendars.year()}"></p>

このコードを実行すると、システムが自動的に現在の年を計算し、画面上には「2026」のように数値が表示されます。プログラミングに慣れていない方でも、year()という単語が「年」を指していることが一目でわかるため、学習コストが非常に低いのが特徴です。

また、Thymeleafでこれらの値を扱う際は、事前にJava側で特別な設定をしなくても、#calendarsと記述するだけで即座に利用可能です。この手軽さが、企業のシステム開発や教育現場で広く採用されている理由の一つです。

2. 現在の月と曜日を取得する

Webサイトを運営していると、「今月のおすすめ商品」や「本日の担当者」のように、月や曜日に合わせて表示を切り替えたい場面が多くあります。Thymeleafの#calendarsを使えば、難しいプログラムを書かなくても、HTMLに数行加えるだけで現在の月や曜日を自動で取得できます。

まずは、最も基本的な取得方法のサンプルコードを見てみましょう。プログラミング未経験の方でも、month（月）やdayOfWeek（曜日）という英単語を知っていれば、直感的に理解できるはずです。


<!-- 現在の月を数値（1～12）で出力します -->
<p>現在は <span th:text="${#calendars.month()}"></span> 月です</p>

<!-- 現在の曜日を数値（1:日曜 ～ 7:土曜）で出力します -->
<p>現在の曜日番号は <span th:text="${#calendars.dayOfWeek()}"></span> です</p>

ここで注意したいポイントが1つあります。dayOfWeek()で取得できるのは「月曜日」という文字ではなく、1（日曜）から7（土曜）までの「数値」であるという点です。

「数値だと分かりにくい」と感じるかもしれませんが、実は数値で取得できるからこそ、「もし月曜日（2）ならこのメッセージを出す」といった条件分岐が作りやすくなります。サーバー側でJavaのDateオブジェクトをこねくり回す必要はありません。表示側のHTMLだけで完結するため、デザインの修正感覚でカレンダー機能を実装できるのが、このユーティリティの最大の魅力です。

このように、#calendarsを活用することで、ユーザーのアクセスした瞬間のタイミングに合わせた、鮮度の高い動的なコンテンツを簡単に提供できるようになります。

3. 特定の日付を基にした処理

Webアプリを開発していると、「キャンペーン期間中だけ特定のメッセージを表示したい」といった、日付に基づいた条件分岐が必要になることが多々あります。Thymeleafの#calendarsユーティリティは、こうした日付の比較処理も非常に得意です。

特に便利なのが、2つの日付を比べて「～より後か（isAfter）」や「～より前か（isBefore）」を判定する機能です。これにより、複雑なJavaのプログラムを書き換えることなく、HTML側で「イベント終了後なら表示を消す」といった制御が可能になります。

まずは、特定の日付（例：2025年1月1日）と現在時刻を比較して、表示するテキストを切り替えるシンプルな例を見てみましょう。


<!-- 2025年1月1日が現在よりも後（未来）かどうかを判定します -->
<p th:text="${#calendars.isAfter(#calendars.create(2025, 1, 1), #calendars.createNow()) ? 'これからの予定です' : '終了したイベントです'}"></p>

このコードの仕組みを詳しく解説します。まず#calendars.create(2025, 1, 1)の部分で、比較対象となる「2025年元旦」という日付データを作成しています。次にcreateNow()で「現在のシステム時刻」を取得しています。

最後にisAfterを使って、「元旦が現在よりも後の日付か？」をチェックしています。もし現在のほうが新しければ（つまり2025年を過ぎていれば）、「終了したイベントです」という文字が自動的に表示されます。

このように、#calendarsを使うことで、日付による表示制御が直感的な三項演算子（ A ? B : C という書き方）で完結します。プログラミングに詳しくないデザイナーの方でも、日付の数字を書き換えるだけで運用ができるため、現場での実用性が非常に高いテクニックです。

4. カレンダーのロジックをテンプレートに追加する

#calendarsユーティリティを使うと、カレンダー関連のロジックをテンプレート内に組み込むことができます。以下は、1か月分のカレンダーをループで表示する例です。


<ul>
    <li th:each="day : ${#numbers.sequence(1, 31)}" th:text="'日付: ' + day"></li>
</ul>

このコードでは、1日から31日までのリストが生成され、各日付が「日付: 1」などの形式で表示されます。

5. 実践例: 動的カレンダー表示

以下は、動的に現在の年と月、そして日付リストを表示する実践例です。


<p>現在の年: <span th:text="${#calendars.year()}"></span></p>
<p>現在の月: <span th:text="${#calendars.month()}"></span></p>
<ul>
    <li th:each="day : ${#numbers.sequence(1, 31)}" th:text="'日付: ' + day"></li>
</ul>

この例では、動的に生成された現在の年と月、そして1か月分の日付がリストとして表示されます。

6. #datesと#calendarsの使い分け

Thymeleafには似た機能を持つ#datesがありますが、#calendarsはJavaのjava.util.Calendarオブジェクトを操作するために最適化されています。

#dates: 主にjava.util.Date型を扱い、単純なフォーマットや変換に適しています。
#calendars: 曜日、週番号、タイムゾーンの考慮など、より複雑なカレンダー計算が必要な場合に適しています。

2026年現在のモダンな開発では、特定の「タイムゾーン」を意識した表示を行いたい場合に、この#calendarsユーティリティが特に力を発揮します。

7. タイムゾーンを指定した日付表示

グローバルなアプリケーションでは、サーバーの時刻ではなくユーザーの地域の時刻を表示する必要があります。#calendarsを使えば、特定のタイムゾーンに基づいた現在時刻を簡単に取得できます。


<!-- 日本標準時(JST)で現在の日時を表示 -->
<p th:text="${#calendars.format(#calendars.createForTimeZone(#calendars.createNow(), 'Asia/Tokyo'), 'yyyy/MM/dd HH:mm')}"></p>

<!-- ニューヨークの現在時刻を表示 -->
<p th:text="${#calendars.format(#calendars.createForTimeZone(#calendars.createNow(), 'America/New_York'), 'yyyy/MM/dd HH:mm')}"></p>

このように、createForTimeZoneメソッドを組み合わせることで、世界各地の時刻をテンプレート上で柔軟に書き分けることが可能になります。

8. 週末や特定の曜日を判定する

カレンダー表示において、「土日だけ文字色を変えたい」というケースは非常に多いです。#calendars.dayOfWeek()を利用した条件分岐の例を見てみましょう。


<!-- 日曜日(1)または土曜日(7)の場合にクラスを適用 -->
<span th:text="${day}" 
      th:class="${#calendars.dayOfWeek(targetDate) == 1 or #calendars.dayOfWeek(targetDate) == 7} ? 'text-danger' : ''">
</span>

dayOfWeekは日曜日を「1」として数え始めます。これを利用することで、CSSクラスの動的な切り替えが簡単に行え、視覚的に分かりやすいカレンダーUIを構築できます。

まとめ

今回の記事では、Thymeleafの#calendarsユーティリティを使用したカレンダー操作について詳しく学びました。#calendarsを利用することで、テンプレート内で日付やカレンダー情報を簡単に取得し操作できるため、動的なコンテンツを作成する際に非常に便利です。例えば、現在の年や月、曜日の取得、日付の比較や条件分岐、さらに1か月分のカレンダー表示など、実践的な使用例を通してその効果的な使い方を学びました。

特に、#calendars.isAfterや#calendars.year()などのメソッドは、動的な日付処理を実現するための強力なツールです。また、カレンダー操作に関連するループ処理や条件分岐も簡潔に書けるので、コードの可読性も向上します。


<p>現在の年: <span th:text="${#calendars.year()}"></span></p>
<p>現在の月: <span th:text="${#calendars.month()}"></span></p>
<ul>
    <li th:each="day : ${#numbers.sequence(1, 31)}" th:text="'日付: ' + day"></li>
</ul>

このコードは実際に動作するテンプレートの一例で、動的にカレンダー情報を表示する際に使用できます。こうした柔軟な機能を使いこなすことで、より使いやすいWebアプリケーションを構築できます。

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

生徒

「今回の学びで、Thymeleafでカレンダー操作がどれだけ簡単かよく分かりました！」

先生

「そうですね。特に#calendarsを使うと、日付や曜日などの情報を簡単に取得できて便利です。どんな場面で活用できそうですか？」

生徒

「例えば、予約システムやイベント管理アプリケーションで役立ちそうです。動的なカレンダー表示も簡単に作れそうですね！」

先生

「その通りです。ぜひ今回学んだ内容を活かして、実際のプロジェクトに応用してみてください。」

スタースクール：社会人向け実務教育プロジェクト

【職業訓練講師が直接指導】