3. 模板引擎进阶：模板继承、宏、自定义过滤器与扩展

在掌握了 Jinja2 基础语法之后，面对真实业务场景（如导出包含复杂表格、图表、页眉页脚的 PDF/Excel 报告），模板的复用性、可维护性和表达能力成为关键瓶颈。本章深入 Jinja2 的三大进阶特性：模板继承（布局复用）、宏（函数式片段复用）、自定义过滤器与扩展（Python 能力注入），并结合异步导出场景说明其工程价值。

3.1 模板继承：构建可复用的布局骨架

模板继承允许定义一个基础骨架（base template），子模板通过 {% extends %} 继承并填充特定 {% block %} 区域。在异步导出场景中，所有报告（PDF、HTML、Excel 预览）共享统一的页眉、页脚、样式和导航结构，只需在子模板中替换内容块。

3.1.1 基础模板示例（base_report.html）

<!DOCTYPE html>
<html>
<head>
    <title>{% block title %}数据导出报告{% endblock %}</title>
    <link rel="stylesheet" href="/static/report.css">
    {% block extra_head %}{% endblock %}
</head>
<body>
    <header>
        <h1>{% block header_title %}系统导出中心{% endblock %}</h1>
        <p class="timestamp">生成时间：{{ now() }}</p>
    </header>

    <main>
        {% block content %}
        <!-- 默认内容，子模板可覆盖 -->
        <p>无内容。</p>
        {% endblock %}
    </main>

    <footer>
        <p>© 2025 数据平台 | 第 {{ page }} 页</p>
    </footer>
</body>
</html>

3.1.2 子模板示例（sales_report.html）

{% extends "base_report.html" %}
{% block title %}销售数据导出 - {{ date_range }}{% endblock %}
{% block header_title %}销售日报导出{% endblock %}
{% block content %}
<h2>销售概览</h2>
<table>
    <tr><th>品类</th><th>销售额</th><th>订单数</th></tr>
    {% for row in sales_data %}
    <tr>
        <td>{{ row.category }}</td>
        <td>{{ row.amount | format_currency }}</td>
        <td>{{ row.count }}</td>
    </tr>
    {% endfor %}
</table>
{% endblock %}

3.2 宏：模板中的可复用函数

宏（Macro）类似编程语言中的函数，用于封装重复的 HTML 片段。在导出场景中，表格行、分页导航、图表容器、状态标签等高频片段非常适合定义为宏。

3.2.1 定义与调用宏

{% macro render_table_row(row, fields, currency_fields=[]) %}
<tr>
    {% for field in fields %}
    <td>
        {% if field in currency_fields %}
            {{ row[field] | format_currency }}
        {% else %}
            {{ row[field] }}
        {% endif %}
    </td>
    {% endfor %}
</tr>
{% endmacro %}

<!-- 调用宏 -->
<table>
    <tr><th>品类</th><th>销售额</th><th>订单数</th></tr>
    {% for row in sales_data %}
        {{ render_table_row(row, ['category', 'amount', 'count'], currency_fields=['amount']) }}
    {% endfor %}
</table>

3.2.2 宏的导入与作用域

宏可以单独存放在 macros.html 文件中，通过 {% import %} 或 {% from ... import ... %} 引入：

{% from "macros/report_macros.html" import render_table_row, render_pagination %}

{{ render_table_row(row, fields=['name', 'price'], currency_fields=['price']) }}
{{ render_pagination(current_page, total_pages) }}

3.3 自定义过滤器：Python 能力注入模板

过滤器（Filter）是 Jinja2 最灵活的扩展点之一。通过 Python 函数注册为过滤器，可以在模板中直接调用复杂的数据处理逻辑（如格式化金额、脱敏、时区转换、JSON 序列化）。

3.3.1 注册自定义过滤器

from jinja2 import Environment

def format_currency(value, currency='CNY', decimal_places=2):
    """格式化金额，如 12345.6 -> ¥12,345.60"""
    if value is None:
        return '—'
    formatted = f"{value:,.{decimal_places}f}"
    symbols = {'CNY': '¥', 'USD': '$', 'EUR': '€'}
    symbol = symbols.get(currency, currency + ' ')
    return f"{symbol}{formatted}"

def mask_phone(phone):
    """手机号脱敏：138****1234"""
    if not phone or len(phone) < 7:
        return phone
    return phone[:3] + '****' + phone[-4:]

# 注册到 Jinja2 环境
env = Environment()
env.filters['format_currency'] = format_currency
env.filters['mask_phone'] = mask_phone

3.3.2 在模板中使用自定义过滤器

<p>订单金额：{{ order.amount | format_currency('USD', 2) }}</p>
<p>联系电话：{{ order.phone | mask_phone }}</p>
<p>原始数据：{{ complex_data | tojson }}</p>

3.3.3 过滤器链与参数传递

过滤器支持链式调用，参数通过括号传递：

{{ raw_value | default(0) | format_currency('CNY') | safe }}

3.4 自定义扩展：深度集成 Python 生态

当过滤器或宏不足以表达复杂逻辑时（如注入全局函数、修改 AST、支持自定义标签），可以编写 Jinja2 扩展。扩展是类，继承 jinja2.ext.Extension，可注册新的 {% tag %} 或修改编译行为。

3.4.1 常用内置扩展

3.4.2 自定义扩展示例：注入全局函数

from jinja2 import Environment
from jinja2.ext import Extension

class ReportGlobalsExtension(Extension):
    """注入导出报告所需的全局函数和常量"""

    def __init__(self, environment):
        super().__init__(environment)
        # 注入全局函数
        environment.globals['now'] = lambda: datetime.utcnow().strftime('%Y-%m-%d %H:%M:%S UTC')
        environment.globals['page_break'] = '<div class="page-break"></div>'
        environment.globals['export_version'] = '2.1.0'

# 使用扩展
env = Environment(extensions=[ReportGlobalsExtension])
template = env.from_string("生成时间：{{ now() }}，版本：{{ export_version }}")
print(template.render())
# 输出：生成时间：2025-03-21 14:30:00 UTC，版本：2.1.0

3.5 进阶特性综合架构图

下图展示了模板继承、宏、自定义过滤器和扩展在异步导出渲染流程中的协作关系：

3.6 进阶特性对比与选型建议

3.7 实战：在异步导出中组合使用进阶特性

以下代码片段展示如何在异步导出任务中组合使用模板继承、宏和自定义过滤器：

# async_export_service.py
from jinja2 import Environment, FileSystemLoader
from .filters import format_currency, mask_phone, to_json
from .extensions import ReportGlobalsExtension

# 初始化 Jinja2 环境，加载模板目录
env = Environment(
    loader=FileSystemLoader('templates/reports/'),
    extensions=[ReportGlobalsExtension],
    autoescape=True
)

# 注册自定义过滤器
env.filters['format_currency'] = format_currency
env.filters['mask_phone'] = mask_phone
env.filters['tojson'] = to_json

async def render_sales_report(sales_data: list, date_range: str) -> str:
    """异步渲染销售报告模板"""
    template = env.get_template('sales_report.html')
    # 模板中自动使用继承、宏和过滤器
    html = template.render(
        sales_data=sales_data,
        date_range=date_range,
        page=1
    )
    return html

对应的模板 sales_report.html 使用继承和宏：

{% extends "base_report.html" %}
{% from "macros/report_macros.html" import render_table_row, render_pagination %}

{% block title %}销售数据导出 - {{ date_range }}{% endblock %}
{% block content %}
<h2>销售明细</h2>
<table class="data-table">
    <thead>
        <tr><th>品类</th><th>销售额</th><th>订单数</th><th>联系人</th></tr>
    </thead>
    <tbody>
        {% for row in sales_data %}
            {{ render_table_row(row, ['category', 'amount', 'count', 'phone'],
                                currency_fields=['amount'],
                                mask_fields=['phone']) }}
        {% endfor %}
    </tbody>
</table>
{{ render_pagination(page, total_pages) }}
{% endblock %}