Jinja2 チートシート

変数 (Variables)

テンプレート内でPythonの変数を展開します。

コード例

Python コード:

from jinja2 import Template
template = Template("""
名前: {{ name }}
年齢: {{ user.age }}
最初の趣味: {{ hobbies[0] }}
都市: {{ address['city'] }}
""")
data = { 'name': '山田 太郎', 'user': {'age': 30}, 'hobbies': ['読書', '映画鑑賞', '旅行'], 'address': {'city': '東京'}
}
output = template.render(data)
print(output)

出力結果:

名前: 山田 太郎
年齢: 30
最初の趣味: 読書
都市: 東京

制御構造 (Control Structures)

条件分岐や繰り返し処理をテンプレート内で実現します。

If 文

コード例

template = Template("""
{% if user.is_admin %} 管理者です。
{% elif user.is_staff %} スタッフです。
{% else %} 一般ユーザーです。
{% endif %}
""")
output_admin = template.render(user={'is_admin': True, 'is_staff': False})
output_staff = template.render(user={'is_admin': False, 'is_staff': True})
output_user = template.render(user={'is_admin': False, 'is_staff': False})
print("管理者:", output_admin.strip())
print("スタッフ:", output_staff.strip())
print("一般ユーザー:", output_user.strip())

出力結果:

管理者: 管理者です。
スタッフ: スタッフです。
一般ユーザー: 一般ユーザーです。

For ループ

リストや辞書などのイテラブルオブジェクトを反復処理します。

Loop ヘルパー変数

`for` ループ内では `loop` という特殊な変数にアクセスでき、ループの状態に関する情報を取得できます。

コード例

template = Template("""
<ul>
{% for user in users %} <li class="{{ loop.cycle('odd', 'even') }}{% if loop.first %} first{% endif %}{% if loop.last %} last{% endif %}"> {{ loop.index }}: {{ user.name }} {% if user.age > 30 %}(ベテラン){% endif %} </li>
{% else %} <li>ユーザーはいません。</li>
{% endfor %}
</ul>
<dl>
{% for key, value in config.items() %} <dt>{{ key }}</dt> <dd>{{ value }}</dd>
{% endfor %}
</dl>
Filtered List:
{% for x in [1, 2, 3, 4, 5] if x is even %}
- {{ x }}
{% endfor %}
""")
data = { 'users': [ {'name': 'Alice', 'age': 25}, {'name': 'Bob', 'age': 35}, {'name': 'Charlie', 'age': 28} ], 'config': {'theme': 'dark', 'debug': True}
}
output = template.render(data)
print(output)
# 空のリストの場合
empty_data = {'users': [], 'config': {}}
output_empty = template.render(empty_data)
print("\n--- 空の場合 ---")
print(output_empty)

出力結果:

<ul> <li class="odd first"> 1: Alice </li> <li class="even"> 2: Bob (ベテラン) </li> <li class="odd last"> 3: Charlie </li>
</ul>
<dl> <dt>theme</dt> <dd>dark</dd> <dt>debug</dt> <dd>True</dd>
</dl>
Filtered List:
- 2
- 4
--- 空の場合 ---
<ul> <li>ユーザーはいません。</li>
</ul>
<dl>
</dl>
Filtered List:

フィルター (Filters)

変数の表示形式を変更したり、データを加工したりします。パイプ (`|`) 記号を使って適用します。

コード例

template = Template("""
名前 (大文字): {{ name | upper }}
挨拶 (デフォルト値): {{ greeting | default("こんにちは") }}
最初のタグ: {{ tags | first | capitalize }}
タグリスト: {{ tags | join(", ") }}
数値リスト (バッチ処理 2個ずつ):
{% for row in numbers | batch(2, '-') %} {{ row | join(" | ") }}
{% endfor %}
HTMLコンテンツ: {{ html_code | e }}
安全なHTML: {{ safe_html | safe }}
""")
data = { 'name': 'Sato', 'tags': ['python', 'jinja', 'web'], 'numbers': [1, 2, 3, 4, 5], 'html_code': 'Click me', 'safe_html': '
This is safe.
' # 'greeting' は未定義
}
output = template.render(data)
print(output)

出力結果:

名前 (大文字): SATO
挨拶 (デフォルト値): こんにちは
最初のタグ: Python
タグリスト: python, jinja, web
数値リスト (バッチ処理 2個ずつ): 1 | 2 3 | 4 5 | -
HTMLコンテンツ: <button onclick="alert('XSS')">Click me</button>
安全なHTML: <p style="color: green;">This is safe.</p>

テスト (Tests)

変数の型や値をチェックし、`if` 文などの条件式で使用します。`is` キーワードを使って適用します。

コード例

template = Template("""
{% if user is defined and user is mapping %} ユーザー名: {{ user.name | default('不明') }} {% if user.age is defined and user.age is number and user.age >= 18 %} 年齢は {{ user.age }} 歳で、成人です。 {% if user.age is odd %} 年齢は奇数です。 {% endif %} {% elif user.age is defined %} 年齢は {{ user.age }} 歳で、未成年です。 {% else %} 年齢は不明です。 {% endif %} {% if 'admin' in user.roles %} 管理者権限を持っています。 {% endif %}
{% else %} ユーザー情報がありません。
{% endif %}
{% if value is none %} 値はNoneです。
{% endif %}
{% if count == 5 %} カウントは5です。
{% endif %}
""")
data1 = { 'user': { 'name': 'Alice', 'age': 25, 'roles': ['editor', 'user'] }, 'value': None, 'count': 5
}
data2 = { 'user': { 'age': 15, 'roles': ['admin', 'user'] } # 'name' は未定義
}
data3 = {}
output1 = template.render(data1)
output2 = template.render(data2)
output3 = template.render(data3)
print("--- Data 1 ---")
print(output1)
print("--- Data 2 ---")
print(output2)
print("--- Data 3 ---")
print(output3)

出力結果:

--- Data 1 --- ユーザー名: Alice 年齢は 25 歳で、成人です。 年齢は奇数です。
値はNoneです。
カウントは5です。
--- Data 2 --- ユーザー名: 不明 年齢は 15 歳で、未成年です。 管理者権限を持っています。
--- Data 3 --- ユーザー情報がありません。

マクロ (Macros)

テンプレート内で再利用可能な関数のようなものを定義します。HTMLの断片やロジックをカプセル化するのに便利です。

定義と呼び出し

{% macro input(name, value='', type='text', size=20) %} <input type="{{ type }}" name="{{ name }}" value="{{ value|e }}" size="{{ size }}">
{% endmacro %}
{{ input('username') }}
{{ input('password', type='password') }}
{{ input('email', 'test@example.com', size=30) }}

`macro` タグでマクロを定義し、通常の変数のように呼び出します。引数を渡すことができ、デフォルト値を設定することも可能です。

`caller()`

`call` タグを使ってマクロを呼び出す際に、呼び出し元のブロックの内容をマクロ内で利用できます。

{% macro render_dialog(title, class='dialog') %} <div class="{{ class }}"> <h2>{{ title }}</h2> <div class="content"> {{ caller() }} </div> </div>
{% endmacro %}
{% call render_dialog('ようこそ') %} これはダイアログの本文です。<br> HTMLも利用可能です。
{% endcall %}
{% call(user) render_dialog(user.name, class='user-profile') %} 年齢: {{ user.age }}<br> メール: {{ user.email }}
{% endcall %}

`caller()` は `call` ブロック内のレンダリング結果を返します。`call` タグに引数を渡すと、`caller` にもその引数が渡されます。

インポート

他のテンプレートファイルで定義されたマクロを利用するには、`import` または `from … import` を使います。

`import`

テンプレート全体をインポートし、`.` (ドット) を使ってマクロにアクセスします。

例: `_forms.html` に `input` マクロが定義されている場合

{% import '_forms.html' as forms %}
{{ forms.input('username') }}
{{ forms.input('password', type='password') }}

`from … import`

特定の名前のマクロを現在のテンプレートのスコープに直接インポートします。

{% from '_forms.html' import input as input_field, textarea %}
{{ input_field('email') }}
{{ textarea('message') }}

`with context` を付けると、インポート元のコンテキスト（変数）がインポートしたマクロ内で利用可能になります。`without context` を付けると利用できなくなります（デフォルト）。

{% from '_helpers.html' import my_macro with context %}
{% from '_utils.html' import utility_macro without context %}
{{ my_macro() }} {# 現在のコンテキストが利用可能 #}
{{ utility_macro() }} {# 現在のコンテキストは利用不可 #}

テンプレート継承 (Template Inheritance)

テンプレートの骨組み（レイアウト）を定義し、子テンプレートで特定の部分を上書きする仕組みです。コードの再利用性を高めます。

コード例

親テンプレート (`base.html`):

<!DOCTYPE html>
<html>
<head> <title>{% block title %}デフォルトタイトル{% endblock %}</title> {% block head %} <link rel="stylesheet" href="style.css"> {% endblock %}
</head>
<body> <div id="content"> {% block content %}{% endblock %} </div> <div id="footer"> {% block footer %} 2025 My Company {% endblock %} </div>
</body>
</html>

子テンプレート (`child.html`):

{% extends "base.html" %}
{% block title %}マイページ - {{ super() }}{% endblock %}
{% block head %} {{ super() }} <!-- このページ固有のスタイルシート --> <link rel="stylesheet" href="mypage.css">
{% endblock %}
{% block content %} <h1>ようこそ、{{ username }} さん！</h1> <p>これはマイページのコンテンツです。</p>
{% endblock %}
{# footerブロックは上書きしないので、親テンプレートの内容が使われる #}

`child.html` を `username=’ゲスト’` でレンダリングすると、`base.html` の構造に `child.html` のブロック内容が挿入されたHTMLが出力されます。`title` と `head` ブロックでは `super()` を使って親の内容を含めています。

インクルード (Include)

他のテンプレートファイルの内容を現在のテンプレートに挿入します。ヘッダー、フッター、サイドバーなど、共通部分のパーツを読み込むのに便利です。

コード例

`main.html`:

<div class="page"> {% include "header.html" %} <div class="content"> <h1>{{ page_title }}</h1> <p>メインコンテンツエリア</p> {# user変数だけを渡す #} {% include "user_profile.html" with {'user': current_user} %} </div> {# コンテキストを渡さない #} {% include "footer.html" without context ignore missing %}
</div>

`header.html`:

<header> サイトロゴ - {{ site_name | default('My Site') }} {% if current_user %} <span>ようこそ、{{ current_user.name }}さん</span> {% endif %}
</header>

`user_profile.html`:

<div class="profile"> <h2>{{ user.name }}のプロフィール</h2> <p>メール: {{ user.email }}</p> {# page_title は渡されていないので使えない #} {# <p>現在のページ: {{ page_title }}</p> これはエラーになるか空になる #}
</div>

`main.html` をレンダリングする際に `page_title`, `site_name`, `current_user` などの変数を渡すと、`header.html` では `current_user` や `site_name` が利用でき、`user_profile.html` では渡された `user` のみが利用できます。`footer.html` は存在すればコンテキストなしで読み込まれます。

コメント (Comments)

テンプレート内にメモを残しますが、レンダリング結果には出力されません。

コード例

{# ユーザー情報を表示するセクション #}
<div class="user-info"> {# 名前を表示 #} <p>名前: {{ user.name }}</p> {# 複数行のコメントも可能です。 年齢はオプションで表示します。 #} {% if user.age %} <p>年齢: {{ user.age }}</p> {# 年齢を表示 #} {% endif %}
</div>
{# --- ここまでユーザー情報 --- #}

空白制御 (Whitespace Control)

テンプレートタグの前後にある空白（改行含む）を制御します。タグの開始/終了デリミタにハイフン (`-`) を追加します。

コード例

制御なし:

<ul>
{% for item in items %} <li>{{ item }}</li>
{% endfor %}
</ul>

出力 (改行とインデントがそのまま残る):

<ul> <li>Apple</li> <li>Banana</li> <li>Cherry</li>
</ul>

空白制御あり:

<ul>
{%- for item in items -%} <li>{{- item -}}</li>
{%- endfor -%}
</ul>

出力 (タグ周りの不要な空白が削除される):

<ul><li>Apple</li><li>Banana</li><li>Cherry</li></ul>

部分的な制御:

<ul>
{% for item in items %} <li>{{ item }}</li>{% endfor %}
</ul>

出力 (endforの後ろの改行のみ削除):

<ul> <li>Apple</li> <li>Banana</li> <li>Cherry</li></ul>

環境設定で `trim_blocks` や `lstrip_blocks` を有効にすると、ブロックタグ周りの空白を自動的に制御することも可能です。

エスケープ (Escaping)

セキュリティ（特にクロスサイトスクリプティング – XSS）のために、テンプレートに変数を埋め込む際のHTML特殊文字の扱いを制御します。

自動エスケープ

Jinja2 環境の多く（Flask, Djangoなど）では、デフォルトで自動エスケープが有効になっています。これにより、`{{ variable }}` で出力される変数は自動的にHTMLエスケープされます。

# 環境で autoescape=True (デフォルトが多い)
template = Template("Hello, {{ name }}")
output = template.render(name='<b>World</b>')
print(output) # 出力: Hello, &lt;b&gt;World&lt;/b&gt;

手動エスケープ

自動エスケープが無効な環境や、明示的にエスケープしたい場合に `escape` または `e` フィルターを使用します。

# 環境で autoescape=False
template = Template("Data: {{ user_input | e }}")
output = template.render(user_input='<script>alert("XSS")</script>')
print(output) # 出力: Data: &lt;script&gt;alert("XSS")&lt;/script&gt;

エスケープの無効化

変数の内容が安全なHTMLであり、エスケープせずにそのまま出力したい場合は、`safe` フィルターを使用するか、変数を `Markup` オブジェクトにします。

警告: ユーザー入力など、信頼できないソースからのデータを `safe` にマークするのは非常に危険です。XSS脆弱性の原因となります。

from markupsafe import Markup
# 自動エスケープが有効な環境
template = Template("""
Escaped: {{ unsafe_html }}
Safe: {{ safe_html | safe }}
Markup Object: {{ markup_obj }}
""")
data = { 'unsafe_html': '<strong>Unsafe</strong>', 'safe_html': '<em>This is marked safe</em>', # 本来は信頼できるソースから生成されたHTML 'markup_obj': Markup('<a href="#">Link</a>')
}
output = template.render(data)
print(output)

出力結果:

Escaped: <strong>Unsafe</strong>
Safe: <em>This is marked safe</em>
Markup Object: <a href="#">Link</a>

`autoescape` ブロック

テンプレートの一部で自動エスケープの挙動を切り替えることができます。

{% autoescape true %} {{ var1 }} {# エスケープされる #} {% autoescape false %} {{ var2 }} {# エスケープされない #} {% endautoescape %} {{ var3 }} {# 再びエスケープされる #}
{% endautoescape %}
{# XMLを生成する場合など #}
{% autoescape 'xml' %} <foo>{{ data }}</foo> {# XMLエスケープ #}
{% endautoescape %}

`true`, `false` の他に、ファイル拡張子に応じたエスケープ（例: `’html’`, `’xml’`）を指定することも可能です。

特殊変数 (Special Variables)

Jinja2が提供する、特定のコンテキストで利用可能な特殊な変数です。

`namespace` のコード例

template = Template("""
{% set ns = namespace(found=false, count=0) %}
{% for item in items %} {% if item.startswith('A') %} {% set ns.found = true %} {% set ns.count = ns.count + 1 %} 
{{ item }} (Found!)
 {% else %} 
{{ item }}
 {% endif %}
{% endfor %}
{% if ns.found %}
Found {{ ns.count }} items starting with 'A'.
{% else %}
No items starting with 'A' found.
{% endif %}
""")
data = {'items': ['Apple', 'Banana', 'Avocado', 'Cherry', 'Apricot']}
output = template.render(data)
print(output)
data_none = {'items': ['Banana', 'Cherry']}
output_none = template.render(data_none)
print("\n--- None Found ---")
print(output_none)

出力結果:

 
Apple (Found!)
 
Banana
 
Avocado (Found!)
 
Cherry
 
Apricot (Found!)
Found 3 items starting with 'A'.
--- None Found ---
 
Banana
 
Cherry
No items starting with 'A' found.

`namespace` を使わないと、`for` ループ内で `found` や `count` を変更しても、ループの外側には反映されません。

環境設定と拡張 (Environment & Extensions)

Jinja2の動作をカスタマイズするための主要な概念です。チートシートの範囲を超えますが、基本的な点をいくつか紹介します。

Environment

Jinja2の中核となるオブジェクトです。テンプレートのロード方法、構文デリミタ、自動エスケープの有無、拡張機能などを設定します。

from jinja2 import Environment, FileSystemLoader
# ファイルシステムからテンプレートをロードする環境を作成
env = Environment( loader=FileSystemLoader('templates/'), # テンプレートを探すディレクトリ autoescape=True, # 自動HTMLエスケープを有効化 trim_blocks=True, # ブロックタグの後の改行を削除 lstrip_blocks=True # ブロックタグの前のインデントを削除
)
# 拡張機能を追加
# env.add_extension('jinja2.ext.do')
# テンプレートをロードしてレンダリング
template = env.get_template('mytemplate.html')
output = template.render(my_variable='value')

ローダー (Loaders)

テンプレートファイルをどこから読み込むかを定義します。

• FileSystemLoader(searchpath): 指定されたディレクトリからテンプレートを読み込みます。
• PackageLoader(package_name, package_path='templates'): Pythonパッケージ内からテンプレートを読み込みます。
• DictLoader(mapping): Pythonの辞書からテンプレートを読み込みます。
• ChoiceLoader(loaders): 複数のローダーを試し、最初に見つかったものを使用します。
• PrefixLoader(mapping, delimiter='/'): プレフィックスに応じて異なるローダーに委譲します。

拡張機能 (Extensions)

Jinja2のコア機能を拡張します。`Environment` 作成時に `extensions` リストで指定するか、`add_extension` メソッドで追加します。

• `jinja2.ext.do`: テンプレート内で式を実行できる `{% do %}` タグを追加します。例: `{% do mylist.append(1) %}`
• `jinja2.ext.loopcontrols`: `for` ループ内で `break` と `continue` を使えるようにします。
  `{% for item in items %}{% if item.invalid %}{% continue %}{% endif %}{% if item.is_last %}{% break %}{% endif %}…{% endfor %}`
• `jinja2.ext.with_`: より複雑な変数のスコープ管理を行う `{% with %}` タグを追加します（Jinja2 3.0以降はコア機能）。
  `{% with foo=42, bar=user.name %}{{ foo }} – {{ bar }}{% endwith %}`
• `jinja2.ext.autoescape`: `{% autoescape %}` ブロックを提供します（Jinja2 2.9以降はコア機能）。
• `jinja2.ext.i18n`: 国際化（i18n）サポートを追加し、`{% trans %}` タグなどを提供します。

`do` 拡張のコード例

from jinja2 import Environment
env = Environment(extensions=['jinja2.ext.do'])
template = env.from_string("""
{% set mylist = [] %}
{% for i in range(5) %} {% do mylist.append(i * 2) %}
{% endfor %}
List: {{ mylist | join(', ') }}
""")
output = template.render()
print(output) # 出力: List: 0, 2, 4, 6, 8