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