📚 课程目录第3章报表模板设计

3. 报表模板设计：从结构到占位符的完整实践

报表模板设计这件事，说实话，我见过太多团队把它想简单了。一开始随便写个 HTML 文件，数据一多就崩，格式一改就乱。后来我慢慢总结出一套原则，今天跟你聊聊。

3.1 报表结构设计原则

设计报表模板，核心就三个字：分、定、稳。

分：把报表拆成头部、主体、尾部三大块。头部放标题、时间、审计范围；主体放表格、图表、异常清单；尾部放签名、免责声明、版本号。
定：每块的内容和顺序固定下来。比如头部永远是“审计编号 → 审计日期 → 审计对象 → 审计范围”，不要今天换明天改。
稳：模板本身不依赖具体数据。数据是变量，模板是骨架，两者解耦。

我个人的习惯：先画一张纸上的草图，把每个区块的边界、内容、数据来源标清楚。代码还没写，结构先定死。这一步省下来的时间，后面十倍补回来。

举个例子，一个典型的审计报表结构长这样：

区块	内容	数据来源
报表头部	审计编号、日期、审计对象、审计范围	审计任务元数据
执行摘要	异常总数、严重级别分布、趋势对比	聚合统计结果
异常明细表	逐条异常记录（时间、类型、金额、状态）	审计规则命中结果
趋势图表	折线图/柱状图（按天/周/月）	时间序列数据
报表尾部	审计人、复核人、免责声明、版本号	配置常量

你想想看，如果一开始没分清楚，后面往模板里塞东西，很容易变成“屎山”。

3.2 模板引擎选择：为什么我选 Jinja2

模板引擎市面上不少，Django 自带的、Mako、Jinja2 等等。我做过几个项目对比，最后基本固定在 Jinja2 上。

原因有三：

语法干净：{{ variable }} 和 {% for %} 一眼就能看懂，非 Python 背景的同事也能快速上手。
继承机制强大：可以定义基础模板（base.html），子模板只覆盖具体区块。审计报表的头部和尾部几乎不变，改主体就行。
过滤器丰富：日期格式化、数字千分位、默认值处理，内置过滤器直接搞定，不用自己写一堆辅助函数。

避坑指南：我曾经在一个项目里用了 Django 模板引擎，后来发现它不支持 {% set %} 赋值，临时变量处理起来特别别扭。换成 Jinja2 后，代码量直接砍掉 30%。

Jinja2 的基本用法，我直接给你看一段：

<!-- base_report.html -->
<!DOCTYPE html>
<html>
<head>
    <title>{% block title %}审计报表{% endblock %}</title>
    <style>
        body { font-family: 'Microsoft YaHei', sans-serif; }
        table { border-collapse: collapse; width: 100%; }
        th, td { border: 1px solid #ccc; padding: 8px; text-align: left; }
        th { background-color: #f4f4f4; }
    </style>
</head>
<body>
    <div class="header">
        <h1>审计报表</h1>
        <p>编号：{{ audit_id }} | 日期：{{ audit_date }}</p>
    </div>
    <div class="content">
        {% block content %}{% endblock %}
    </div>
    <div class="footer">
        <p>审计人：{{ auditor }} | 版本：{{ version }}</p>
    </div>
</body>
</html>

子模板只需要写主体部分：

<!-- detail_report.html -->
{% extends "base_report.html" %}

{% block content %}
<h2>异常明细</h2>
<table>
    <tr>
        <th>时间</th>
        <th>类型</th>
        <th>金额</th>
        <th>状态</th>
    </tr>
    {% for item in anomalies %}
    <tr>
        <td>{{ item.time }}</td>
        <td>{{ item.type }}</td>
        <td>{{ item.amount | round(2) }}</td>
        <td>{{ item.status }}</td>
    </tr>
    {% endfor %}
</table>
{% endblock %}

嗯，这里要注意：| round(2) 是 Jinja2 的过滤器，把金额保留两位小数。类似的还有 | date("Y-m-d") 格式化日期，| default("无") 处理空值。

3.3 动态表格与图表占位符

报表里最头疼的就是表格和图表。表格行数不确定，图表数据动态变化。怎么处理？

动态表格：用 {% for %} 循环遍历数据列表。关键点在于表头要固定，表体用循环填充。如果数据为空，记得加个 {% else %} 提示。

<table>
    <thead>
        <tr>
            <th>序号</th>
            <th>异常类型</th>
            <th>发生时间</th>
            <th>涉及金额</th>
        </tr>
    </thead>
    <tbody>
        {% if anomalies %}
        {% for item in anomalies %}
        <tr>
            <td>{{ loop.index }}</td>
            <td>{{ item.type }}</td>
            <td>{{ item.time | date("Y-m-d H:i") }}</td>
            <td>{{ item.amount | round(2) }}</td>
        </tr>
        {% endfor %}
        {% else %}
        <tr>
            <td colspan="4">暂无异常记录</td>
        </tr>
        {% endif %}
    </tbody>
</table>

图表占位符：我的做法是，在模板里放一个 <div> 容器，id 固定，数据通过 JavaScript 变量注入。图表库（比如 ECharts 或 Chart.js）在渲染时读取这个变量。

<!-- 图表占位符 -->
<div id="trendChart" style="width: 100%; height: 400px;"></div>

<script>
    // 数据由后端渲染时注入
    var chartData = {{ chart_data | tojson }};

    // 初始化图表
    var chart = echarts.init(document.getElementById('trendChart'));
    chart.setOption({
        xAxis: { data: chartData.dates },
        yAxis: {},
        series: [{
            type: 'line',
            data: chartData.values
        }]
    });
</script>

注意：| tojson 是 Jinja2 的过滤器，把 Python 对象转成 JSON 字符串。但要注意，如果数据里包含日期对象或 Decimal 类型，需要先序列化。我一般会在后端先转成字符串或浮点数，再传给模板。

为什么会这样？因为 Jinja2 的 tojson 默认只处理基本类型，遇到 datetime 或 Decimal 会报错。我的解决方案是：在数据准备阶段统一做类型转换。

# 后端数据准备
import json
from decimal import Decimal
from datetime import datetime

def prepare_chart_data(raw_data):
    return {
        "dates": [d.strftime("%Y-%m-%d") for d in raw_data["dates"]],
        "values": [float(v) for v in raw_data["values"]]
    }

这样模板里直接 {{ chart_data | tojson }} 就安全了。

3.4 整体流程：一张图说清楚

我把报表模板设计的核心流程画成了一张图，你看一眼就明白了。

这张图把整个流程串起来了。从结构设计开始，到模板引擎选择，再到动态表格和图表占位符，最后渲染输出。每一步都有明确的输入和输出。

我的经验：刚开始做的时候，别急着写代码。先把结构图画出来，跟团队过一遍。我曾经有一次直接上手写模板，写到一半发现结构不合理，全部推翻重来。嗯，从那以后，我都是先画图再写码。

好了，报表模板设计这块，核心就是这些。记住：结构先行，模板引擎选对，动态内容用占位符兜底。做到这三点，你的报表模板就能稳定跑起来，不会动不动就崩。