【Java Web入門 #15】Thymeleafの利用（２） | オブジェクトと演算子
2025.03.21
Thymeleaf をHTMLテンプレートとして利用する際は、主に th: で始まる属性をHTML上に埋め込み、属性の値には変数やリテラルを含む式を設定する方法で利用します。このため、Thymeleaf を利用するためには、属性の動作と式の構成要素について理解する必要があります。
当記事では最も基本的な式の構成要素である、 Thymeleaf で利用可能な変数、リテラルなどのオブジェクトと、演算子について説明します。
◆Java Web入門の過去記事はこちら
◆Java入門 記事一覧はこちら
目次
利用できるオブジェクト
リテラル
リテラルの種類
Thymeleaf では、以下のリテラル値が利用できます。
| 種類 | 記述方法 | 記述例 |
| 文字列 | シングルクォーテーションで囲んで記述する。 （シングルクォーテーションを含む場合は \ でエスケープする） | 'Hello world!' ' Let\'s go!' |
| 数値 | 数値をそのまま記述する。小数の利用や四則演算も可。 （演算については後述の演算子参照） 桁区切り文字（カンマ）の利用は不可。 | 100 + 10 31.25 * 32 |
| 真偽値 | 「false」または「true」 を記述する。 | true |
| null | 「null」を記述する。 | param.val == null |
リテラルトークン
リテラルトークンは、アルファベット（A～Z、a～z）、数字（0-9）、括弧（[]）、ドット（.）、ハイフン（-）、アンダースコア（ _ ）で構成される文字列です。属性値などに設定する際に、通常の文字列として扱われます。変数式などの式の中では利用できません。
数値や真偽値（true・false）もリテラルトークンの１つですが、これらは例外的に文字列ではなく、Thymeleaf によって数値や真偽値として扱われます。
<!-- th:alt属性の値に文字列を設定 -->
<img th:alt="'サンプル画像'" src="hoge.png"/>
<!-- リテラルトークン（シングルクォーテーションなし） -->
<img th:alt="サンプル画像" src="hoge.png"/>
<!-- 数値もリテラルトークンの１つ -->
<textarea th:rows="10" th:cols="50"/>
実際には、th:xxx 属性の値で式を利用しない場合に、通常のHTMLと同じように記述すれば良いだけですので、そこまでリテラルトークンを意識しなくても問題ないと思います。
リテラル置換
文字列リテラルの利用方法として、リテラル置換と呼ばれるものがあります。これは、属性内のリテラルトークンの一部を式の値に置き換えます。
リテラル置換を行う文字列リテラルは縦棒（ | ）で囲みます。リテラル置換を利用することで、文字列の連結に「+」記号を利用せずにシンプルな記述が実現できます。
<!-- リテラル置換を利用する場合 -->
<p th:text="|こんにちは、${name}さん。|">挨拶文をここに</p>
<!-- 文字列の連結（式）を利用する場合 -->
<p th:text="'こんにちは、' + ${name} + 'さん。'">挨拶文をここに</p>
置き換える値には変数式（ ${ ... }、*{ ... } ）またはメッセージ式（ #{ ... } ）のみ利用できます。式の値に置き換えるため、式の中の文字列リテラルに対してリテラル置換を利用することはできません。
変数
変数は Thymeleaf のコンテキスト内にある同名のオブジェクトを参照します。
Spring Boot で Model に保持した変数や、リクエストに設定（setAttribute）した属性などは、このThymeleaf のコンテキスト内に保持されるため、その名前で変数として利用できます。
以下のサンプルコードでは変数「name」の値を出力します。
<p>こんにちは、[[ ${name} ]] さん。</p>
但し、変数名に式基本オブジェクト（param、session、application）、数値、真偽値、「null」は利用できません。また、後述する演算子（eq、and など）と同じ名前で保持させた場合、式として動作はしますが可読性が著しく悪くなりますので注意しましょう。
式基本オブジェクト
JSPの暗黙オブジェクトと同様に、Thymeleaf にも宣言を行わなくても利用できる変数が準備されています。
基本オブジェクト
基本オブジェクトは「#」で始まる、以下の２つのオブジェクトです。
| 変数名 | 説明 | クラス |
| #ctx | Thymeleaf のコンテキストオブジェクト。 （#vars または #root でも同様だが非推奨） | org.thymeleaf.context.IWebContext （※１） |
| #locale | 現在のリクエストに関連付けられているロケールオブジェクト。 | java.util.Locale |
#ctx はThymeleaf のコンテキストオブジェクトです。Webアプリケーションで利用する場合、リクエストや Spring の Model に設定した各属性（Attribute）は、このオブジェクトに設定されています。これらの属性にアクセスする場合は「#ctx.anyAttr」だけでなく、「anyAttr」のみでもアクセスできます。
ウェブパラメーター・スコープ
「param」はリクエストパラメーターへのアクセスを、「session」および「application」はそれぞれセッションスコープ、アプリケーションスコープの属性（attribute) へのアクセスを提供するオブジェクトです。
param、session、application の３つは他の式基本オブジェクトや式ユーティリティオブジェクトと異なり、「#」が前方につきません。このため、Model に保持させた変数を Thymeleaf で利用したい場合などは、これらの名前で保持しないようにする必要があることに注意してください。
| 変数名 | 説明 |
| param | リクエストパラメーターへのアクセスを提供する。 （ServletRequest#getParameter と同じ働き） |
| session | セッションスコープ属性（attribute）へのアクセスを提供する。 （HttpSession#getAttribute と同じ働き） |
| application | アプリケーションスコープ属性（attribute）へのアクセスを提供する。 （ServletContext#getAttribute と同じ働き） |
Thymeleaf では、リクエストの属性は自動的にコンテキストルートの変数として追加され、session.XXX や application.XXX のように取得先を指定する必要がないため、式基本オブジェクトとしての「request」は準備されていません。
[参考：Thymeleaf 3.0 まで利用可]
ウェブコンテキストオブジェクト
以下のウェブコンテキストオブジェクトへのアクセスは、Thymeleaf 3.1 から無効となっているためご注意ください。（テンプレートファイル上に記述した場合、実行時エラーとなります）
参考：Thymeleaf 3.1 の変更点 - thymeleaf.org
| 変数名 | 説明 | クラス |
| #request （※４） | 現在のリクエストに紐づく HttpServletRequest オブジェクト。 | jakarta.servlet.http.HttpServletRequest （※２） |
| #response （※４） | 現在のリクエストに紐づく HttpServletResponse オブジェクト。 | jakarta.servlet.http.HttpServletRequest （※２） |
| #session （※４） | 現在のリクエストに紐づく HttpSession オブジェクト。 | jakarta.servlet.http.HttpSession （※２） |
| #servletContext （※４） | 現在のリクエストに紐づく ServletContext オブジェクト。 | jakarta.servlet.ServletContext （※３） |
※３ Java/Jakarta EE 8 まではjavax.servletパッケージ
※４ リンク先が以前のバージョン（Thymeleaf 3.0）のドキュメントであることにご注意ください
式ユーティリティオブジェクト
Thymeleaf では式基本オブジェクトに加え、フォーマットや演算、配列やコレクションを扱うためのユーティリティクラスのオブジェクト（式ユーティリティオブジェクト）が準備されています。
これらの式ユーティリティオブジェクトの利用ついては、公式チュートリアルに詳細が記載されていますので、ここでの説明は割愛します。（変数名のリンクをご参照ください）
| 変数名 | 説明 | クラス （※５） |
| #execInfo | 現在処理しているテンプレートの情報を提供する式オブジェクト。 | ExecutionInfo |
| #messages | メッセージリソース（外部化メッセージ）の利用のためのユーティリティクラス。 | Messages |
| #uris | URI／URLのエスケープ、アンエスケープを行うユーティリティクラス。 | Uris |
| #conversion | コンバージョン（クラス変換）のためのユーティリティクラス。 | Conversions |
| #dates | java.util.Date オブジェクトに対するユーティリティクラス。 | Dates |
| #calendars | java.util.Calendar オブジェクトに対するユーティリティクラス。 | Calendars |
| #temporals | java.time APIの日付/時刻オブジェクトに対するユーティリティクラス。 | Temporals |
| #numbers | 数値のフォーマットや配列作成を行うユーティリティクラス。 | Numbers |
| #strings | 文字列全般に対するユーティリティクラス。 | Strings |
| #objects | オブジェクトまたは配列、List、Setに対して null時のデフォルト値を設定するユーティリティクラス。 | Objects |
| #bools | 真偽値処理ユーティリティクラス。 | Bools |
| #arrays | 配列への変換、空チェック、要素数の取得などを行うユーティリティクラス。 | Arrays |
| #lists | リストへの変換、空または包含チェック、ソートなどを行う、リスト（java.util.List）オブジェクトに対するユーティリティクラス。 | Lists |
| #sets | セットへの変換、空または包含チェック、要素数の取得などを行う、セット（java.util.Set）オブジェクトに対するユーティリティクラス。 | Sets |
| #maps | 空または包含チェック、要素数の取得などを行う、マップ（java.util.Map）オブジェクトに対するユーティリティクラス。 | Maps |
| #aggregates | 数値型の配列やコレクションに対し、集計（合算または平均）処理を行うユーティリティクラス。 | Aggregates |
| #ids | （ループ処理などで）HTMLオブジェクトの「id」属性を扱うためのユーティリティクラス。 | Ids |
利用できる演算子
算術演算子
Thymeleaf の式の中では、四則演算（+、-、*、/）および剰余演算子（%）を利用することができます。
除算（/）と剰余（%）には文字列エイリアスが定義されており、それぞれ「div」（除算）、「mod」剰余と記述することも可能です。
また、加算（+）の演算子は、文字列の連結にも利用します。
| 演算内容 | 演算子 | 文字列エイリアス |
| 加算・文字列連結 | + | （なし） |
| 減算 | - | （なし） |
| 乗算 | * | （なし） |
| 除算 | / | div |
| 剰余 | % | mod |
<!-- 文字列の連結 -->
<div>[[ 'Hello' + ' ' + 'World!' ]]</div>
<hr/>
<!-- 四則演算（整数値） -->
<div>10 + 3 = [[ 10 + 3 ]]</div>
<div>10 - 3 = [[ 10 - 3 ]]</div>
<div>10 * 3 = [[ 10 * 3 ]]</div>
<div>10 / 3 = [[ 10 / 3 ]]</div>
<div>10 % 3 = [[ 10 % 3 ]]</div>
<div>10 div 3 = [[ 10 div 3 ]]</div>
<div>10 mod 3 = [[ 10 mod 3 ]]</div>
実行結果：
等価演算子・比較演算子
値の大小や、値の等価性を比較するための演算子は、全ての演算子が文字列エイリアスを持ちます。
イコール記号や特に不等号（<, >）はHTMLでも利用される文字で、特に不等号はHTMLタグで利用される文字であるため推奨されていない（「>」「<」と記述する）ため、これらの演算子については基本的に文字列エイリアスを利用することをお勧めします。
| 比較内容 | 演算子 | 文字列エイリアス |
| 等しい | == | eq |
| 等しくない | != | ne |
| 以上 | >= （>=） | ge |
| より大きい | > （>） | gt |
| 以下 | <= （<=） | le |
| より小さい | < （<） | lt |
<div>1 eq 1 ： [[1 eq 1]]</div> <!-- （1 == 1）-->
<div>1 ne 1 ： [[1 ne 1]]</div> <!-- （1 != 1） -->
<div>1 ge 1 ： [[1 ge 1]]</div> <!-- （1 >= 1） -->
<div>1 gt 1 ： [[1 gt 1]]</div> <!-- （1 > 1） -->
<div>1 le 1 ： [[1 le 1]]</div> <!-- （1 <= 1） -->
<div>1 lt 1 ： [[1 lt 1]]</div> <!-- （1 < 1） -->
実行結果：
論理演算子
複数の条件を判定する場合や、結果を反転させる場合の論理演算子については、以下のものが利用できます。"&&" や "||" は利用できません。
| 比較内容 | 演算子 | 文字列エイリアス |
| かつ | （なし） | and |
| または | （なし） | or |
| 否定 | ! | not |
and 演算子または or 演算子では短絡評価（ショートサーキット）を行うため、論理演算子より後方の条件に解析エラーとなる記述があってもエラーとならずに動作してしまう場合があるため注意してください。
<!-- 1 / 0（ゼロ除算）があるためエラーとなる -->
<div>[[1 eq 1 and 1 / 0 > 0]]</div>
<!-- 1 / 0（ゼロ除算）があるが短絡評価のため実行されずにエラーとならない -->
<div>[[1 eq 1 or 1 / 0 > 0]]</div>条件式・デフォルト式
条件式（三項演算子）
Thymeleaf では、いわゆる三項演算子を利用した条件式を利用できます。
書式：
${ 条件式 ? [真の場合の値] : [偽の場合の値] }
<p>こんにちは、[[ ${param.name != null ? param.name : '名無し' } ]] さん。</p>デフォルト式（エルビス演算子）
Thymeleaf では条件式に似た構文として、デフォルト式の利用が可能です。デフォルト式では判定条件の指定は不要で、出力対象の項目が null であるかどうかで判定を行います。
書式：
${ [出力対象] ?: [デフォルト値] }
デフォルト式（エルビス演算子）では、出力対象（演算子の前の式・変数）の値が null であった場合、演算子（ ?: ）の後方に指定したデフォルト値の内容が出力されます。出力対象の値が null ではなかった場合は、その値が出力されます。
以下のサンプルコードはどちらもリクエストパラメーター「name」の有無をチェックして出力を切り替える式ですが、デフォルト式を利用する方がシンプルな記述となっています。
<!-- デフォルト式（エルビス演算子）を利用 -->
<p>こんにちは、[[ ${param.name ?: '名無し' } ]] さん。</p>
<!-- 条件式（三項演算子）を利用 -->
<p>こんにちは、[[ ${param.name != null ? param.name : '名無し' } ]] さん。</p>
いかがでしたでしょうか。これらのオブジェクトや演算子については、全て覚えなくても Thymeleag を利用することはできますが、Thymeleaf でどのような処理ができるのかを理解するためには必要な情報です。次回の記事では、これらのオブジェクトや演算子を実際に利用する、Thymeleaf の式構文について説明します。
